Synctera API
Need to Know
Request Validation
Synctera will not correct your requests other than for potential abuse / sanitization. You will need to validate and clean your input to ensure that your customer information is usable for features like KYC or mailing physical cards.Environments
Base URLs
The base URL for your request determines whether the request goes to the Synctera sandbox or, when you’ve rolled your code out for real, to the Synctera production environment where your requests will transact business in the real world. Use the sandbox base URL to make requests of the sandbox, and the production base URL to make requests of the real Synctera platform.| Environment | URL |
|---|---|
| Sandbox | https://api-sandbox.synctera.com |
| Production | https://api.synctera.com |
baseurl, e.g.
Shell
apikey, see the Authentication section for more details.
Sandbox
You can experiment with our APIs in the Synctera sandbox, which is self-contained and has no interaction with the real world. You can use our sandbox to test our underlying services, accessing our vendors’ sandboxes as necessary when using their services. You’ll need an API key to authorize requests to the sandbox. If you don’t have one:- Switch to your Sandbox workspace using the workspace selector at the top of the screen
- In the “Welcome to your Sandbox” view, click “Generate”, then click the Copy icon to copy the key
- Save the key by pasting it somewhere you can later retrieve it
Authentication
You authenticate each request by presenting your API key in the request header.Authorization: Bearer {API_KEY}
For example, the beginning of a request using a fictitious key:
Shell
apikey, e.g.
Shell
baseurl, see the Environments section for more details.
Idempotency
All of our API endpoints support idempotency, in which a request defines a state, not an action. If you repeat an idempotent request through accident or because you’re unsure if an earlier request made it through, the repeated requests won’t accumulate with unintended results. If you repeat an idempotent request three times to credit an account with 90, you will credit the intended $30. The response to any request made with an idempotency header is cached, and a subsequent request with the same idempotency key will return the cached response, including the original response status code. Our endpoints support idempotency as defined in the IETF draft specification. To send an idempotent request, add the headerIdempotency-Key: {KEY} to your request, where {KEY} is an arbitrary value that you generate. When you repeat a request (e.g. because of an error or timeout), you need to send the same idempotency key as the previous attempt. When sending a distinct (not repeated) request, you must send a new, distinct, idempotency key.
Each idempotency key and any resulting cached responses persist for 7 days and then disappear.
An example of a cURL request using an idempotent request header with an example key value of 259:
Shell
Errors and Idempotency
In general, requests that return an error are cached in the same way as successful requests. The following specific cases are exceptions. A repeat of these requests with the same idempotency key will re-execute the request and not return a cached response:- 500-series status codes are not cached, since they may not have been fully executed
- requests that are rate-limited and return a 429 status code are not cached
IDEMPOTENCY_INVALID_REUSE error code.
If you re-use an idempotency key while the previous request is still being processed, you will receive a 409 response with an IDEMPOTENCY_CONCURRENT_USE error code.
Synctera Money Movement Endpoints
Currently the Synctera ledger (including all POST and PATCH endpoints that deal with transactions or money transfers) implements a stricter form of idempotency. For these endpoints:- An idempotency key header is required. Requests missing an idempotency key header will result in a 400 Bad Request with the message “missing Idempotency-Key header”.
- The response to successfully executed requests is not cached. Instead, subsequent requests with the same idempotency key will result in a 409 Conflict response with the message “duplicate idempotency key”.
- Idempotency keys used by successfully executed requests persist indefinitely. They are persisted on a per resource basis where the resources are pending transactions and posted transactions. These idempotency keys can never be re-used for another resource of the same type, i.e, given a posted transaction with id 123, another posted transaction with id 123 would result in a 409 Conflict but a pending transaction with id 123 would be successful.
Response Codes
Requests to our APIs return standard HTTP status codes (described here) often accompanied by additional data. All are formatted as JSON.- 2xx codes indicate success and are often accompanied by response parameters generated by endpoint service.
- 4xx codes indicate request failure due to missing or erroneous request information.
- 5xx codes indicate an error in endpoint service.