Skip to main content
POST
/
payments
Create a payment
curl --request POST \
  --url https://api.sandbox.primer.io/payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "orderId": "order-abc",
  "currencyCode": "EUR",
  "amount": 42,
  "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
  "customerId": "customer-123",
  "customer": {
    "emailAddress": "customer123@gmail.com"
  },
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  },
  "paymentMethod": {
    "vaultOnSuccess": true
  }
}
'
{
  "id": "kHdEw9EG",
  "date": "2021-02-21T15:36:16.367687",
  "status": "AUTHORIZED",
  "orderId": "order-abc",
  "currencyCode": "EUR",
  "amount": 42,
  "customerId": "customer-123",
  "customer": {
    "email": "customer123@gmail.com"
  },
  "paymentMethod": {
    "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
    "isVaulted": true,
    "descriptor": "Purchase: Socks",
    "analyticsId": "VtkMDAxZW5isH0HsbbNxZ3lo",
    "paymentMethodType": "PAYMENT_CARD",
    "paymentMethodData": {
      "first6Digits": "411111",
      "last4Digits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "cardholderName": "John Biggins",
      "network": "Visa",
      "isNetworkTokenized": false,
      "binData": {
        "network": "VISA",
        "regionalRestriction": "UNKNOWN",
        "accountNumberType": "UNKNOWN",
        "accountFundingType": "UNKNOWN",
        "prepaidReloadableIndicator": "NOT_APPLICABLE",
        "productUsageType": "UNKNOWN",
        "productCode": "VISA",
        "productName": "VISA"
      }
    }
  },
  "processor": {
    "name": "STRIPE",
    "processor_merchant_id": "acct_stripe_1234",
    "amountCaptured": 0,
    "amountRefunded": 0
  },
  "transactions": [
    {
      "type": "SALE",
      "processorStatus": "AUTHORIZED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a"
    }
  ],
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  }
}

Authorizations

​
X-API-KEY
string
header
required

Headers

​
X-Idempotency-Key
string

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.

Body

application/json
​
paymentMethodToken
string
required

The payment method token used to authorize the payment.

​
orderId
string

Your reference for the payment.

​
currencyCode
string

The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.

​
amount
integer<int64>

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.

Required range: x >= 0
​
order
Order Details · object

More information associated with the order.

​
customerId
string

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

​
customer
Customer Details · object

More information associated with the customer.

​
metadata
Payment Metadata · object

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

​
paymentMethod
Payment Method Options · object

Enable certain options associated with the payment method.

Response

Successful Response

​
id
string

The unique payment ID.

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

​
date
string<date-time>

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

​
status
enum<string>

See the payment status table for more information.

Available options:
PENDING,
FAILED,
AUTHORIZED,
SETTLING,
PARTIALLY_SETTLED,
SETTLED,
DECLINED,
CANCELLED
​
orderId
string

Your reference for the payment.

​
currencyCode
string

The 3-letter currency code in ISO 4217 format. e.g. use USD for US dollars.

​
amount
integer<int64>

The amount you charged the customer, in minor units.

Required range: x >= 0
​
order
Order Details · object

More information associated with the order.

​
customerId
string

The unique identifier for your customer.

​
customer
Customer Details · object

More information associated with the customer.

​
metadata
Payment Metadata · object

Additional data to be used throughout the payment lifecycle.

​
paymentMethod
Payment Method Options · object

The payment method options provided in the request, as well as the token used to process the payment.

​
processor
Processor Information · object

More information associated with the payment processor, including the processor name.

​
requiredAction
Required action · object

Required action to perform in order to resume the payment workflow. This can be requiring a 3DS check from the customer for instance.

​
statusReason
Status Reason · object

Check this field for more information regarding the payment's status. This is especially useful when the status is DECLINED or FAILED.

​
transactions
TransactionOverviewAPISchema · object[]

A list summarizing the transactions that occurred while processing the payment.

Note: a refund is a separate transaction and so will appear in this transactions list if a refund was performed.