Direct payment API
Show the methods in your own picker and start the payment for the one the buyer picks. The buyer never sees a method picker from the gateway. The payment object, the statuses, the webhooks and the cancel are the same as for the hosted checkout.
On this page
Three calls
- Create the payment:
POST /v1/payments, as for the hosted checkout. It iscreated. - List the methods for its amount:
GET /v1/payment-methods. - Select the method the buyer picked:
POST /v1/payments/{id}/method. The answer is the payment plusnext_action, which says what your site shows or does next.
Creating and selecting are two calls on purpose, so each can be retried on its own.
If you do not need your own picker, the hosted checkout is simpler.
List the methods
curl -sS "https://payments.example.com/api/v1/payment-methods?currency=EUR&amount=49.00" \
-H "Authorization: Bearer cp_test_..."{
"object": "list",
"data": [
{
"object": "payment_method",
"code": "mollie:ideal",
"gateway": "mollie",
"label": "iDEAL",
"logo_url": "https://payments.example.com/method-logos/mollie-ideal.svg",
"charge_currency": null
},
{
"object": "payment_method",
"code": "mollie:swish",
"gateway": "mollie",
"label": "Swish",
"logo_url": null,
"charge_currency": "SEK"
}
]
}currency(EURorUSD) andamountare required.- Show
labelandlogo_url(absolute, ornullwhen there is no logo). Sendcodeback asmethod. gatewaygroups the methods of one provider; some providers offer many local methods.charge_currencyis set when the buyer is charged in a local currency (PLN, CHF, SEK or NOK).- The list holds the methods enabled for your account and mode for that amount. An empty list means none is enabled.
Select the method
curl -sS -X POST https://payments.example.com/api/v1/payments/pay_0123456789abcdefghjkmnpq/method \
-H "Authorization: Bearer cp_test_..." \
-H "Content-Type: application/json" \
-d '{ "method": "mollie:ideal" }'The body is method (a code from the list) and, optionally, expected_provider_amount: the local-currency amount in minor units that you quoted the buyer, for example "5423" for 54.23 SEK. If the amount the gateway computes differs, the call is refused with 409 rate_changed, so the buyer never pays a different amount from the one you showed. It is ignored for a method without a charge_currency.
{
"id": "pay_0123456789abcdefghjkmnpq",
"object": "payment",
"status": "pending",
"method": "mollie:ideal",
"next_action": {
"type": "redirect",
"redirect_url": "https://pay.example.com/ideal/0f3c9a"
}
}Selecting is idempotent by method: the same method again returns the stored next_action without calling the provider again, so a retry after a timeout is safe. Another method on a payment that already has one answers 409 already_selected.
Next actions
next_action.type says what to show. Store the next_action with the payment.
| type | Fields | What your site does |
|---|---|---|
redirect | redirect_url | Send the buyer to redirect_url, an https page of the provider, in the same window. The buyer comes back to your return_url. |
crypto | coin, amount, address, uri, expires_at | Show uri as a QR code, with the coin, the amount (in coin units, exactly as given), the address and the expiry. |
bank_transfer | bank_name, iban, bic, reference, redirect_url | Show the bank details and the amount. The reference must be quoted exactly. redirect_url, when present, is the provider’s instructions page: offer it as a link. |
none | none | Test mode only: nothing to show. Finish the payment on <checkout_url>/simulate. |
Some methods issue a reference or a voucher the buyer pays at a shop or an ATM (such as Multibanco). For those only a redirect is returned: the reference is on the provider’s page, not in next_action.
Errors when selecting
| HTTP | code | What to do |
|---|---|---|
| 409 | already_selected | Another method was chosen. Keep the stored next_action; to change, start a new payment. |
| 409 | selection_in_progress | A start for this payment is running. Wait for Retry-After and send the same call again. |
| 409 | not_selectable | The payment is no longer open (canceled or already paid). Read it with GET. |
| 409 | expired | The payment has expired. Create a new one. |
| 409 | billing_required | An invoiced payment needs billing details, which only the hosted checkout takes. Send the buyer to checkout_url. |
| 409 | details_required | The method needs buyer details this call does not take. Send the buyer to checkout_url. |
| 409 | country_unsupported | The method is not available for the buyer’s country. Offer another method. |
| 409 | rate_changed | The exchange rate moved since your quote. Read the payment again (provider_charge) or retry without expected_provider_amount. |
| 422 | method_unavailable | The method cannot be used for this payment. List the methods again or offer another one. |
| 422 | amount_too_small | The amount is too small for this method. Offer another one. |
| 502 | provider_error | The provider could not be reached. Nothing was selected; repeat after Retry-After. |
| 503 | gateway_not_configured | The method is not available right now. Retry after Retry-After, or offer another method. |
Confirming the payment
next_action tells the buyer what to do; it does not tell you that the money arrived. Act on the payment.paid webhook and confirm with GET /v1/payments/{id}. Do not ship an order on the redirect or on the bank details alone.