Skip to content
Creative Payments

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

  1. Create the payment: POST /v1/payments, as for the hosted checkout. It is created.
  2. List the methods for its amount: GET /v1/payment-methods.
  3. Select the method the buyer picked: POST /v1/payments/{id}/method. The answer is the payment plus next_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

List payment methodscurl
curl -sS "https://payments.example.com/api/v1/payment-methods?currency=EUR&amount=49.00" \
  -H "Authorization: Bearer cp_test_..."
Response 200JSON
{
  "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 (EUR or USD) and amount are required.
  • Show label and logo_url (absolute, or null when there is no logo). Send code back as method.
  • gateway groups the methods of one provider; some providers offer many local methods.
  • charge_currency is 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

Select a methodcurl
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.

Response 200 (shortened)JSON
{
  "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.

typeFieldsWhat your site does
redirectredirect_urlSend the buyer to redirect_url, an https page of the provider, in the same window. The buyer comes back to your return_url.
cryptocoin, amount, address, uri, expires_atShow uri as a QR code, with the coin, the amount (in coin units, exactly as given), the address and the expiry.
bank_transferbank_name, iban, bic, reference, redirect_urlShow 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.
nonenoneTest 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

HTTPcodeWhat to do
409already_selectedAnother method was chosen. Keep the stored next_action; to change, start a new payment.
409selection_in_progressA start for this payment is running. Wait for Retry-After and send the same call again.
409not_selectableThe payment is no longer open (canceled or already paid). Read it with GET.
409expiredThe payment has expired. Create a new one.
409billing_requiredAn invoiced payment needs billing details, which only the hosted checkout takes. Send the buyer to checkout_url.
409details_requiredThe method needs buyer details this call does not take. Send the buyer to checkout_url.
409country_unsupportedThe method is not available for the buyer’s country. Offer another method.
409rate_changedThe exchange rate moved since your quote. Read the payment again (provider_charge) or retry without expected_provider_amount.
422method_unavailableThe method cannot be used for this payment. List the methods again or offer another one.
422amount_too_smallThe amount is too small for this method. Offer another one.
502provider_errorThe provider could not be reached. Nothing was selected; repeat after Retry-After.
503gateway_not_configuredThe 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.