Making the Best Use of Synapse

We advise following these best practices to ensure you and your end-users have the best experience possible when working with Synapse.

Recommended Flows

All the ways to use our APIs are not created equal. In many circumstances, of the different ways to achieve the same action, there is a clearly preferred method. We refer to the best methods for using our APIs in our User Guides as Recommended Flows. Please refer to each product page for its respective recommended flow.

Example Recommended Flow: Create User and add KYC

Subscribing to Webhooks

Information in our system is constantly changing and updating, long after API calls have been made.

Examples include:

A user could be flagged on a sanctions list after being previously marked as verified.
A node’s balance could be updated after a payment has posted.
A transaction could be queued shortly after creation.

We recommend that platforms subscribe to webhooks to receive updates on their users, nodes, transactions, and other changes inside their respective ecosystems.

Webhook Sub-Resources

Idempotent Requests

To prevent duplicate creation of users, nodes, and transactions, it's important provide retry attempts with idempotency keys.

All POST calls support idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a transaction fails due to a network connectivity error, you can retry the request with the same idempotency key to guarantee that only a single charge is created.

To perform an idempotent request, attach a unique key to any POST request made to the API via the X-SP-IDEMPOTENCY-KEY: header.

Notes to keep in mind when making idempotent requests:

Idempotency keys expire after 24 hours.
It is best practice to wait for a failure response from the POST call before attempting to retry the call.

Mitigating Risk

Please refer to our Mitigating Transaction Risks guidelines for steps you can take to reduce your exposure to transaction risks.