Skip to main content

API Basics

Zero Configuration​

The Payment API follows a zero configuration approach whereby you provide all the relevant variables as part of the API calls.

This allows faster development, complete E2E testing and multi-staging environments as you can define webhooks, timeouts and other behavioural variables programmatically at runtime.

Multi-Tenancy​

The access to the Payment API is tenant-specific. Each tenant can have its own UI customization to perfect UI Embedding.

Idempotency Keys​

When creating resources with the Payment API, you can provide an Idempotency Key, i.e. a unique key that is tenant-specific and that will act as an identifier for the object to be created.

We highly recommend to use Idempotency Keys when creating Checkout Intent, Payment Intent and Refunds.

Submitting the same request with the same Idempotency Key multiple times will result in the resource being created only once.

API Basics​

All non-GET endpoints from the Payment API expect a valid JSON as the body, if you fail at this you can expect the following 400 Bad Request response:

{
  "message": "Unexpected number in JSON at position 102",
  "error": "Bad Request",
  "statusCode": 400
}

All API endpoints that return data use the JSON format, therefore you don't need to specify a specific Content-Type header.

All endpoints except one expect a bearer token for authentication & authorization (read more below).

The message property can be an array of error messages.

Authentication​

Authentication is done using a bearer token that never expires. You can generate multiple bearer tokens if you need to rotate them. Pass the token through the Authorization: Bearer {{key}} header.

Authorization​

Orchestrapay uses a claim-based authorization scheme, each API key is assigned a series of claims and each feature is only accessible if the API key holds the relevant claims.

Both unauthorized and unauthenticated requests get the same "401 Unauthorized" response for security purpose, if you need to debug whether you have an authentication or authorization issue, use the /me endpoint which is accessible to all API keys and returns a list of claims associated with the API key.

If you have a wildcard * claim, then the API key has full authorization across all features/resources associated with your tenant.

Error Handling​

All illegal requests that don't follow documentation from your side will receive a 400 Bad Request with an explainer:

{
  "statusCode": 400,
  "message": "A value for `gateway` is expected if you provide a `payment_intent`"
}

If you submit a correct request with a non existing resource, you will get a 404 status code:

{
  "statusCode": 404,
  "message": "No checkout intent found with uuid 6e051feb-d234-4225-b4ea-6d9917389fe8"
}

Any request that returns a 50x error message is monitored by our side and should not occur, if they do however, please send us a message on Slack to speed up troubleshooting.

API Error Codes​

When an error results in a 400 statusCode, you will usually find an associated apiErrorCode. These are unique across Orchestrapay and represent a specific type of exception, you can use it to communicate with us for debugging purposes.

{
  "apiErrorCode": 102,
  "message": "Requested amount of the refund (125000) is greater than the remaining refundable amount (100000). You can only refund EGP 25000 (in cents) anymore.",
  "statusCode": 400
}

HTTP Error Codes​

Orchestrapay's API uses the official HTTP response status codes when it answers API Calls. You can read more about standard HTTP response status codes here.