Skip to main content

Core Concepts

Multi-Tenancy​

Your entire Orchestrapay transactional universe is scoped to a tenant, which can have their own team members, API keys, transactions, refunds, logos, etc. An organization can have multiple tenants.

When creating a tenant, you can specify whether it is a production or sandbox one, this value cannot be changed afterwards and sandbox tenants can only route transactions through sandbox/staging environments in each gateways.

Regions​

We provide multiple separate regions that you can chose as your main database. Regions are 100% seggregated and do not communicate together: pick the region closest to your users, or the one that you require for compliance reasons if your country's Central Bank has a specific mandate.

Europe - The eu1 Region is based in Frankfurt, Germany.

USA (West) - The us1 Region is based in Oregon and is currently in Release Candidate, reach out to us if you'd like to open an account in us1.

USA (East) - The us2 Region is based in Virginia and is currently in Release Candidate, reach out to us if you'd like to open an account in us2.

Egypt - The eg1 Region is compliant with all requirements of the Egypt Central Bank regarding the localization mandate. It is located in Cairo. Only use the Egyptian region if most of your transactions are Egypt based as there can be limitations in gateways availability.

Nigeria - The ng1 Region is currently in Release Candidate, reach out to us if you'd like to open an account in ng1.

Kenya - The ke1 Region is currently in Release Candidate, reach out to us if you'd like to open an account in ke1.

Idempotency Keys​

When creating resources such as Payment Intents & Refunds, 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. Submitting the same request with the same Idempotency Key multiple times will result in the resource being created only once.

We highly recommend to use Idempotency Keys.

Throttling​

We use a soft throttling approach where we will throttle your requests automatically for security purposes.

Webhooks​

Both payments and refunds are actually an asynchronous promise: you create the resource, let the user interact with it and at some point receive a webhook notification that the promise has settled.

You can set an array of webhook URLs and webhook secrets when you create the Payment Intents and the Refunds - you currently cannot set these up in our Dashboard. This is by design to ease touchless end-to-end testing & CI/CD.

You need to respond with a 200 HTTP status code when you receive webhooks, otherwise we will retry with exponential backoff up to 5 times before we give up. You can see all webhooks sent in our Dashboard, we keep the payloads available for inspection for 90 days.

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 your secret key as a bearer token. You can keep multiple API keys alive and rotate them in production. Pass the token through the Authorization: Bearer {{your_secret_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 payment intent found with id pi_eu1_6e051febd2344225b4ea6d9917389fe8"
}

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.