BillKitCheckout
Create one-shot payment
Charge an existing customer once, with no subscription and no stored mandate.
POST/v1/checkout/one_shot
Parameters
| Parameter | Description |
|---|---|
| amount_centsintegerrequired | Amount in minor units of currency. Gross or net according to tax_behavior; the response's amount_cents is what is actually charged. Maximum 99999999. |
| currencystringrequired | Three-letter ISO 4217 currency code. Case-insensitive; stored uppercase. At most 3 characters. |
| customer_idstringrequired | Id of the customer being charged. At most 64 characters. |
| success_urlstring (uri)required | Where the payer is sent after the payment. Must be an absolute URL. At most 2083 characters. |
| cancel_urlstring (uri) | nulloptional | Where the payer is sent if they leave without paying. Optional. Must be an absolute URL. At most 2083 characters. |
| descriptionstring | nulloptional | What is being paid for. Shown on the payment page and the payer's bank statement, and used as the invoice line. At most 255 characters. |
| metadataobject | nulloptional | Key-value pairs stored on the payment and echoed on it and its events. At most 50 keys. |
| payment_methodenum | nulloptional | The payment method to charge with, checked against the methods your account can accept in this currency. Required when ui_mode is hosted; must be omitted when it is embedded, where the buyer picks the method. One of creditcard, ideal, bancontact, eps, applepay, paypal, banktransfer. |
| refund_window_daysinteger | nulloptional | Days after the payment settles during which it can be refunded. Null uses the default of 30 days; 0 disables refunds. Between 0 and 365. |
| tax_behaviorenum | nulloptional | inclusive: amount_cents includes VAT. exclusive: VAT is added on top of amount_cents. Null uses the default of the tax rate for the customer's country. One of inclusive, exclusive. |
| ui_modeenumoptional | hosted creates the payment now and returns a redirect_url for the payer. embedded creates no payment yet and returns a client_secret for the embedded payment element. One of hosted, embedded. Defaults to "hosted". |
Returns
Returns an OneShotPaymentResponse object.
Errors
| Status | Cause |
|---|---|
| 400 | The request was refused (type: invalid_request_error): a required parameter is missing (parameter_missing), one failed validation (parameter_invalid) or is not one the operation takes (parameter_unknown), and param names it. |
| 401 | No credential, or one that does not authenticate. |
| 402 | The account is suspended (tenant_suspended), or the payment provider refused a charge or refund the call made (type: payment_error, code: payment_refused). |
| 403 | Authenticated, but not allowed: missing scope (insufficient_scope), a key of the wrong mode (mode_mismatch), or a refused origin. Needs the checkout_sessions:write scope. |
| 404 | No such object in this account and mode. |
| 409 | Conflicts with the object's current state (state_conflict, or a more specific code), or an operation still in flight (operation_pending). |
| 413 | The request body is larger than the API accepts. |
| 429 | Rate limited. Retry-After says when to try again. |
| 500 | Something failed on BillKit's side (type: api_error). Retry with the same Idempotency-Key. |
| 502 | The payment provider failed or did not answer. |
| 503 | Temporarily unable to serve. reason says whether the request was attempted. |
Other checkout operations
- List one shots GET /v1/checkout/one_shot
- Get one-shot payment GET /v1/checkout/one_shot/{one_shot_id}
- Create a Checkout session POST /v1/checkout/sessions
- Get checkout session GET /v1/checkout/sessions/{checkout_id}