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.

The examples in the Guides assume that you have set an environment variable baseurl, e.g.

export baseurl=https://api-sandbox.synctera.com

You also need to set 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:

1. Switch to your Sandbox workspace using the workspace selector at the top of the screen
2. In the "Welcome to your Sandbox" view, click "Generate", then click the Copy icon to copy the key
3. 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:

curl https://api-sandbox.synctera.com/v0/customers \
  -H 'Authorization: Bearer 476d901b4-a264a79-9db9-96d3dfaafb732'

The examples in the Guides assume that you have set an environment variable apikey, e.g.

export apikey=476d901b4-a264a79-9db9-96d3dfaafb732

You also need to set 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 $30, for example, you won't accidentally credit $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 header Idempotency-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:

curl -X POST https://api-sandbox.synctera.com/v0/customers \
  -H 'Idempotency-Key: 259'

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

An idempotency key can only be re-used for the same request.
If you try to use it with a different request, you will receive a 422 response with an 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:

1. 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".
2. 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".
3. 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.

OpenAPI Specification

You can download the Synctera OpenAPI schema decribing our API surface below.

Download

This schema can be used with the various openapi tools like openapi generator.

Using openapi generator, you can generate a client library to interact with Synctera. Below is an example to generate a java client library using openapi generator.

java -jar openapi-generator-cli-6.0.0-20211025.061654-22.jar generate -i synctera_openapi.json -g java -o ./java_client