Managing payments

The Payments API enables you to manage all payments, through a unified transaction lifecycle.

Before accepting payments, we'll show you how to authenticate against our API and maintain idempotency.

Environments

You can use our dedicated Sandbox environment to test your payments integration. Visit our Test your integration page for more information.

API Authentication

Authentication is handled via the X-Api-Key header. Create and manage API keys and scopes from the Dashboard in the Developers area.

Idempotency

Idempotency is the concept that a single action should only ever have one effect. Our Payments API supports idempotency by providing an X-Idempotency-Key header. Multiple requests to the same endpoint using the same idempotency key will be processed only once. The value you pick for this header should be unique to the payment being processed.

We should mention that sending this header is optional. You don't have to send it, but we think you can agree that it's powerful feature to use.

This example demonstrates a valid, authenticated, idempotent request.

1
2
3
4
5
6
7
8
9
10
11
12

curl --location --request \
    POST 'https://api.sandbox.primer.io/payments' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'X-Idempotency-Key: mqum0y1m8n' \
    --data '{
        "amount": 700,
        "currencyCode": "EUR",
        "orderId": "order-123",
        "paymentInstrument": {
            "token": "<YOUR_TOKEN>",
        },
    }'

For all valid requests to the Payments API, Primer will respond with a 200. The response will always be a payment object including the following attributes:

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

{
    "id": "slklmjh4", // The payment ID
    "date": "2021-01-26T14:24:15.540899",
    "status": "DECLINED",
    "orderId": "YOUR_CUSTOMER_ORDER_ID",
    "currencyCode": "GBP",
    "amount": 800,
    "amountAuthorized": 1000,
    "amountCaptured": 800,
    "amountRefunded": 300,
    "paymentInstrument": {
        "token": "hXIHB_WfR2-M6PM13JDmQnwxNjAxMTE3NTA4",
        "analyticsId": "0gUl6gf1VgmsJQSM4wXShzNX",
        "tokenType": "SINGLE_USE",
        "paymentInstrumentType": "PAYMENT_CARD",
        "paymentInstrumentData": {
            "last4Digits": "1111",
            "expirationMonth": "03",
            "expirationYear": "2030",
            "cardholderName": "MR FOO BAR",
            "network": "Visa",
        },
        "threeDSecureAuthentication": null
    },
    "vaultedPaymentInstrument": null,
    "lastPaymentError": {
        "date": "2021-01-26T14:27:15.540899",
        "type": "ISSUER_DECLINE",
        "declineCode": "DO_NOT_HONOR"
        "declineType": "SOFT",
        "processorMessage": "Transaction cannot be honored."
    },
    "customer": {
        "id": "customer-123",
    },
    "transactions": [

Managing declined and failed payments

If your payment status is

In the example above, the payment has a status of

1
2
3
4
5
6
7
8
9

{
    "lastPaymentError": {
        "date": "2021-01-26T14:27:15.540899",
        "type": "ISSUER_DECLINE",
        "declineCode": "DO_NOT_HONOR",
        "declineType": "SOFT",
        "processorMessage": "Transaction cannot be honored."
    }
}

In this case it was a soft decline, and so authorization can be retried with the same or another payment processor.

Managing non-200 status codes

If you receive a 4XX, then there has been an API validation error. In this case, the response payload will contain an error object with the following attributes:

An example error response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
    "error": {
        "errorId": "RequestValidationError",
        "description": "We were unable to validate your request, please check your payload against https://primer.io/docs/api",
        "diagnosticsId": "11738938659721344025",
        "validationErrors": [
            {
                "model": "PaymentCreationAPIRequest",
                "errors": [
                    {
                        "path": "$.amount",
                        "description": "Missing required field"
                    }
                ]
            }
        ]
    }
}

Now that you can create authenticated, idempotent requests, let's start processing payments. The Payments API is available at /payments.

Creating a payment

Upon creation, a payment will automatically be sent for authorization, using the authorization Workflow in your Dashboard. On successful authorization, the payment status will be set to

Below are the paymentInstrument parameters:

An example payment creation request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

curl --location --request \
    POST 'https://api.sandbox.primer.io/payments' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'X-Idempotency-Key: mqum0y1m8n' \
    --data '{
        "amount": 700,
        "currencyCode": "EUR",
        "orderId": "order-123",
        "paymentInstrument": {
            "token": "<YOUR_TOKEN>", # one-time use, or recurring token
            "vault": "ON_SUCCESS",
        },
        "customer": {
            "id": "customer-123",
        },
    }'

Recurring payments

Primer enables you to flag recurring or subscriptions payments. This is handled by the options.recurring.transactionType field. If you successfully vault a single-use token on payment creation, then there's no need to set a value for this field and it will be flagged as FIRST_PAYMENT. Otherwise, see the table below for all possible values.

An example payment creation request which includes a recurring flag:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

curl --location --request \
    POST 'https://api.sandbox.primer.io/payments' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'X-Idempotency-Key: mqum0y1m8n' \
    --data '{
        "amount": 700,
        "currencyCode": "EUR",
        "orderId": "order-123",
        "paymentInstrument": {
            "token": "<YOUR_TOKEN>", # one-time use, or recurring token
            "vault": "ON_SUCCESS",
        },
        "customer": {
            "id": "customer-123",
        },
        "options": {
            "recurring": {
                "transactionType": "FIRST_PAYMENT",
                "previousNetworkTransactionId": "AJHGHJ",
            },
        },
    }'

Capturing a payment

If you have successfully authorized a transaction, you can now fully capture, or partially capture funds from the authorized payment, depending on whether your selected payment processor supports it. The transaction will be updated to

1
2
3
4
5
6
7
8

curl --location --request \
    POST 'https://api.sandbox.primer.io/payments/<YOUR-PAYMENT-ID>/capture' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'X-Idempotency-Key: mqum0y1m8n' \
    --data '{
        "amount": 700,
        "final": false,
    }'

Cancelling a payment

Provided the payment has not reached 

Example cancellation request:

1
2
3
4

curl --location --request \
    POST 'https://api.sandbox.primer.io/payments/<YOUR-PAYMENT-ID>/cancel' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'X-Idempotency-Key: mqum0y1m8n' \

Refunding payments

By default, this request will refund the full amount. Optionally, pass in a lesser amount for a partial refund.

1
2
3
4
5
6
7
8

curl --location --request \
    POST 'https://api.sandbox.primer.io/payments/<YOUR-PAYMENT-ID>/refund' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'X-Idempotency-Key: mqum0y1m8n' \
    --data '{
        "amount": 200, # supply this parameter for a partial refund, otherwise defaults to full amount
        "orderId": "order-123",
    }'

Retrieving a payment

When getting your payments from our API, we'll return a payment object or list of summarized payment objects.

To retrieve a list of payments in your Primer account:

1
2
3

curl --location --request \
    GET 'https://api.sandbox.primer.io/payments' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \

To get a specific payment by it's payment ID:

1
2
3

curl --location --request \
    GET 'https://api.sandbox.primer.io/payments/<YOUR-PAYMENT-ID>' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \