API Initialization

Requirements of a general API call

Host URLs

Request Headers

Client and user authentication information is expected to be included as header values in your requests.




Required. This is your client_id and client_secret separated by a vertical bar.



Required. The ip_address of the user.



Required. User’s oauth_key and fingerprint separated by a vertical bar.






Optional. POST calls only.

Idemopotent Requests

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 connection error, you can retry the request with the same idempotency_key to guarantee that only a single transaction is created.

Idempotency keys expire after 24 hours.

Example Headers

Host: uat-api.synapsefi.com
X-SP-GATEWAY: client_id_2bb1e412edd311e6bd04e285d6015267|client_secret_6zZVr8biuqGkyo9IxMO5jY2QlSp0nmD4EBAgKcJW
X-SP-USER: |e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json


On occasion, you may see fields in the API responses that are not listed in our examples. These fields are for our testing purposes only and may or may not become permanent in the future. We recommend that you do not rely on these fields for your integration until you see them listed in our API documentation.

Timeout Window

While most API calls finish quickly, we recommend a timeout window of 100 seconds in the event that we are experiencing slowdowns. This will give our API enough time to handle all of the processes and return the correct information in the response.

Client Libraries

Currently in Beta

Client libraries are currently in beta (Sandbox and Production).

Instead of using the API directly, you can use our client libraries:

Deprecated Client Libraries

For platforms using older versions of the client libraries, we recommend updating to the new libraries above. The older libraries are no longer maintained and will soon be deprecated.

Note: The older client libraries do not support changing an account from personal to business. To use this and other newer features, we recommend upgrading to a newer library.

Library Initialization

The following is how you initialize the environment for the libraries.

import os
from synapsepy import Client

client = Client(
    'client_id'= os.environ['CLIENT_ID'], # your client id
    'client_secret'= os.environ['CLIENT_SECRET'], # your client secret
    'fingerprint'= USER_FINGERPRINT,
    'ip_address'= USER_IP_ADDRESS, # user's IP
    'devmode'= True, # (optional) default False
    'logging'= False # (optional) logs to stdout if True
const Synapse = require('synapsenode');
const Client = Synapse.Client;

const args = {
  client_id: process.env.CLIENT_ID,
  client_secret: process.env.CLIENT_SECRET,
  fingerprint: process.env.FINGERPRINT,
  ip_address: '<ip_address>',
  // isProduction determines if production (true) or sandbox (false) endpoint is used
  isProduction: false

const client = new Client(args);
require 'synapseruby'

args = {
  # synapse client_id
  client_id:        ENV.fetch("client_id"),
  # synapse client_secret
  client_secret:    ENV.fetch("client_secret"),
  # a hashed value, either unique to user or static for app
  fingerprint:      "fp",
  # end user's IP
  ip_address:       'ip',
  # (optional) requests go to sandbox endpoints if true
  development_mode: true,
  # (optional) if true logs requests to stdout
  logging: true,
  # (optional) file path to write logs to
  log_to: nil,
  # (optional) rases for 2FA and MFA if set to true
  raise_for_202: true

client  = Synapse::Client.new(args)
require(dirname(__FILE__) . '/../../init.php');

use SynapsePayRest\Client;

$options = array(
	'oauth_key'=> USER_OAUTH_KEY, # Optional,
	'fingerprint'=> USER_FINGERPRINT,
	'client_id'=> CLIENT_ID,
	'client_secret'=> CLIENT_SECRET,
	'development_mode'=> true, # true will ping sandbox.synapsepay.com
	'ip_address'=> USER_IP_ADDRESS

$user_id = USER_ID # optionals

$client = new Client($options, $user_id); // $user_id optional
import github.com/SynapseFI/SynapseGo

// credentials used to set headers for each method request
var client = synapse.New(

Automatic OAuth Updates

You do not need to add oauth_key to the headers after a user is created and authentication is performed. The libraries automatically do that for you.

API Initialization

Requirements of a general API call

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.