Create a payment session

Creates a hosted payment session and returns a client_secret (embedded hosted fields — SAQ A-EP), a hosted_page_url (our hosted payment page — SAQ A) and an expires_at. The customer completes the payment on either surface; capture/void/refund and webhooks are shared with /v2/payments/{id}.

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/payment-sessions" \  -H "Content-Type: application/json" \  -d '{    "amount": 1000,    "currency": "EUR",    "reference": "order_12345",    "capture_mode": "automatic",    "payment_method": {      "type": "card"    },    "customer": {      "email": "buyer@example.com"    }  }'

{  "id": "string",  "amount": 1,  "currency": "str",  "status": "created",  "capture_mode": "automatic",  "authorized_amount": 0,  "captured_amount": 0,  "refunded_amount": 0,  "disputed_amount": 0,  "used_method_family": "string",  "used_method_type": "string",  "payment_method": {    "type": "string",    "token": "string"  },  "dcc": {    "currency": "str",    "amount": 0  },  "reference": "string",  "description": "string",  "customer": {    "reference": "string",    "email": "string"  },  "metadata": {    "property1": null,    "property2": null  },  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "client_secret": "string",  "redirect_url": "string",  "hosted_page_url": "string",  "action_url": "string",  "expires_at": "2019-08-24T14:15:22Z"}

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`