Create a payment

Creates a payment. For a card without a PAN in the request, a one-time client_secret is returned; the hosted-fields SDK collects the card client-side and submits it against that secret (the card never touches the API, SAQ A-EP). Sending payment_method.card_data charges the card server-to-server (SAQ D) — device.ip is then required for risk scoring. wallet/APM payments return a redirect_url the client follows; pay_by_bank returns the hosted form url where the payer picks their bank. capture_mode automatic (default) authorizes and captures; manual authorizes only.

Authorization

ApiKey

X-Api-Key<token>

Merchant API key for authentication

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount*integer

Amount to charge, in the currency's minor units (e.g. 1000 = €10.00).

Range0 < value

currency*string

ISO 4217 three-letter currency code, e.g. EUR.

Length3 <= length <= 3

reference*string

Your unique reference for this payment (order id). Returned on every event.

Length1 <= length <= 191

capture_mode?string

automatic (default) authorizes and captures; manual authorizes only — capture later via POST /payments/{id}/capture.

Value in

"automatic"
"manual"

return_url?string

URL to return to after a redirect flow.

Formaturi

Lengthlength <= 500

cancel_url?string

URL to return to on cancel.

Formaturi

Lengthlength <= 500

webhook_url?string

Per-payment webhook URL (https), in addition to dashboard webhooks.

Formaturi

Lengthlength <= 500

customer?

Customer details.

device?

Payer device/session signals for risk scoring. device.ip is required for a direct card charge (payment_method.card_data); optional otherwise.

payment_method?

Payment method. type selects the method (default card); provide card_data for a direct server-to-server charge, or omit it for the hosted-fields flow (a client_secret is returned).

setup_future_usage?"off_session"

Set to off_session to store the card for later merchant-initiated charges (rebilling). The stored token is returned as payment_method.token once the payment succeeds.

Value in

"off_session"

off_session?boolean

Set to true for a merchant-initiated charge on a stored payment_method.token (the customer is not present — no CVV, SCA exemption applies).

interactive?boolean

Set to true if you can redirect the payer's browser. When the card turns out to be eligible for a currency conversion (DCC), the payment is created pending with an action_url instead of being charged straight away: send the payer there to choose their currency, then wait for the webhook. Without it — or when no conversion applies — the card is charged immediately in your own currency, exactly as before.

metadata?

Arbitrary key/value pairs echoed back on the payment and its events.

Response Body

`application/json`

curl -X POST "https://example.com/payments" \  -H "Content-Type: application/json" \  -d '{    "amount": 1000,    "currency": "EUR",    "reference": "order_12345",    "capture_mode": "automatic",    "payment_method": {      "type": "card"    },    "customer": {      "reference": "cus_9f8e7d",      "email": "buyer@example.com",      "billing_address": {        "line1": "1 rue de Rivoli",        "city": "Paris",        "postal_code": "75001",        "country": "FR"      }    },    "metadata": {      "orderId": "12345"    }  }'

{  "id": "pr_a1b2c3d4e5f6",  "amount": 1000,  "currency": "EUR",  "status": "pending",  "capture_mode": "automatic",  "authorized_amount": 0,  "captured_amount": 0,  "refunded_amount": 0,  "disputed_amount": 0,  "used_method_family": null,  "used_method_type": null,  "reference": "order_12345",  "customer": {    "reference": "cus_9f8e7d",    "email": "buyer@example.com"  },  "metadata": {    "orderId": "12345"  },  "client_secret": "pr_a1b2c3d4e5f6_secret_9f8e7d6c5b4a3210",  "redirect_url": null,  "created_at": "2026-07-17T10:00:00.000Z",  "updated_at": "2026-07-17T10:00:00.000Z"}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`