Top up your balance
Add dollars to your open.sume.com balance with your API key.
POST /v1/open/top-ups
Host https://api.open.sume.com · Auth your open.sume.com API key
Starts a top-up of the balance your key is billed to. It is the same top-up as Add funds on the Billing page: you get a Stripe Checkout link, the payment happens there, and the balance grows once it is paid. A team key tops up the team's balance.
Send an Idempotency-Key. A retry with the same key returns the same top-up and the same checkout link, so a dropped connection never leads to a second payment. Reusing a key for a different amount fails with 409 idempotency_conflict.
Request
Headers
| Name | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <your open.sume.com API key> |
Idempotency-Key | Recommended | Up to 255 characters. One key, one top-up. |
Body
| Name | Type | Required | Description |
|---|---|---|---|
amount_usd_cents | integer | Yes | Dollars to add, in cents. 2000 is $20. From 500 ($5) to 1000000 ($10,000). |
success_url | string | No | Where the payer lands after paying (https). Defaults to the Billing page. |
cancel_url | string | No | Where the payer lands on cancel (https). Defaults to the Billing page. |
Example
Open checkout_url in a browser and pay. Then poll Get a top-up until status is paid.
Response
201 Created, or 200 OK for a retry with the same Idempotency-Key.
status | Meaning |
|---|---|
pending | The checkout is open and not paid yet. |
paid | Paid; the dollars are in your balance. |
failed | The payment failed. Nothing was charged. |
expired | The checkout closed unpaid. Start a new top-up with a new Idempotency-Key. |
Errors
| Status | code | When |
|---|---|---|
| 400 | invalid_amount | The amount is under $5 or over $10,000, or not whole cents. |
| 400 | invalid_request | A return URL is not https, or the Idempotency-Key is not 1 to 255 printable characters. |
| 403 | open_key_required | The key is not an open.sume.com key. |
| 409 | idempotency_conflict | The Idempotency-Key was used for a different amount. |
| 502 | stripe_error | Stripe could not open the checkout. Retry with the same Idempotency-Key. |
| 503 | stripe_not_configured | Top-ups are not available in this environment. |