Create a wallet top-up payment link
Create a USD payment link for a customer to fund their wallet.
Create a link, share the returned data.checkout_url with the customer, and let them pay through the selected gateway. This creates a real pending charge. The wallet balance changes only after payment completes.
The customer must belong to your selected store. Both wallet:write and charge API-key abilities and both store permissions are required. Wallets must be enabled, and frozen wallets cannot receive top-ups. Store amount limits and allowed wallet payment methods apply.
Use data.charge_id with Retrieve a charge to check progress. For custom payments, proof submission moves the charge to REVIEW; approve it only after independently verifying receipt of funds. A browser return is not payment confirmation. Completion credits the exact deposit plus any bonus saved when you created the link.
Send a stable Idempotency-Key. Repeat the same request with the same key to recover the response within 24 hours. A different request with that key returns 409. After an uncertain provider failure, inspect charges before creating another link.
Create the link
Set your API credentials and store using the quickstart. Replace 42 with an existing customer ID in that store, and choose an idempotency key for this one top-up. This request creates a real pending charge; it does not collect money immediately.
export CUSTOMER_ID=42
export TOPUP_KEY="topup-customer-42-001"
curl --request POST "${SELLAPP_API_BASE_URL}/v2/wallets/${CUSTOMER_ID}/top-ups" \
--header "Authorization: Bearer ${SELLAPP_API_KEY}" \
--header "X-STORE: ${SELLAPP_STORE}" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: ${TOPUP_KEY}" \
--data '{"amount_cents":2500,"payment_method":"STRIPE"}'Share the returned data.checkout_url. Keep data.charge_id to check payment status. If Stripe is unavailable for wallet top-ups, choose a method enabled in the store's wallet settings. The CLI guide shows the corresponding terminal command.
Provide your SellApp API key as a bearer token.
In: header
Path Parameters
Header Parameters
Reuse this key only for an identical retry. A replay returns Idempotent-Replayed: true.
1 <= length <= 255Store slug. Required for OAuth access tokens. API keys may omit it to use their current store, or the first accessible store when no current store is selected.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://sell.app/api/v2/wallets/42/top-ups" \ -H "Idempotency-Key: project-library-2026-09-04" \ -H "X-STORE: launch-lab" \ -H "Content-Type: application/json" \ -d '{ "amount_cents": 2500, "payment_method": "STRIPE" }'{
"data": {
"charge_id": 987654321,
"amount_cents": 2500,
"currency": "USD",
"checkout_url": "https://cedar-studio.sell.app/charge/987654321",
"payment_method": "STRIPE",
"custom_payment_method_id": null
}
}{
"type": "invalid_request_error",
"code": "bad_request",
"message": "The request could not be understood.",
"status": 400,
"param": null,
"request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
"docs_url": "https://sell.app/docs/api/errors#bad-request"
}{
"type": "authentication_error",
"code": "unauthenticated",
"message": "Unauthenticated.",
"status": 401,
"param": null,
"request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
"docs_url": "https://sell.app/docs/api/errors#unauthenticated"
}{
"type": "authorization_error",
"code": "forbidden",
"message": "This action is unauthorized.",
"status": 403,
"param": null,
"request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
"docs_url": "https://sell.app/docs/api/errors#forbidden"
}{
"type": "not_found_error",
"code": "resource_not_found",
"message": "Not Found.",
"status": 404,
"param": null,
"request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
"docs_url": "https://sell.app/docs/api/errors#resource-not-found"
}{
"type": "conflict_error",
"code": "conflict",
"message": "The resource state changed before this request.",
"status": 409,
"param": null,
"request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
"docs_url": "https://sell.app/docs/api/errors#conflict"
}{
"type": "validation_error",
"code": "validation_failed",
"message": "The selected product variant id is invalid.",
"status": 422,
"param": "product_variant_id",
"request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
"docs_url": "https://sell.app/docs/api/errors#validation-failed",
"errors": {
"product_variant_id": [
"The selected product variant id is invalid."
]
}
}{
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Too Many Attempts.",
"status": 429,
"param": null,
"request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
"docs_url": "https://sell.app/docs/api/errors#rate-limit-exceeded"
}{
"type": "api_error",
"code": "api_error",
"message": "Server Error",
"status": 500,
"param": null,
"request_id": "01992a65-e064-71ba-b38f-902b7966a6be",
"docs_url": "https://sell.app/docs/api/errors#api-error"
}