Getting Started

API Structure

The Primer API is used to manage Client Sessions, Payments and saved payment methods.
All other actions are either managed in the Universal Checkout implementation or in the Dashboard.

Check out:

• Client Sessions
• Universal Checkout
• Managing Payments

Test the APIs yourself in our API Reference

API Endpoint Deployments

• Sandbox: https://api.sandbox.primer.io
• Production: https://api.primer.io

API Versions

Primer makes updates to the APIs on a regular basis, as we release new features.
To allow you to update your integration as you are ready, we allow for a X-Api-Version header to be passed on all API requests.

If you omit the version header, your request will default to the earliest supported version of the API.

curl -X POST 'https://api.primer.io/<ENDPOINT>' \
  --header 'X-Api-Version: 2.2'

📘

Available Versions

Read about the available versions of the APIs below on our Changelog.

Authentication

Primer uses API keys to authenticate requests. You can manage API keys in the Developers area of the dashboard.

As API keys carry many privileges such as authorizing payments, it is important to keep them private and secure. Do not hardcode or share API keys (particularly in your source version control system), and they should only be used in your backend.

Authentication is handled via HTTP headers, specifically the X-Api-Key header.

curl -X POST 'https://api.primer.io/<ENDPOINT>' \
  --header 'X-Api-Key: <YOUR_API_KEY>'

Managing API keys

Head up to the Developers area on the dashboard to manage your API keys.

You will be able to generate or revoke API keys and edit their respective scopes. Be aware that any changes to existing API keys will be reflected immediately and could cause unwanted side effects.

Available scopes

Idempotency key

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.

This is particularly useful when an API call fails due to the request being invalid, due to a network issue, or if Primer is momentarily unavailable.

If this is the case, 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.
• Otherwise, Primer will attempt to process the new request.

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

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

The way you generate the key is totally up to you, as long as it is unique per request attempt.

Keep in mind that a payment request resulting in a declined or failed payment is still considered Successfully processed for the API. Therefore, if you want to allow the user to retry an unsuccessful payment, make sure to not use the same idempotency key.

As a such, don't use anything too restrictive like an orderId for the idempotency key as multiple payment attempts and refunds can be made for a single order.

API Responses

Status Codes

The following table summarizes the HTTP response codes you may receive from
the Primer REST API.

Error Responses

Primer uses conventional HTTP response codes to indicate the success or failure of an API request. HTTP codes in the 2XX range indicate a successful request, whereas codes in the 4XX range indicate a failed request usually due to invalid inputs or operations.

The format of the payload for all errors is common. When an unsuccessful request occurs, you will receive a payload in the following format:

{
    "error": {
        "errorId": "AnErrorId",
        "description": "A human description of the error.",
        "diagnosticsId": "1234567890",
        "validationErrors": []
    }
}

All error payloads will be comprised of a unique errorId which you can use to identify the error, a human description description, and a diagnosticsId that you can quote when contacting the support team ([email protected]).
In case of a badly formed request, Primer will also return additional validationErrors.

Payment Status

As the payments are created, processed, and finalised, they go through a number of states that you will get as an API response, through webhook notifications, and in the Dashboard. These states are used across all processors, as processor specific states are mapped to these. An additional message, in the field processorMessage, from the processor may also be included that details the reason for the state, primarily on failure states.

Don't hesitate to reach out with any questions or feedback. You can email Primer directly at [email protected], or contact your Primer account manager.