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:
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
Scope | Description |
---|---|
client_tokens:write | Create client tokens for use with the client SDK. |
third_party:webhook_trigger | Allows you to post to our webhooks endpoint. API keys with this scope can be used to enable communication between your processor and Primer about important payment lifecycle events. |
transactions:authorize | Authorize a payment. |
transactions:cancel | Cancel a payment. |
transactions:capture | Submit a payment for settlement. |
transactions:retrieve | Retrieve one or more payments. |
transactions:refund | Refund a payment. |
payment_instrument:read | Read stored payment methods. |
payment_instrument:write | Write stored payment methods. |
API Responses
Status Codes
The following table summarizes the HTTP response codes you may receive from
the Primer REST API.
Status Code | Description |
---|---|
200 | Success |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Entity Not Found |
409 | Entity Already Exists |
422 | Input Validation Failed |
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.
Status | Description |
---|---|
PENDING | The payment has been created by Primer but not yet authorized. |
FAILED | The processor failed to process this payment. |
AUTHORIZED | The payment is authorized and awaiting capture. |
SETTLING | The payment has been submitted for settlement and funds will be settled later. |
PARTIALLY_SETTLED | The payment has been partially settled. |
SETTLED | Funds have been settled into your account. |
DECLINED | This payment was declined by the processor, either at a gateway or acquirer level. See the reason object in your response payload for more details. |
CANCELLED | The payment was cancelled prior to it being settled. |
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.
Updated 2 days ago