LogoLogo
StatusChangelogDashboardCreate a Ticket
  • Getting Started
  • Intro to APIs
  • How to Contact us
  • How to Go-Live
  • Intro to Risk
  • Intro to Spec Sheets
  • Product Guides
    • Deposit Hub
      • 🌎Global Cash
    • Credit Hub
    • Payment Accounts
    • ID Score
  • API References
    • OAuth
      • OAuth Object Details
      • Create OAuth Key
      • Generate Refresh Token
    • Users
      • User Object Details
      • Testing on UAT
      • View All Users
      • View User
      • Create User
      • Update User
      • Generate UBO Doc
      • Manage Duplicates
      • Allowed Document Types
      • Allowed Entity Scopes
      • Allowed Entity Types
    • Nodes
      • Node Object Details
      • Testing on UAT
      • View all User Nodes
      • View Node
      • Create Node
      • Update Node
      • Generate eCash Barcode
      • Allowed Node Types
      • View ATMs
    • Subnets
      • Subnet Object Details
      • Testing on UAT
      • View all Node Subnets
      • View Subnet
      • Create Subnet
      • Update Subnet
      • Push to Wallet
    • Shipments
      • Shipment Object Details
      • View all Subnet Shipments
      • View Shipment
      • Create Shipment
      • Cancel Shipment
    • Statements
      • Statement Object Details
      • View all User Statements
      • View all Node Statements
    • Transactions
      • Transaction Object Details
      • Testing on UAT
      • View all User Transactions
      • View all Node Transactions
      • View Transaction
      • Create Transaction
      • Create Batch Transactions
      • Cancel Transaction
      • Retry ACH Transaction
      • Dispute Chargebacks
      • Dispute Transaction
    • Subscriptions
      • Subscription Object Details
      • Webhook Object Details
      • Testing on UAT
      • View all Subscriptions
      • View Subscription
      • Create Subscription
      • Update Subscription
      • View Webhook Logs
    • Miscellaneous
      • Dummy Transactions
      • Verify Address
      • Verify Routing Number
      • International WIRE-INT Required Data by Country
      • View Billers
      • View Enriched Data
      • Loan Limits
      • Transaction Decisioning
      • 3D Secure
      • Virtual Terminal
      • Pre-Authorization
      • Card Disputes Guide
      • Mobile Wallets
      • Interchange Revenue
      • Enrichment Guide
  • Developer Guides
    • User Onboarding
      • Create User Flow
      • Authenticate as the User
      • Create Node Flow
        • Cash Advance
        • Credit Builder Loan
        • One Time Loans
        • Secured Open Loans
        • Secured Revolving Loans
        • Unsecured Revolving Loans
      • Create Subnets Flow
        • Creating Cards
        • Creating AC/RT
      • Linking External Accounts
        • Linking Cards
        • Linking External Bank Account
      • Add Additional Documents
    • Account Details
      • Displaying Balances
      • Transaction History
      • Transaction Details
      • Account Agreements
      • Node Statements
      • Card Details
    • Managing Cards
      • Card Preferences
      • Setting PIN
      • Mobile Wallet Flow
        • Integrate with Apple Pay
        • Integrate with Google Pay
        • Integrate with Samsung Pay
      • Shipping Cards
    • Originating Transactions
      • Sending Fed Wires
      • Sending ACH Transfers
      • Sending International Wires
      • Deposit a Check
      • Issuing Checks
      • Recurring Transactions
      • 3rd Party Payment Accounts
      • Cancelling Transactions
      • Exceeding Origination Limits
    • Receiving Transactions
      • Transaction Decisioning
      • Receiving ACH / Wires
      • Card Transactions
      • Exceeding Inbound Limits
    • Managing Disputes
      • ACH Disputes
      • Card Disputes
    • 3rd Party Integrations
      • Payment Integrations
      • Account Aggregators
      • 3rd Parties & Compliance
  • Recipes
    • Overdraft Protection
    • Social Banking
    • Monetizing Transactions
Powered by GitBook
On this page
  • We are RESTful
  • We use Headers
  • Idempotent Requests
  • We are Easy
  • API Rate Limits
  • Max HTTP Request Body Size

Was this helpful?

Export as PDF

Intro to APIs

We are RESTful

Synapse has built a RESTful JSON API for you. Which means, we use:

  • POST to create a document

  • PATCH to update it

  • GET to query one or more documents

  • DELETE to cancel or delete a document (Subtext: nothing gets deleted. It is either unindexed in case of a user or a bank account or it's canceled in case of a transaction)

To make things easier, all GET calls that get multiple documents support pagination and since our primary database is mongoDB (that's why we call everything documents), it also supports mongo filters. Example call for retrieving LOCKED users, page 2 with max 10 documents:

GET /users?page=2&limit=10&filter={"permission":"LOCKED"}

We use Headers

Mostly all requests (with some minor exceptions) require various kinds of headers. Here are some examples:

Header

Example Value

Description

X-SP-GATEWAY

your_client_id|your_client_key

Your client id and secret, separated by a pipe.

X-SP-USER

user_oauth_key|user_device_fingerprint

User's OAuth key and their device fingerprint, separated by a pipe.

X-SP-USER-IP

user_ip

User's IP Address.

X-SP-IDEMPOTENCY-KEY

idempotency_key

Idempotency key to go along with the POST API call.

Not all headers are needed for all API calls. Some require client-level authentication while some require user-level authentication. More on this later, but a good rule of thumb is any resource that requires actions performed by the user (open deposit account, create a transaction, etc.), require user credentials (X-SP-USER-IP) while others require client-level credentials (X-SP-GATEWAY).

Idempotent Requests

To prevent duplicate creation of users, nodes, transactions and subnets, 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.

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.

We are Easy

All Synapse functionality can be broken down into the following core resources:

API Rate Limits

The following is a table of the the most common API calls and their respective rate limits. These limits cannot be increased. Please take this into account when building out your application.

HTTP Verb
URL
Functionality
Rate Limits (per min/per user)

POST

/oauth/<user:id>

This API call allows you to get oauth_key for users.

30

POST

/oauth/<user:id>/login

Using basic auth to get refresh_token for users.

30

GET

/users

View all users created with your client keys (paginated).

100

POST

/users

Allows you to register a new user.

100

GET

/users/<user:id>

View user info and refresh_token.

30

PATCH

/users/<user:id>

Add/update KYC, log in credentials, profile, etc.

30

GET

/users/<user:id>/nodes

View all nodes linked to a user (paginated).

100

POST

/users/<user:id>/nodes

Allows you to create a deposit account or link an external bank account to a user.

100

GET

/users/<user:id>/nodes/<node:id>

View node info.

100

PATCH

/users/<user:id>/nodes/<node:id>

Update supp_id, verify micro-deposits, etc.

100

DELETE

/users/<user:id>/nodes/<node:id>

Unindex node from a user.

100

POST

/users/<user:id>/nodes/<node:id>/subnets

Allows you to issue a virtual account number on top of a node.

100

GET

/users/<user:id>/nodes/<node:id>/subnets

View all subnets linked to a node (paginated).

100

GET

/users/<user:id>/nodes/<node:id>/subnets/<subnet:id>

View subnet info.

100

PATCH

/users/<user:id>/nodes/<node:id>/subnets/<subnet:id>

Update subnet info.

100

GET

/users/<user:id>/trans

View all transactions of a user (paginated).

100

GET

/users/<user:id>/nodes/<node:id>/trans

View all transactions of a node (paginated).

100

POST

/users/<user:id>/nodes/<node:id>/trans

Allows you to create a transaction.

100

GET

/users/<user:id>/nodes/<node:id>/trans/<trans:id>

View transaction info.

100

PATCH

/users/<user:id>/nodes/<node:id>/trans/<trans:id>

Update notes on a transaction.

100

DELETE

/users/<user:id>/nodes/<node:id>/trans/<trans:id>

Only works if transaction has been created or queued.

100

GET

/subscriptions

View all subscriptions created with your client keys (paginated).

10

POST

/subscriptions

Create a subscription with webhook preferences.

10

GET

/subscriptions/<subscription:id>

View a subscription.

10

PATCH

/subscriptions/<subscription:id>

Update scope, url, is_active, etc.

10

GET

<:user_id>/statements

View a users statement

30

GET

<:node_id>/statements

View a node statements

30

Max HTTP Request Body Size

HTTP request body size is limited to 30 MB maximum.

PreviousGetting StartedNextHow to Contact us

Last updated 2 years ago

Was this helpful?

: Individual or Business accounts you create in our System. User objects store all KYC and Authentication information for each user.

: Nodes are either deposit accounts, credit accounts that you open with us, or 3rd party accounts you link with us to be able to move funds on behalf of the user. Each user can link or create multiple nodes under them.

: Transactions resource enables you to send money between various nodes. Just supply addresses for from and to nodes, and we will move money between both accounts. This is handy because this gives you one unified way of creating all kinds of transactions: Internal Transfers, ACH Debit, ACH Credit, Interchange Pulls, Push to Card, Wires, BillPay, etc.

: Each deposit or credit node (accounts we open for your users) automatically generates statements each month. This is to comply with regulations like Reg and . The idea is that we will generate the statements and you will distribute them.

: With Transactions resource, you can create transactions between two nodes that exist in the Synapse system. But what if you wanted other networks and platforms to be able to interface with the Synapse system? That's where subnets come in handy. If a node is hosted by Synapse (deposit or credit), you can issue a Subnet on top of that node to interface with other platforms. That's the general idea. Currently, it supports two kinds of interfaces -- Account and Routing Numbers, and Card Numbers.

: If a Subnet is a card number, this resource enables you to ship a physical card to the user.

: Since it's not efficient to poll our entire system with API calls, Subscriptions enables you to set up webhook alerts with us so that whenever updates to objects happen, your system can automatically stay in sync.

Users
Nodes
Transactions
Statements
E
Z
Subnets
Shipments
Subscriptions