Payments API

Create a payment

Changed on Sep 30, 2026

Create and authorize a payment for a given customer order. You should provide a payment method token here to avoid PCI implications. If only a payment method token is passed, the values passed with the Client Session is used to determine the amount, currency etc. Note: `amount`, `currencyCode` and `orderId` are required during payment creation. Make sure to pass these fields when creating a client session, or if not yet available, when creating a payment. All fields provided on this request will take preference over any field on the `order` associated with the client session. E.g. if you pass `amount` on this request, it will override the `amount` on the `order` associated with the Client Session. Parameters that are not on this request will be fetched from previously created Client Session and merged. E.g. if you specify `customer.billingAddress` in Client Session and then pass `customer.emailAddress` data with this request, it will automatically merge the `customer` fields and use both `billingAddress` and `emailAddress` for later calculations.

post/payments

Request

Base URL
https://api.sandbox.primer.io
URL
https://api.sandbox.primer.io/payments
Auth
API key in header X-API-KEY

Headers

X-Idempotency-Keystring

Optional key to make the request idempotent. Enables a safe retry of a request without risking the user being charged or refunded multiple times. The idempotency key must be generated by the client and needs to be unique for every new request.

X-API-VERSIONstring required

Example:2.4

Specifies the version of the API to use. This must be set to 2.4.

Request body

orderIdstring

Your reference for the payment.

currencyCode'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYR' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'UYU' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XCD' | 'XCG' | 'XOF' | 'XPF' | 'YER' | 'ZAR' | 'ZMW' | 'ZWG' | 'ZWL'

3-letter currency code in <a href='https://en.wikipedia.org/wiki/ISO_4217#Active_codes'>ISO 4217</a> format, e.g. <code>USD</code> for US dollars.

The following currencies have been retired and will return a deprecation error on new payment or session creation requests: BGN, ZWL, ANG

amountinteger

The amount you would like to charge the customer, in minor units. e.g. for $7, use 700.

Some currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for ¥100, use 100. The minimum amount is 0. The maximum amount is the limit of int64.

paymentMethodTokenstring required

The payment method token used to authorize the payment. Tokens contain only letters, digits, _ and -.

customerIdstring

A unique identifier for your customer. This attribute is required if paymentMethod.vaultOnSuccess or paymentMethod.vaultOn3DS is set to true.

metadataobject

Additional data to be used throughout the payment lifecycle.

A dictionary of key-value pairs where the values can only be strings or integers.

e.g. {"productId": 1001, "merchantId": "a13bsd62s"}

The size of metadata must not exceed 300 KB (307,200 bytes) when serialized as JSON. Larger payloads are rejected with a PaymentMetadataSizeExceeded error.

expandstring[] nullable

A list of fields to expand, such as transactions.events.

Example request

{
  "orderId": "order-abc",
  "currencyCode": "EUR",
  "amount": 42,
  "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
  "customerId": "customer-123",
  "customer": {
    "emailAddress": "customer123@gmail.com"
  },
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  },
  "paymentMethod": {
    "paymentType": "SUBSCRIPTION",
    "vaultOnSuccess": true,
    "authorizationType": "ESTIMATED"
  }
}

Response

Successful Response

idstring required

The unique payment ID.

You can use this ID to retrieve the payment details, or perform downstream operations.

datestring date-time required

The date and time at which the payment was created in UTC format.

dateUpdatedstring date-time required

The date and time of the last payment update in UTC format.

An enumeration.

cardTokenType'CARD_PAN' | 'NETWORK_TOKEN' | 'PROCESSOR_TOKEN'

An enumeration.

orderIdstring required

Your reference for the payment.

3-letter currency code in <a href='https://en.wikipedia.org/wiki/ISO_4217#Active_codes'>ISO 4217</a> format, e.g. <code>USD</code> for US dollars.

The following currencies have been retired and will return a deprecation error on new payment or session creation requests: BGN, ZWL, ANG

amountinteger required

The amount you charged the customer, in minor units.

customerIdstring

The unique identifier for your customer.