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.

KEY
VALUE
Comments

X-SP-GATEWAY

CLIENT_ID|CLIENT_SECRET

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

X-SP-USER-IP

USER_IP_ADDRESS

Required. The ip_address of the user.

X-SP-USER

USER_OAUTH_KEY|USER_FINGERPRINT

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

Content-Type

application/json

Required.

X-SP-IDEMPOTENCY-KEY

IDEMPOTENCY_KEY

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-IP: 127.0.0.1
X-SP-USER: |e83cf6ddcf778e37bfe3d48fc78a6502062fc
Content-Type: application/json

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(
"CLIENT_ID",
"CLIENT_SECRET",
"IP_ADDRESS",
"FINGERPRINT",
)

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.