Getting Started

Don't hesitate to reach out with any questions or feedback.

Navigate to our JIRA Service Desk to submit your inquiry. If you don’t have access, please contact your account administrator for assistance.

Not yet integrated with Primer and interested in learning more? Contact us.

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

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.