Managing transactions

Primer's Transaction API enables you to process and manage payments across all processors and payment methods, through a unified transaction lifecycle. This guide assumes you have read our Quick start guide.

For transaction lifecycle requests, Primer will respond with a 200 provided the request was successfully processed. The response will contain the following attributes:

An example transaction lifecycle response:

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

{
    "success": false,
    "reason": {
        "decisionType": "APPLICATION_ERROR",  // null if success equals true
        "declineReason": "...", // null if decisionType is not equal to ISSUER_DECLINED
        "message": "This request could not be honored because..."
        "source": "BRAINTREE"
    },
    "transaction": {
        "createdAt": "2020-09-26T14:24:15.540899",
        "id": "9483a0c5-b1c3-42f5-ab73-d3feee09fb46",
        "primerAccountId": "2ff302dc-45d7-4759-85fc-cc905e7d3191",
        "merchantId": "<YOUR_MERCHANT_ID>",
        "processorTransactionId": "8ftnw094",
        "orderId": "order-123",
        "status": "DECLINED",
        "riskData": [
            ... // AVS, CVV and proprietary risk data
        ],

If Primer responds with a 4XX, there has been an API validation error, and the request has not been sent to the processor. 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": "BasicPaymentAPIRequest",
                "errors": [
                    {
                        "path": "$.amount",
                        "description": "Missing required field"
                    }
                ]
            }
        ]
    }
}

Our Transactions API supports idempotency by providing an optional Idempotency-Key header. Multiple requests to the same endpoint using the same idempotency key will be processed only once.

For example, if we successfully receive a request but the connection drops before you receive a response, you may automatically retry that request. Without the use of an idempotency key, we would process the request a second time. By supplying an idempotency key, we ensure that the retried request is not processed a second time.

This example demonstrates a valid, authenticated, idempotent request.

1
2
3
4
5
6
7
8
9
10
11

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

Many payment methods support an auth and capture flow, where authorizing the transaction will put a hold on customer funds for a period of time (typically determined by the card scheme), and capturing will transfer funds from the customer's account to your acquirer - and bank account. Primer enables you to to perform authorization and capture requests separately, or at once.

Authorizing a payment

Primer sends an auth and capture request by default. If you want to authorize and capture separately then pass capture: false on the authorization request. Upon success, the transaction will transition to SETTLING or SETTLED (depending on the payment method type). For authorization-only requests, the transaction will transition to AUTHORIZED where it is ready for a capture or cancel request.

An example auth/capture request:

1
2
3
4
5
6
7
8
9
10
11

curl --location --request \
    POST 'https://api.sandbox.primer.io/transactions/auth' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'Idempotency-Key: order-123' \
    --data '{
        "paymentMethod": "<YOUR_TOKEN>", # one-time use, or recurring token
        "orderId": "order-123",
        "amount": 700,
        "currencyCode": "EUR",
        "merchantId": "<YOUR_MERCHANT_ID>"
    }'

Recurring payments

Primer enables you to store payment method information in our unified vault, for recurring transactions (when the payment method supports it). This agnostic storage layer enables you to process transactions across different processors (typically for card payments).

To store a payment method on authorization, set the vault and customerDetails.customerId attributes in your request. This customerId is your reference for the customer, and is used to subsequently retrieve payment methods for a given customer.

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

curl --location --request \
    POST 'https://api.sandbox.primer.io/transactions/auth' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'Idempotency-Key: order-123' \
    --data '{
        "paymentMethod": "<YOUR_TOKEN>", # one-time use, or recurring token
        "orderId": "order-123",
        "amount": 700,
        "currencyCode": "EUR",
        "merchantId": "<YOUR_MERCHANT_ID>",
        "vault": {
            "paymentMethod": "ON_SUCCESS",
            "recurring": "SCHEDULED",
        },
        "customerDetails": {
            "customerId": "<YOUR_CUSTOMER_ID>"
        }
    }'

Capture

If you have performed an authorization-only request, you can now fully capture, or partially capture funds from the authorization (depending on whether your selected processor supports it). The transaction will be updated to SETTLED or SETTLING (depending on the payment method type).

1
2
3
4
5
6
7
8

curl --location --request \
    POST 'https://api.sandbox.primer.io/transactions/<primer-transaction-id>/capture' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'Idempotency-Key: order-123' \
    --data '{
        "amount": 700,
        "final": true
    }'

Cancelling a payment

Provided the transaction has not reached SETTLED, Primer will typically send a "void" request to the processor, thereby cancelling the transaction and releasing the hold on customer funds. Upon success, the transaction will transition to CANCELLED.

Example cancellation request:

1
2
3
4

curl --location --request \
    POST 'https://api.sandbox.primer.io/transactions/<YOUR-TRANSACTION-ID>/cancel' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'Idempotency-Key: order-123' \

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/transactions/<YOUR-TRANSACTION-ID>/refund' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'Idempotency-Key: order-123' \
    --data '{
        "orderId": "order-123"
        "amount": 100 # supply this parameter for a partial refund, otherwise defaults to full amount
    }'