Payments API

Create a payment

POST
https://api.sandbox.primer.io/payments

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.

Headers

X-Idempotency-Key
optional string

Optional key to make the request idempotent. Learn more in the Idempotency Key guide.

Request

This endpoint expects an object.
paymentMethodToken
string

The payment method token used to authorize the payment.

orderId
optional string

Your reference for the payment.

currencyCode
optional enum

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

amount
optional integer

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.

order
optional object

More information associated with the order.

customerId
optional string

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

customer
optional object

More information associated with the customer.

metadata
optional map from strings to any

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
optional object

Enable certain options associated with the payment method.

Response

This endpoint return an object.
id
optional string

The unique payment ID.

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

date
optional datetime

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

status
optional enum

See the payment status table for more information.

orderId
optional string

Your reference for the payment.

currencyCode
optional enum

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

amount
optional integer

The amount you charged the customer, in minor units.

order
optional object

More information associated with the order.

customerId
optional string

The unique identifier for your customer.

customer
optional object

More information associated with the customer.

metadata
optional map from strings to any

Additional data to be used throughout the payment lifecycle.

paymentMethod
optional object

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

processor
optional object

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

requiredAction
optional 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
optional object

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

transactions
optional list of objects

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.

riskData
optional object

Errors

POST
/payments
1
2
3
4
5
6
7
curl -X POST "https://api.sandbox.primer.io/payments" \
     -H "X-Idempotency-Key: string" \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "paymentMethodToken": "string"
}'
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
{
  "id": "string",
  "date": "2023-01-01T00:00:00Z",
  "status": "PENDING",
  "orderId": "string",
  "currencyCode": "AED",
  "amount": 0,
  "order": {
    "lineItems": [
      {
        "itemId": "string",
        "name": "string",
        "description": "string",
        "amount": 0,
        "quantity": 0,
        "discountAmount": 0,
        "taxAmount": 0,
        "taxCode": "string",
        "productType": "PHYSICAL",
        "productData": {
          "sku": "string",
          "brand": "string",
          "color": "string",
          "globalTradeItemNumber": "string",
          "manufacturerPartNumber": "string",
          "weight": 1,
          "weightUnit": "string"
        }
      }
    ],
    "countryCode": "AW",
    "retailerCountryCode": "AW",
    "fees": [
      {
        "amount": 0,
        "type": "string",
        "description": "string"
      }
    ],
    "shipping": {
      "amount": 0
    }
  },
  "customerId": "string",
  "customer": {
    "emailAddress": "string",
    "mobileNumber": "string",
    "firstName": "string",
    "lastName": "string",
    "billingAddress": {
      "firstName": "string",
      "lastName": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "state": "string",
      "countryCode": "AW",
      "postalCode": "string"
    },
    "shippingAddress": {
      "firstName": "string",
      "lastName": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "state": "string",
      "countryCode": "AW",
      "postalCode": "string"
    },
    "taxId": "string",
    "nationalDocumentId": "string"
  },
  "metadata": {
    "string": {}
  },
  "paymentMethod": {
    "descriptor": "string",
    "paymentType": "FIRST_PAYMENT",
    "paymentMethodToken": "string",
    "isVaulted": true,
    "analyticsId": "string",
    "paymentMethodType": "PAYMENT_CARD",
    "paymentMethodData": {
      "first6Digits": "string",
      "last4Digits": "string",
      "expirationMonth": "string",
      "expirationYear": "string",
      "cardholderName": "string",
      "network": "string",
      "isNetworkTokenized": true,
      "binData": {
        "network": "AMEX",
        "issuerCountryCode": "AW",
        "issuerName": "string",
        "issuerCurrencyCode": "AED",
        "regionalRestriction": "DOMESTIC_USE_ONLY",
        "accountNumberType": "PRIMARY_ACCOUNT_NUMBER",
        "accountFundingType": "CREDIT",
        "prepaidReloadableIndicator": "RELOADABLE",
        "productUsageType": "CONSUMER",
        "productCode": "string",
        "productName": "string"
      }
    },
    "threeDSecureAuthentication": {
      "responseCode": "NOT_PERFORMED",
      "reasonCode": "GATEWAY_UNAVAILABLE",
      "reasonText": "string",
      "protocolVersion": "string",
      "challengeIssued": true
    },
    "authorizationType": "ESTIMATED"
  },
  "processor": {
    "name": "string",
    "processorMerchantId": "string",
    "amountCaptured": 0,
    "amountRefunded": 0
  },
  "requiredAction": {
    "name": "3DS_AUTHENTICATION",
    "description": "string",
    "clientToken": "string"
  },
  "statusReason": {
    "type": "APPLICATION_ERROR",
    "declineType": "SOFT_DECLINE",
    "code": "ERROR",
    "message": "string"
  },
  "transactions": [
    {
      "date": "string",
      "amount": 0,
      "currencyCode": "AED",
      "transactionType": "SALE",
      "processorTransactionId": "string",
      "processorName": "string",
      "processorMerchantId": "string",
      "processorStatus": "PENDING",
      "processorStatusReason": {
        "type": "APPLICATION_ERROR",
        "declineType": "SOFT_DECLINE",
        "code": "ERROR",
        "message": "string"
      }
    }
  ],
  "riskData": {
    "fraudCheck": {
      "source": "string",
      "preAuthorizationResult": "ACCEPT",
      "postAuthorizationResult": "ACCEPT"
    }
  }
}