Create a payment

Creates a payment for one of your orders and returns the link to the payment page. Create one per order: reference is your order number.

POST /api/v1/payments

Request

POST /api/v1/payments
X-Api-Key: <your API key>
Content-Type: application/json

{
  "reference": "ORDER-8841",
  "amount": "215.50",
  "currency": "EUR",
  "callbackUrl": "https://shop.example.com/api/payments/callback",
  "successUrl": "https://shop.example.com/thanks",
  "cancelUrl": "https://shop.example.com/cart",
  "billingDetails": {
    "email": "customer@example.com"
  },
  "customer": {
    "ip": "203.0.113.9"
  }
}

Field	Required	Description
reference	yes	Your order number, up to 64 characters. Comes back in the callback and the order's status.
amount	yes	The amount in currency units, as a number or a string: 215.50, "215.50", 1500 for JPY. No more decimals than the currency has; at most 10 000 USD.
currency	yes	ISO code: EUR, USD, …
callbackUrl	yes	Where we send the callbacks for this order. A public https address.
billingDetails.email	yes	The customer's email. Prefills the payment page.
successUrl	no	Where the customer returns after paying.
cancelUrl	no	Where the customer returns after cancelling.
customer.ip	recommended	The customer's IP, not your server's. Needed if your account takes customers only from some countries.
customer.userAgent	no	The customer's browser User-Agent.
customer.language	no	The customer's Accept-Language.
customer.deviceId	no	Your browser fingerprint of the customer, if you have one.
billingDetails.name, .phone	no	Kept with the customer's record.
billingDetails.address	no	line1, city, state, postal_code, country (2 letters). Kept with the customer's record.

Response

{
  "ok": true,
  "orderId": "4f0c2a8e-…",
  "accountId": "stripe-1",
  "paymentUrl": "https://checkout.stripe.com/c/pay/cs_live_…",
  "amount": "215.50",
  "amountMinor": 21550,
  "currency": "EUR",
  "reused": false
}

Field	Description
orderId	Our id of the order.
paymentUrl	The payment page. Send the customer there.
amount, amountMinor	The amount in units ("215.50") and in minor units (21550).
reused	true when this is the order's link you already got.

The same reference again

A reference is one order, with one open payment link at a time. Asking again for the same reference is safe:

When	You get
Same amount, the link is still open	200, the same link, reused: true. A double click or a retry is harmless.
The link has expired	200, a new link for the same order.
The amount or currency changed, the order is unpaid	200, a new link. The old one is closed.
The order is paid	409 order_already_paid

A refused request (any error) creates nothing: for a new reference there is no order, and an existing order keeps its link.

Check the amount in the callback

If the customer pays an old link a moment before it is replaced, the order is paid with the old amount. Compare the callback's amount with your order.