Sign in
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"
  }
}

Changes

Changed in 3 of the 8 revisions of this API.736

  • b372e7d5563d635See the full diff
    • ▲

      the billingAddress/country request property's minLength was increased from 0 to 2

      request-property-min-length-increased

    • ▲

      the currency request property's minLength was increased from 0 to 3

      request-property-min-length-increased

    • ▲

      added the pattern ^[A-Za-z]{2}$ to the request property billingAddress/country

      request-property-pattern-added

    • ▲

      added the pattern ^[A-Za-z]{3}$ to the request property currency

      request-property-pattern-added

    • ▲

      the error/code response's property type/format changed from string/ to / for status 400

      response-property-type-changed

    • ▲

      removed the success response with the status 201

      response-success-status-removed

    • ●

      the billingAddress/country request property's maxLength was set to 2

      request-property-max-length-set

    • ●

      the currency request property's maxLength was set to 3

      request-property-max-length-set

    • ●

      removed the optional property error/errors from the response with the 400 status

      response-optional-property-removed

    • ○

      added the new optional request property merchant_id

      new-optional-request-property

    • ○

      added the new optional request property simulation

      new-optional-request-property

    • ○

      added the optional property error/metadata to the response with the 400 status

      response-optional-property-added

    • ○

      added subschema #1 subschema #2 to the error/code response property allOf list for the response status 400

      response-property-all-of-added

    • ○

      added the success response with the status 200

      response-success-status-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 6637b341d86d1See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 919eb7a392aa1See the full diff
    • ▲

      api path removed without deprecation

      api-path-removed-without-deprecation

    This revision also has 367 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog