API Responses

Status Codes

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

Status CodeDescription
200Success
400Bad Request
401Unauthorized
403Forbidden
404Entity Not Found
409Entity Already Exists
422Input 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:

1{
2  "error": {
3    "errorId": "AnErrorId",
4    "description": "A human description of the error.",
5    "diagnosticsId": "1234567890",
6    "validationErrors": []
7  }
8}

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 (support@primer.io). 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.

StatusDescription
PENDINGThe payment has been created by Primer but not yet authorized.
FAILEDThe processor failed to process this payment.
AUTHORIZEDThe payment is authorized and awaiting capture.
SETTLINGThe payment has been submitted for settlement and funds will be settled later.
PARTIALLY_SETTLEDThe payment has been partially settled.
SETTLEDFunds have been settled into your account.
DECLINEDThis payment was declined by the processor, either at a gateway or acquirer level. See the reason object in your response payload for more details.
CANCELLEDThe payment was cancelled prior to it being settled.

Breaking changes

Primer commits to not introducing breaking changes in endpoints or API versions without also introducing a minor API version bump. You can expect endpoints that you’re using to not have breaking changes until you upgrade to another version.

However, you should expect non-breaking or additive changes, and we encourage you to design your systems to protect against this possibility.

Currently, non-breaking changes can happen inside the same minor API vesion, and breaking changes cannot.

Primer considers breaking changes to be changes that can potentially break an integration. Breaking changes include:

  • removing an entire operation
  • removing or renaming a parameter
  • removing or renaming a response field
  • adding a new required parameter
  • making a previously optional parameter required
  • changing the type of a parameter or response field
  • removing enum values
  • adding a new validation rule to an existing parameter
  • changing authentication or authorization requirements

Primer considers non-breaking changes to be changes that should not break an integration, and that you should protect against. Additive changes include:

  • adding an operation
  • adding an optional parameter
  • adding an optional request header
  • adding a response field
  • adding a response header
  • adding values to existing enums

If, in exceptional circumstances, we do need to introduce a breaking change without bumping the API version, then we will ensure to communicate this ahead of any release, working closely with you to mitigate any possible impact.

Don’t hesitate to reach out with any questions or feedback. You can email Primer directly at support@primer.io, or contact your Primer account manager.