Create a payment

curl --request POST \
  --url https://api.sandbox.primer.io/payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-VERSION: <x-api-version>' \
  --data '
{
  "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"
  }
}
'

{
  "id": "kHdEw9EG",
  "date": "2021-02-21T15:36:16.367687",
  "dateUpdated": "2021-02-21T15:36:17.133701",
  "status": "AUTHORIZED",
  "orderId": "order-abc",
  "currencyCode": "EUR",
  "amount": 42,
  "customerId": "customer-123",
  "customer": {
    "email": "customer123@gmail.com"
  },
  "cardTokenType": "CARD_PAN",
  "paymentMethod": {
    "paymentType": "SUBSCRIPTION",
    "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
    "isVaulted": true,
    "authorizationType": "FINAL",
    "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",
    "processorMerchantId": "acct_stripe_1234",
    "amountCaptured": 0,
    "amountRefunded": 0
  },
  "transactions": [
    {
      "type": "SALE",
      "processorStatus": "AUTHORIZED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a",
      "cardTokenType": "CARD_PAN"
    }
  ],
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  },
  "riskData": {
    "fraudChecks": {
      "source": "FRAUD_PROVIDER",
      "preAuthorizationResult": "THREE_DS",
      "postAuthorizationResult": "ACCEPT"
    },
    "cvvCheck": {
      "source": "PROCESSOR",
      "result": "MATCHED"
    },
    "avsCheck": {
      "source": "PROCESSOR",
      "result": {
        "streetAddress": "NOT_MATCHED",
        "postalCode": "NOT_VERIFIED"
      }
    }
  }
}

Create a payment

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

Create a payment

curl --request POST \
  --url https://api.sandbox.primer.io/payments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --header 'X-API-VERSION: <x-api-version>' \
  --data '
{
  "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"
  }
}
'

{
  "id": "kHdEw9EG",
  "date": "2021-02-21T15:36:16.367687",
  "dateUpdated": "2021-02-21T15:36:17.133701",
  "status": "AUTHORIZED",
  "orderId": "order-abc",
  "currencyCode": "EUR",
  "amount": 42,
  "customerId": "customer-123",
  "customer": {
    "email": "customer123@gmail.com"
  },
  "cardTokenType": "CARD_PAN",
  "paymentMethod": {
    "paymentType": "SUBSCRIPTION",
    "paymentMethodToken": "heNwnqaeRiqvY1UcslfQc3wxNjEzOTIxNjc4",
    "isVaulted": true,
    "authorizationType": "FINAL",
    "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",
    "processorMerchantId": "acct_stripe_1234",
    "amountCaptured": 0,
    "amountRefunded": 0
  },
  "transactions": [
    {
      "type": "SALE",
      "processorStatus": "AUTHORIZED",
      "processorName": "STRIPE",
      "processorMerchantId": "acct_stripe_1234",
      "processorTransactionId": "54c4eb5b3ef8a",
      "cardTokenType": "CARD_PAN"
    }
  ],
  "metadata": {
    "productId": 123,
    "merchantId": "a13bsd62s"
  },
  "riskData": {
    "fraudChecks": {
      "source": "FRAUD_PROVIDER",
      "preAuthorizationResult": "THREE_DS",
      "postAuthorizationResult": "ACCEPT"
    },
    "cvvCheck": {
      "source": "PROCESSOR",
      "result": "MATCHED"
    },
    "avsCheck": {
      "source": "PROCESSOR",
      "result": {
        "streetAddress": "NOT_MATCHED",
        "postalCode": "NOT_VERIFIED"
      }
    }
  }
}

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.

X-API-VERSION

string

required

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

Example:

"2.4"

Body

application/json

paymentMethodToken

string

required

The payment method token used to authorize the payment.

orderId

string

Your reference for the payment.

Maximum string length: 256

currencyCode

enum<string>

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

Available options:

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,

MRO,

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,

SOS,

SRD,

SSP,

SVC,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VND,

VUV,

WST,

XAF,

XAG,

XAU,

XBA,

XBB,

XBC,

XBD,

XCD,

XDR,

XFU,

XOF,

XPD,

XPF,

XPT,

XSU,

XTS,

XUA,

YER,

ZAR,

ZMW,

ZWL

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.

Show child attributes

customerId

string

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

Maximum string length: 256

customer

Customer Details · object

More information associated with the customer.

Show child attributes

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.

Show child attributes

expand

enum<string>[] | null

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

Available options:

transactions.events

Response

Successful Response

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.

dateUpdated

string<date-time>

The date and time of the last payment update 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

cardTokenType

enum<string>

The type of card token used for the payment.

Only applies for card payments.

Available options:

CARD_PAN,

NETWORK_TOKEN,

PROCESSOR_TOKEN

Example:

"CARD_PAN"

orderId

string

Your reference for the payment.

Maximum string length: 256

currencyCode

enum<string>

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

Available options:

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,

MRO,

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,

SOS,

SRD,

SSP,

SVC,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VND,

VUV,

WST,

XAF,

XAG,

XAU,

XBA,

XBB,

XBC,

XBD,

XCD,

XDR,

XFU,

XOF,

XPD,

XPF,

XPT,

XSU,

XTS,

XUA,

YER,

ZAR,

ZMW,

ZWL

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.

Show child attributes

customerId

string

The unique identifier for your customer.

Maximum string length: 256

customer

Customer Details · object

More information associated with the customer.

Show child attributes

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.

Show child attributes

processor

Processor Information · object

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

Show child attributes

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.

Show child attributes

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.

Show child attributes

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.

Show child attributes

riskData

Risk Data · object

Risk data associated with this payment.

Show child attributes

Search & list payments Authorize a payment

⌘I

API reference

Authorizations

Headers

Body

Response