Primer supports merchant-initiated payments (MITs) for repeat customers, recurring and subscription business models. You can use Primer’s Payments API to create these payments.

Before you start

Before you start, make sure you are ready to process a payment

Generate an API key

Requests to our API are authenticated using an API key in the X-Api-Key header. Create an API key by visiting the developer page of the Primer Dashboard.

Make sure to set the following scopes for your API Key:

• client_tokens:write
• transactions:authorize

Get a payment method token

The Payments API requires a payment method token to create a payment.

A payment method token represents the sensitive data to process a payment: the card data, or the banking details for instance.

You can get a payment method token from:

• Universal Checkout (see Manual Payment Creation)
• Primer’s unified vault (see Save payment methods)

Send a payment request

Below is a minimal payment request example

1234567891011

curl --location --request \    POST 'https://api.sandbox.primer.io/payments' \    --header 'X-Api-Key: <YOUR_API_KEY>' \    --header 'X-Api-Version: 2.2' \    --header 'X-Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>' \    --data '{        "orderId": "<YOUR_ORDER_ID>",        "amount": 800,        "currencyCode": "GBP",        "paymentMethodToken": "<PAYMENT_METHOD_TOKEN>",    }'

When you create a payment, it will start your workflow with a "Payment created" Trigger.

Remember to add the "Continue payment flow" Action to your workflow. This tells Primer when to respond to your payment request. Without this action, your payment request will time out.

Learn more about processing payments here.

1

Legacy-Workflows: false

Any change in the payment’s status (e.g. once it is AUTHORIZED) will trigger a PAYMENT.STATUS webhook notification event. Learn more about webhooks here.

Handle the Payment’s Lifecycle

All Primer payments conform to a unified payment lifecycle.

Each payment will progress through some combination of the Payment Statuses on their way through your Workflow.

Recover declined or failed payments

A declined transaction doesn't necessarily have to mean the end of the road for your payment.

When authorization is declined by the card issuer or processor gateway, a statusReason object is returned in response to your payment request, providing a decline code and processor message (if available) with further information that can help you recover the payment. You can also see this information on the payment's Timeline in the Dashboard.

• Hard declines include reasons like invalid information, a closed account, or because the card owner reported the card lost or stolen. These cannot be retried with the existing paymentMethodtoken because the payment can never be successfully authorized unless the payment method data is changed. (Your customer's expired card, for example, will never unexpire.)
• Soft declines indicate that authorization wasn't possible due to conditions that in some cases may only be temporary, like when the card limit has been exceeded or the issuer is unavailable. It may be possible to complete these payments successfully at a later time with the same information captured in the initial attempt. In these cases, you can use the same paymentMethodToken to attempt authorization again.

Issues like latency or service disruption at the processor's gateway are usually the cause of FAILED payments, but these can also occur when a configuration error prevents the request from being processed. These transactions may also be successful on a later attempt in the event that there was a technical issue, but you should make sure everything is configured correctly before you retry the payment.

Handle payment errors

Set up Webhooks to receive information about declined and failed payments and consume the data contained in the statusReason object to handle next steps, or consider setting up a fallback or retry scenario in Workflows.

Information about HTTP error responses (4XX) when making an API call to Primer can be found in the Errors section of the API Reference.

Optimize for recurring payments

Payments are tied together through the Network Transaction ID, the ID assigned by card networks to an initial payment in a series of payments. Future payments can then be routed to any processor, rather than being tied to the processor used for the initial authorization.

To optimize authorization rates for recurring payments, pass paymentMethod.paymentType in the payment request. Primer automatically stores and handles processor, acquirer and scheme data in order to increase approvals.

Avoid duplicated payments

Primer supports a request idempotency mechanism for our Payments API. This optional feature enables you to safely retry a request without risking the user being charged or refunded multiple times.

To make an idempotent request, generate an idempotency key and pass it to the header X-Idempotency-Key.

12

curl -X POST 'https://api.primer.io/<ENDPOINT>' \  --header 'X-Idempotency-Key: <idempotency-key>'

Example idempotency error response:

12345678910

{    "error": {        "errorId": "TransactionRequestIdempotencyKeyAlreadyExists",        "description": "Transaction request already exists with idempotency key 'IDEMPOTENCY_KEY'.",        "diagnosticsId": "3233041960986039254",        "validationErrors": [],        "paymentId": "6gHJtooK6",        "paymentStatus": "SETTLED"    }}

If an API call fails due to the request being invalid, due to a network issue, or if Primer is momentarily unavailable, make another request with the same idempotency key:

• If a request with the same idempotency key has already been successfully processed by Primer, the new request will be ignored. A 400 error will be returned with an errorId set to TransactionRequestIdempotencyKeyAlreadyExists.
• On API version 2.2 and later, we will include the paymentId and paymentStatus in the error response to provide more insights into the related payment. This data can be used to validate which payment was already created in case of a duplicate request.
• Otherwise, Primer will attempt to process the new request.