Sign in

v1

latestOpenAPI 3.1.02026-07-132363652.9 MB
Payments

Create a new payment request

Create a new payment request

post/api/v1/payment-requests

Request body

merchant_idstring uuid

Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.

amountnumber required

Decimal amount in MAJOR units (e.g. 19.99 = £19.99). Sent as a number and converted to minor units server-side. This differs from the redirect and embedded endpoints, which take an integer amount in minor units.

currencystring required

The currency of the payment request

payment_referencestring

Payment reference to appear on the payer’s bank statement (max 18 alphanumeric characters)

order_idstring

The unique identifier for the merchant's order

localestring required

The locale of the payment request

platformstring required

The platform used for the payment request

device_typestring

The type of device used for the payment request

external_payment_request_idstring

External payment reference

test_transactionboolean

Flag for test transactions

groupstring

For grouping related transactions

gidstring

Global identifier

selected_bank_idstring

Selected bank reference

session_idstring

Session tracking

success_url_redirectstring

URL to redirect on successful payment

fail_url_redirectstring

URL to redirect on failed payment

Example request

{
  "merchant_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone_number": "07123456789"
  },
  "billingAddress": {
    "address_line1": "12 West Common Drive",
    "address_line2": "Flat 1",
    "apartment": "Apt 5B",
    "city": "London",
    "state_province": "Greater London",
    "country": "GB",
    "postal_code": "SE1 1AA",
    "company_name": "Acme Ltd"
  },
  "amount": 19.99,
  "currency": "GBP",
  "payment_reference": "ORDER123",
  "order_id": "1140",
  "locale": "en_GB",
  "platform": "WooCommerce",
  "device_type": "mobile",
  "external_payment_request_id": "u0nwmSrNntjIWozmNslK5Tlq",
  "group": "rZNvy+1jH6Z+BcPqA5U5BSIcnUavBha3C63xBalm+xE=",
  "gid": "gid://shopify/PaymentSession/u0nwmSrNntjIWozmNslK5Tlq",
  "selected_bank_id": "38c39d03-8df3-4980-b0a8-7e283c8c62dd",
  "session_id": "4B2dxmle3vGgimS4deUX3+2PgLF2+/0ZWnNsNSZcgdU=",
  "success_url_redirect": "https://storename.com/success",
  "fail_url_redirect": "https://storename.com/failure"
}

Response

Success

successboolean required

Indicates if the request was successful

Example response

{
  "success": true,
  "data": {
    "payment_link": "https://example.com/pay/abc123"
  }
}