Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
If you wish to become a customer, please to get in touch with us.
If you wish to get a general sense of the offering, please go to the resource.
If you wish to add new products or services, please contact your Customer Success Manager or email us at .
Experiencing Technical Issues? Please check our . If the issue is not an ongoing incident, please email us at or to create a ticket.
This is an overview of our implementation process. We will share a more detailed timeline as part of your Implementation Guide.
ETA: 1-2 Weeks
Create Account & Setup Billing Setup your account and billing to kick off your implementation.
Submit Due Diligence Please submit this as soon as possible to prevent delays! We must complete due diligence on your company and beneficial owners prior to receiving bank approval.
Kickoff Call During the kickoff call, we will go over:
Your Implementation Timeline
Your Spec Sheet (detailing your product and any relevant controls)
Your API Guide
Best Practices (weekly calls, issue tracker, communication channels, etc)
Program Sandbox Controls You will receive a custom test environment ("sandbox") that matches the controls outlined on your Spec Sheet, allowing you to test in an environment that closely mirrors what you should expect in production.
ETA: 2-6 Weeks
Third Party Partner Setup Synapse will work with you to receive necessary approvals and setups from third party partners. These can be done in parallel with other steps and includes:
Physical Card Setup with Card Printers
Card Acquiring with Networks
Mobile Wallet Setup with Networks and Partners
Account Aggregation with Banks
Compliance Review Synapse will request a number of documents, screenshots and acknowledgments to ensure the necessary compliance disclosures and marketing components are in place.
Fund Reserve Account Your reserve is used to cover potential losses. The initial funding amount is agreed upon during the Spec Sheet process.
Sign Beta Acknowledgement While in Beta, we ask that you clearly disclose to your users that your product is still in Beta. This is helpful if there are regulatory inquiries while you are in Beta.
Receive Bank Approval - Provisional Our partner bank(s) review your due diligence once it is submitted to grant provisional beta approval.
Program Production Controls - with Beta Cap Your production environment allows you to test real users and real transactions. Please note that we cap the number of users while you are finishing up your Beta testing.
ETA: 2 Weeks
Receive Bank Approval Prior to going fully live, we will [again] submit your updated documentation, along with your completed reviews, to our partner bank(s).
Remove Cap on Users Once we receive full approval, we will remove the cap on the number of users that you can onboard.
Go-Live Kickoff Call Synapse will close out any remaining items from your implementation and walk you through what to expect now that you are live!
Model Validation After you have two weeks of data and some minimum usage, Synapse will review your users' activity. This allows us to catch potential concerns before you roll out your product at scale.
Ongoing UDAAP Marketing Reviews Prior to new Marketing roll-outs, please provide all materials to Synapse for review.
Synapse partners with multiple card vendors to support your physical card needs.
We will facilitate a direct line of communication between you and any of our vendors so you can fully leverage their expertise.
Timelines are ultimately dependent on the vendor. However, cards generally fall into two categories:
Print-on-Demand Cards Timeline: 6-8 Weeks
Print-on-Demand cards are plastic cards with basic customization options. Opting for a Print-on-Demand card is the fastest option to get something to market since it does not require long lead times to print, nor does it require purchasing card inventory in advance. However, these cards have limited options for materials, finishes, and other customizations.
Standard Card Package:
Card (Plastic; Glossy Finish)
Generic White Envelope (Optional Black/White Logo in Address field)
Carrier (Letter or 5x7 Paper Card to affix debit/credit card onto)
Activation Label (Sticker affixed to Card) - OPTIONAL
Inserts - OPTIONAL
Custom Inventory Cards Timeline: Dependent on level of customization
Inventory Cards allow for additional customizations of materials and finishes beyond what a standard Print-on-Demand card supports. Because these cards are highly customized, they require the purchase of inventory upfront and additional lead times. Exact lead times are subject to the printer’s printing schedule upon finalizing art.
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:
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)
.
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.
All Synapse functionality can be broken down into the following core resources:
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.
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
HTTP request body size is limited to 30 MB maximum.
: 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.
ID Score is a probabilistic score (0-1) assigned to all users at the time of onboarding that predicts the likelihood that the identity supplied belongs to the person who is creating the account. 1 means we are 100% certain that the user is who they say they are. 0% means with 100% certainty we can say that the user is not who they say they are.
When ID Score is enabled and users have a high enough ID Score, we will only collect Base Document and SSN to onboard a consumer (individual or joint account). For users with low ID Score, we will collect Government Issued ID and Video Auth as well.
At the beginning of the user onboarding process, nearly every end-user submits the following data points:
Name
Physical address
Email address
Phone number
IP address
Date of Birth (DOB)
We then evaluate this submitted data. For example, we will place additional scrutiny (including restrictions) on IP addresses associated with:
Known web crawlers
VPN proxies
Anonymity networks (e.g. Tor)
Sometimes our model will need to account for user-submitted information that may not necessarily be an indicator of fraud. To delve deeper into a location example, a user may submit a phone number with a 415 area code (i.e. associated with the San Francisco Bay Area) while listing a current address in Los Angeles--and our model may be able to disregard the location mismatch if we can find evidence of previous San Francisco residency in their address history and we can independently verify that the user presently resides in Los Angeles. We refer to such 2nd-order logic as “derived features” of ID Score.
Three main factors are considered for determining which vendors are most useful for ID Score:
Decisioning Tools: Ensuring that we are aligned on how the vendor determines what data to pass on to use and how they make assessments about trustworthiness.
Coverage: Ensuring that there are no gaps or redundancies in the data.
Sources: Ensuring that certain groups are not underrepresented or overrepresented.
After receiving the augmented data from other identity verification vendors, we use machine learning models to compare against previously-seen data patterns.
ID Score is built to be conservative with all Synapse clients in mind. Each client has the ability to adjust the score application according to their business profiles and risk preferences.
For each user, ID Score assigns a trust level (low
,med
or high
) and an id score (0-1) after evaluating the authenticity of user input details.
While KYC programs vary platform by platform, our general guidance is the follow the following though process:
trust_level
KYC requirements
Example KYC
low
Perform EDD by requiring additional documents and maybe even a manual review.
SSN + Govt ID + Video Auth + Manual Review
med
Ask for additional documentation, but still an automated review.
SSN + Govt ID
high
Ask for minimum KYC information.
SSN
Note: A low score does not necessarily mean a user is providing false information or committing fraud, it means that we don’t have enough positive signals to assure their identity.
After ID Score has been added in your MSA (Master Services Agreement), we will follow the following steps:
We will analyze your platform’s activity and make KYC Recommendations for all three trust score values.
Once we agree on a KYC workflow, we will program that for you in your Sandbox environment.
You will then, Integrate with our API for ID Score.
Test both EDD and non-EDD flows for ID Score in Sandbox.
Once testing completes, we will enable the new workflows for you on production.
Synapse provides an easy-to-understand program overview to each platform prior to going live. This enables both parties (you and us) to be on the same page with the product and service offerings. This is also very helpful when regulators have questions about certain programs as it provides an overview of controls and flows of funds, among other details.
In this section we will be walking you through various aspects of a Spec Sheet, to ensure you have a clear understanding of how to navigate the document and the purpose it serves.
This section has basic company information, how you are planning to monetize your product, and who your target audience is.
Customer Demographics is broken down into the following sections:
Demographic
Description
Under-Banked
The end users historically have had limited-to-no access to financial products.
Banked
The end users historically have been moderately banked. So they've had access to deposit accounts, but not low APR loans, for example.
Well-Banked
The end users are well represented by mainstream financial products. They tend to be on the higher end of the socioeconomic ladder and have access to most mainstream financial products.
The section further describes each product and feature that the platform will be utilizing.
Currently, we support the following account types:
Account Type
Description
Individuals
End users will be individuals
Businesses
End users will be business entities
Joint Accounts
End users will be opening combined accounts together (E.g. families).
Third-Party Payment Accounts
No end users, user accounts will be opened for third parties that the users need to send payments to.
This is usually done in conjunction with the above account types as this is a way for your users to make payments to individuals/entities that are not a part of your platform.
The next section documents a platform's KYC Program, starting with document requirements and then an overview of the KYC Policy:
CIP Tag 1 will be opening accounts for individuals who only need to have access to deposit accounts. For this user segment, the platform will be collecting Base Document (Name, Email, Phone, Address, DOB, and IP Address) and the user's SSN. But if the ID Score is below 0.70, the platform will also be collecting front and back of the user's Government Issued ID and Video Auth.
CIP Tag 2 is an example of the same user type but the ID Score Clip is 0.80 vs 0.70. Separating user types in this way ensures that your platform has granular control over the requirements and aligns customers to those requirements to help mitigate risk.
CIP Tag 3 is an example of a third-party payment account, the platform will only be collecting base documents on the individual/entity.
Since in this example the platform is offering credit services, they will also have a Lending Program section in the Spec Sheet. This section has two subsections: Lending Box and Underwriting Policy.
This section goes over the basic terms of the loan. The max amount, APR, and payment schedule.
This is the final section of the Spec Sheet that goes over how much a user and the platform (in aggregate), are able to process through Synapse.
Transaction Limits are a function of your operating capital and the overall fraud occurring on the platform and can be updated over time.
In this example, the platform wants to slow down settlements for ACH and RDC Pulls by 3 business days since that poses a risk of financial loss for the platform, while the rest of the transactions settle as usual.
Currently Global Cash are only able to hold USD balances, but you can onboard customers from the following countries:
Argentina
Australia
Austria
Belgium
Brazil
Canada
China
Chile
Colombia
Czech Republic
Cayman Islands
Denmark
Finland
France
Germany
Hong Kong
India
Ireland
Italy
Luxembourg
Malaysia
Mexico
Netherlands
New Zealand
Norway
Portugal
Singapore
Slovakia
South Africa
Spain
Sweden
Switzerland
United Kingdom
United States
Vietnam
CMA can be used for pretty much any application that requires an embedded deposit custody. But we are seeing the following use cases most frequently:
Please note, we are still learning more about this segment of our business and KYC requirements might evolve over time. Consider this a v1 of Non-US Business KYC.
For UBO's of non-US sole proprietorships, we currently support the following.
To enable, please discuss this with your growth manager.
To spin up a Cash Account for a user, here are the steps you can follow:
The first step is to create a user account and supply all of their KYC. Once the user account has been created, grab the refresh_token
from the response which is needed to issue an OAuth key for the user.
To avoid 2FA, please use the fingerprint value that you used while creating the user account. Once the OAuth key is issued, grab oauth_key
which will be needed to launch deposit hub.
First please preview the cash agreement to the user, once they agree, create the cash account. Please ensure the user is able to select their custody and risk preferences.
That's it. You've successfully created a cash account for your user.
Now let's enable some features on this cash account.
Now you have an ACH-US
node linked under the user profile. This means the user can fund their cash account via an external bank account or if funds are available on the cash account, the user will be able to cash out into the external bank account.
Now the user's cash account will also have an account and routing number associated with it. This can be used for direct cash (payroll, Paypal, Venmo, etc.) or direct debit (billpay, Venmo, Paypal, etc.).
Now your user has a fully functioning Deposit Hub! We would also recommend trying the following:
Unlike a Deposit Account, for the Cash Management account, Synapse Brokerage LLC is the Custodian of Funds. This enables us to keep funds at more than one bank - effectively giving your users higher than 250K FDIC Coverage (just like Multibank) or invest funds in the public markets through Money Market Funds, while the customer can still spend through their card. If funds are kept at a clearing house, they qualify for SIPC Insurance.
Step 1: or .
Step 2: to check Trust Level [1].
Step 3: Bases on Trust Level, or just standard docs.
[1] Trust Level is located under the documents object of the user document (trust_level
). If you are opening accounts for business or joint account users, please note that each base document has an ID Score value and Trust Level associated with it.
We call this program overview a Spec Sheet. of what a Spec Sheet looks like.
Since offering financial products pose a financial risk (see: ), understanding your operating capital and runway gives us the information we need to help underwrite you as a platform. This information also helps us determine what kind of payment limits we should be offering in the first iteration of your product.
This section helps break down, in Synapse terms, exactly what product you are looking to offer. The diagram above illustrates that the platform wants to issue two kinds of products (Interest Carrying Deposit and Custody) and one product (One-Time Loan).
The platform also intends to utilize our for funding the deposit account or paying bills, while also utilizing it for making loan repayments.
Lastly, the platform will be utilizing to enable direct debit or credits in and out of the user's deposit account. While also to build a debit card product on top of the deposit account and a charge card product on top of a custody account.
In this section, we document various users, the products and KYC required to enable those products. For instance, in this example, the platform will be opening accounts for three user segments, so we will be differentiating them with different CIP tags (see: ).
In this section, we ask that the platform articulates its KYC and Risk Strategy (see: ). This is benefical as it helps reduce the risk that accompanies offering a financial product.
In this section, we ask that the platform articulate its underwriting policy and strategy (see: ) for issuing loans. Providing an underwriting policy is an important part of providing access to credit responsibily as it can become a source of financial loss for the platform.
In this section, you will also find information on your Sub BINs and the Card Style IDs. Card Style IDs are used when you to your users.
Our Cash Management Account (CMA
) aka Global Cash 🌏 is an iteration of our Product line that enables individuals and businesses to hold deposits either with FDIC Insured Institutions (FDIC
) or in Money Market Funds (MMF
) based on their investment preferences.
For US Customers, the KYC Requirements . For non-US Customers:
All KYC will be backed. Based on trust_level
, we will collect the following:
For Universal Beneficial Owners (UBOs), the KYC is the same as listed . For the business itself, we will be collecting the following:
The next step will be to start performing actions on behalf of the user. To do that, you need to grab an token for the user.
To do that, usually, you make a API call and grab the refresh_token
from the user profile or get the refresh token from the create user call (like above).
Now the user's cash account will also have a card number associated with it. The card can be for spending online or through the of choice. The card can also be so that the user has a physical card at hand for use. You can also use our to emulate some transactions.
This will enable your platform to always stay up to date when changes/updates to the , , or objects occur.
Since CMA is just another feature, the following considerations still apply:
or any others mentioned on the page.
Use Case
Description
Global Banking
Using CMA to create an FDIC insured cash account with a debit card, account number and access to payments for users in 30+ countries.
Global Spend Cards
Using CMA to create an FDIC or SIPC insured cash account with a credit card on top that enables businesses and individuals to spend online.
Banking for Creators
Gamers, Influencers, Freelancers, etc.
Using CMA to create an FDIC or SIPC insured cash account with a card on top that enables creators to bank regardless of where they live. Especially helpful in situations where creator funds are only avaliable for people who are able to open accounts in the US.
Banking for Travelers Including Foreign Nationals - International Students, -ve Interest or High Inflation Markets.
Using CMA to create an FDIC insured cash account with a card, account number and access to payments that enables individuals to bank in USD. Especially helpful in situations your users are traveling a lot or local currency has high inflation or local banks have a net negative interest rate or spending in local currency incurs a high tax.
Virtual Docs
Social Docs
Physical Docs
DUNS
TIN
(if applicable)
ADDRESS
DATE
WEBSITE
MAILING_ADDRESS
MEMO_OF_INCORPORATION
BYLAWS_DOC
COI
LBL
PROFIT_LOSS
DBA_DOC
(if applicable)
BUS_REGISTRATION
ADDRESS
DATE
Feature
Details
Fully Managed Compliance
All KYC, AML, Transmission compliance handled by Synapse. Customers just have to worry about fraud and marketing.
One Platform
Once a customer is live with CMA, you can cross sell them a Credit Solution (US Only), all in one platform.
Passively Invest
We believe all deposit accounts should be a source of wealth creation. For that reason, funds in a CMA can also be invested in public markets through our High/Medium/Low risk Money Market Funds.
Global Reach
With Synapse, you can onboard individuals or businesses for USD accounts from 30+ countries from the very beginning. No need to add additional vendors.
Card Issuance
Instantly issue card numbers on top of deposit accounts, then load them into any mobile wallet of choice and/or ship a physical card with various shipping and card styling options, including metal.
AC/RT Issuance
Issue unique account numbers on top of cash accounts to enable SWIFT, ACH or FedWire transactions.
Robust Payments Stack
With Synapse, you get SWIFT, ACH, Fedwire, BillPay, Card Processing, Check Issuance, RPPS, ATM and Cash network access from the very beginning. No need to add additional vendors.
Revenue Generating
Accrue daily rebates on deposits kept with us and also generate interchange revenue for your platform.
Trust Level
Virtual Docs
Social Docs
Physical Docs
Notes
high
DRIVERS_LICENSE
TIN
ADDRESS
DATE
high
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
high
PASSPORT
TIN
ADDRESS
DATE
high
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
med
DRIVERS_LICENSE
TIN
ADDRESS
DATE
PASSPORT_BIODATA
med
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
PASSPORT_BIODATA
med
PASSPORT
TIN
ADDRESS
DATE
PASSPORT_BIODATA
med
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
PASSPORT_BIODATA
med
DRIVERS_LICENSE
TIN
ADDRESS
DATE
NATIONAL_ID
NATIONAL_ID_BACK
med
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
NATIONAL_ID
NATIONAL_ID_BACK
med
PASSPORT
TIN
ADDRESS
DATE
NATIONAL_ID
NATIONAL_ID_BACK
med
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
NATIONAL_ID
NATIONAL_ID_BACK
med
DRIVERS_LICENSE
TIN
ADDRESS
DATE
DRIVER_LICENSE
DRIVER_LICENSE_BACK
med
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
DRIVER_LICENSE
DRIVER_LICENSE_BACK
med
PASSPORT
TIN
ADDRESS
DATE
DRIVER_LICENSE
DRIVER_LICENSE_BACK
med
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
DRIVER_LICENSE
DRIVER_LICENSE_BACK
med
DRIVERS_LICENSE
TIN
ADDRESS
DATE
VOTER_REGISTRATION_CARD
VOTER_REGISTRATION_CARD_BACK
med
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
VOTER_REGISTRATION_CARD
VOTER_REGISTRATION_CARD_BACK
med
PASSPORT
TIN
ADDRESS
DATE
VOTER_REGISTRATION_CARD
VOTER_REGISTRATION_CARD_BACK
med
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
VOTER_REGISTRATION_CARD
VOTER_REGISTRATION_CARD_BACK
med
DRIVERS_LICENSE
TIN
ADDRESS
DATE
VOTER_REGISTRATION_CARD
VOTER_REGISTRATION_CARD_BACK
med
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
VOTER_REGISTRATION_CARD
VOTER_REGISTRATION_CARD_BACK
med
PASSPORT
TIN
ADDRESS
DATE
VOTER_REGISTRATION_CARD
VOTER_REGISTRATION_CARD_BACK
med
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
VOTER_REGISTRATION_CARD
VOTER_REGISTRATION_CARD_BACK
low
PASSPORT
TIN
ADDRESS
DATE
OTHER
NATIONAL_ID
NATIONAL_ID_BACK
VIDEO_AUTHORIZATION
low
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
OTHER
NATIONAL_ID
NATIONAL_ID_BACK
VIDEO_AUTHORIZATION
low
DRIVERS_LICENSE
TIN
ADDRESS
DATE
OTHER
DRIVER_LICENSE
DRIVER_LICENSE_BACK
VIDEO_AUTHORIZATION
low
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
OTHER
DRIVER_LICENSE
DRIVER_LICENSE_BACK
VIDEO_AUTHORIZATION
low
PASSPORT
TIN
ADDRESS
DATE
OTHER
DRIVER_LICENSE
DRIVER_LICENSE_BACK
VIDEO_AUTHORIZATION
low
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
OTHER
DRIVER_LICENSE
DRIVER_LICENSE_BACK
VIDEO_AUTHORIZATION
low
DRIVERS_LICENSE
TIN
ADDRESS
DATE
OTHER
PERMANENT_RESIDENT_CARD
PERMANENT_RESIDENT_CARD_BACK
VIDEO_AUTHORIZATION
low
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
OTHER
PERMANENT_RESIDENT_CARD
PERMANENT_RESIDENT_CARD_BACK
VIDEO_AUTHORIZATION
low
PASSPORT
TIN
ADDRESS
DATE
OTHER
PERMANENT_RESIDENT_CARD
PERMANENT_RESIDENT_CARD_BACK
VIDEO_AUTHORIZATION
low
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
OTHER
PERMANENT_RESIDENT_CARD
PERMANENT_RESIDENT_CARD_BACK
VIDEO_AUTHORIZATION
low
DRIVERS_LICENSE
TIN
ADDRESS
DATE
PASSPORT_BIODATA
VIDEO_AUTHORIZATION
low
DRIVERS_LICENSE
PERSONAL_IDENTIFICATION
ADDRESS
DATE
PASSPORT_BIODATA
VIDEO_AUTHORIZATION
low
PASSPORT
TIN
ADDRESS
DATE
PASSPORT_BIODATA
VIDEO_AUTHORIZATION
low
PASSPORT
PERSONAL_IDENTIFICATION
ADDRESS
DATE
PASSPORT_BIODATA
VIDEO_AUTHORIZATION
Risk, with regard to financial products, typically falls into two primary categories: Financial Risk and Regulatory Risk. While Financial Risk leads to direct losses to your operating capital, Regulatory Risk can lead to regulatory fines or other penalties. Ultimately both categories of risk have the potential to impact your operating capital, can impact your reputation, and in extreme cases may lead to the suspension of your program altogether.
Since both categories can cause disruptive events for your business, we recommend building Financial and Regulatory risk reduction strategies. In this resource, we will break down both types of risk and provide guidance to help you address them.
Risk Appetite
Policy
Conservative
We will not provide payment origination products to any customers. All customers will be required to fund their accounts with us via direct deposit or cash deposits that do not pose return risk.
Moderate
Before the policy, here are some definitions: ID Score A probabilistic score (0-1) assigned to all users at the time of onboarding that predicts the likelihood that the identity supplied belongs to the person who is creating the account. 1 meaning we are 100% certain that the user is who they say they are. 0% means with 100% certainty we can say that the user is not who they say they are.
Risk Score A probabilistic score (0-1) assigned to all users who are utilizing their accounts which predicts the likelihood that their subsequent transactions will lead to a financial loss.
Policy Reducing Onboarding Risk
We will be utilizing ID Score to reduce stolen profiles in our system, the idea being that a user is less likely to fraud us with their real identity. If a user's ID Score is below 0.8, we will be collecting additional documentation and performing enhanced due diligence before onboarding them to the platform.
Reducing Ongoing Risk
On top of that, we will be utilizing Risk Score to put people in green (over 0.9), yellow (0.5-0.89), and red (below 0.5) paths. Where the green path will give users uninterrupted access to all payment products, yellow will reduce all payment limits by 50% and red will reduce limits by 90%.
Aggressive
We will provide all payment products to customers and assume that financial fraud is an acceptable risk to the business.
Following are more details on Financial Risk by types:
ACH is a one-way messaging system for payment processing. Meaning, that a transaction in ACH is assumed to have succeeded unless the receiving bank sends a failure notice.
Based on the reason for failure, the receiving bank can have up to 60 days to return a transaction, assuming they have return rights. In practice this means if you released an ACH credit in 3 business days to your user, you might still receive a return up to 57 days later. Here are the most common return reasons:
❌ = Will not lock the user or node. ✅ = Will lock the user or node.
Code
Description
Locks Node
Locks User
R01
Insufficient Funds
❌
❌
R02
Account Closed
✅
❌
R03
No Account/Unable to Locate Account
✅
❌
R04
Invalid Account Number
✅
❌
R06
Returned Per ODFI's Request
❌
❌
R07
Authorization Revoked by Customer
✅
✅
R08
Payment Stopped
✅
❌
R09
Uncollected Funds
❌
❌
R10
Customer Advises Not Authorized
✅
✅
R11
Check Safekeeping Entry Return
❌
❌
R12
Branch Sold To Another DFI
✅
❌
R13
RDFI Not Qualified to Participate
✅
❌
R14
Account Holder Deceased
✅
✅
R16
Account Frozen
✅
❌
R17
File Record Edit Criteria
❌
❌
R20
Non-Transaction Account
✅
❌
R21
Invalid Company Identification
❌
❌
R22
Invalid Individual ID Number
❌
❌
R23
Credit Refused by Receiver
❌
❌
R24
Duplicate Entry
❌
❌
R29
Corporate Customer Advises Not Authorized
✅
✅
R31
Permissible Return Entry
❌
❌
R33
Return of XCK Entry
❌
❌
R34
Limited participation DFI
✅
❌
R68
Untimely Return
❌
❌
These returns are broken into three categories:
These returns occur when the account holder of the ACH account informs their bank (receiving bank) that the transaction was not authorized by them. NACHA guidelines allow account holders to take up to 60 days to dispute these kinds of transactions. Return codes R07, R10, and R29 signify unauthorized returns.
Administrative returns indicate that a transaction was returned due to administrative or account data errors. They occur within 3 business days of settlement. Return codes R02, R03, and R04 signify administrative returns.
Auto rejection logic is in place for ACH returns that occur 60 days or greater after transaction settlement. If an ACH return request is received after 60 days of the payment settlement date, the request will not be honored.
The rest of the returns are just other types of returns allowed by the ACH network. Like Administrative, these returns also occur within 3 business days of settlement.
Dishonoring a return is only allowed in circumstances where the return notice is late. This means, if Administrative and Other returns are coming to us after 3 business days or Unauthorized are coming after 60 days, then they can be dishonored. Otherwise, all other ACH Returns must be honored in compliance with the NACHA consumer protection guidelines.
Unlike ACH, Interchange (more popularly know as acquiring) is capable of giving you failure notices in realtime in almost all circumstances. However, there are some scenarios, known as chargebacks that can take up to 120 days.
Based on the reason for failure, the receiving bank can have up to 120 days to fail a transaction. This means, if you released an Interchange credit instantly to your user, you might still receive a failure notice (also known as a Chargeback) up to 120 days later. Here are the most common failure reasons:
Code
Description
Locks Node
Locks User
IR01
More information is needed from the card issuer
❌
❌
IR02
Refer to card issuer's unique transaction rules
❌
❌
IR03
Not recognized as a valid merchant
❌
❌
IR04
Card not activated for transaction use
❌
❌
IR05
Suspicious activity; do not honor this card's transactions
✅
❌
IR06
Error during transaction process
❌
❌
IR07
Card has unique conditions; currently not activated for transaction use
❌
❌
IR08
Needs more identification to process the transaction
❌
❌
IR09
Transaction requested; currently in progress
❌
❌
IR10
Transaction amount partially approved
❌
❌
IR11
Approved but not processed
❌
❌
IR12
Transaction invalid
❌
❌
IR13
Transaction amount invalid
❌
❌
IR14
Card number does not exist
✅
❌
IR15
Card issuer does not exist
✅
❌
IR17
Customer canceled/reversed payment
✅
❌
IR18
The customer reversed the transaction: chargeback
✅
✅
IR19
Please retry the transaction
❌
❌
IR20
Response from the card processor was invalid
❌
❌
IR21
Transaction formatted incorrectly (Potential reversal detected)
❌
❌
IR22
Suspected malfunction, reversal
❌
❌
IR23
Transaction fee was unacceptable
❌
❌
IR24
File update not supported by receiver
❌
❌
IR25
Unable to locate record on file
❌
❌
IR26
Duplicate file update record, no action taken
❌
❌
IR27
File update field edit error
❌
❌
IR28
Field update record locked out
❌
❌
IR29
File update not successful, contact the acquirer
❌
❌
IR30
Transaction formatted incorrectly (Potential reversal detected)
❌
❌
IR31
Transaction must be initiated in person, bank not supported by "switch"
❌
❌
IR32
Completed partially, reversal
❌
❌
IR33
Expired card, pick-up
✅
❌
IR34
Suspected fraud, pick-up
✅
✅
IR35
Card acceptor must contact acquirer, pick-up
❌
❌
IR36
Restricted card, pick-up
✅
❌
IR37
Merchant must contact the card security
❌
❌
IR38
PIN tried too many times; request a new card or try again later
✅
❌
IR39
No credit account tied to credit card
❌
❌
IR40
Function requested can not be carried out
❌
❌
IR41
Lost card: request a new card
✅
❌
IR42
Account tied to card is not universal
❌
❌
IR43
Stolen card: request a new card
✅
❌
IR44
Investment account not on required
❌
❌
IR45 - IR50
Reserved for ISO use
❌
❌
IR51
Insufficient funds (NSF)
❌
❌
IR52
Checking account not associated with the card
❌
❌
IR53
Savings account not associated with the card
❌
❌
IR54
Card Expired: request a new card
✅
❌
IR55
Pin tried is incorrect
❌
❌
IR56
No record of the validity of the card
❌
❌
IR57
Transaction not permitted to cardholder
❌
❌
IR58
Transaction denied by acceptor (Potential chargeback detected)
❌
❌
IR59
Fraud suspected
✅
✅
IR60
Merchant must contact the card acquirer
❌
❌
IR61
Transaction exceeds card limits
❌
❌
IR62
Card restricted
❌
❌
IR63
Card information compromised (Potential chargeback detected)
❌
❌
IR64
Original amount incorrect, reversal
❌
❌
IR65
Current transactions exceeds withdrawal frequency limit
❌
❌
IR66
Merchant must contact the card acquirer
❌
❌
IR67
Hard capture
❌
❌
IR68
Response received too late, reversal
❌
❌
IR69 - IR74
Reserved for ISO use
❌
❌
IR75
Allowable number of PIN tries exceeded
❌
❌
IR76
Key synchronization error
❌
❌
IR77
Reserved for private use
❌
❌
IR78
Customer not eligible for POS
❌
❌
IR79
Invalid digital signature
❌
❌
IR80
Stale date transaction
❌
❌
IR81
Issuer requested standin
❌
❌
IR82
Count exceeds limit
❌
❌
IR83
Reserved for private use
❌
❌
IR84
Time limit for pre-authorization reached
❌
❌
IR85
Issuer has no reason to decline the transaction (Account Verification)
❌
❌
IR86
Cannot verify PIN
❌
❌
IR87
Check already posted
❌
❌
IR88
Card information not on file
❌
❌
IR89
Security code verification failed
❌
❌
IR90
Card cutoff is in progress
❌
❌
IR91
Card change in progress or not taking effect
❌
❌
IR92
Intermediate network/financial institution is unknown
❌
❌
IR93
Transaction is in violation of the law and will not be completed
❌
❌
IR94
Duplicate transaction
❌
❌
IR95
Error with transaction reconciliation
❌
❌
IR96
System error during transaction
❌
❌
IR97 - IR98
Reserved for national use
❌
❌
IR99
Card network error during transaction
❌
❌
IR100 - IR126
Reserved for ISO use
❌
❌
IR127
SEC is invalid
❌
❌
IR128
Address and verification check data is required for this transaction
❌
❌
IR129
Security code date is required for the transaction
❌
❌
IR130 - IR131
Transaction not permitted to cardholder
❌
❌
IR132
Country of the card issuer is blocked by this merchant
❌
❌
IR133
Incorrect MAC was sent
❌
❌
IR134
Standard Entry Class requirements were not met
❌
❌
IR135
System error during transaction
❌
❌
IR136
Account length error
❌
❌
IR137
Card information error
❌
❌
IR138
Security code format error
❌
❌
IR139
Internal authorization error
❌
❌
IR140
Card product code is blocked
❌
❌
IR141
Attempt to process a BRIC transaction on a prior PIN based transaction
❌
❌
IR142
CyberSource Time Out Connection to CyberSource timed out
❌
❌
IR143
CARD_ENT_METH supplied is not valid or required additional data not provided as defined
❌
❌
IR144
CARD_ID is not valid
❌
❌
IR145
Required PIN block not present
❌
❌
IR146
Card Bin is not valid for pin-less routing
❌
❌
IR147
Signature store did not complete
❌
❌
IR148
Debit PIN transactions must be swiped
❌
❌
IR149
DB proxy response was not processed within the time out period
❌
❌
IR150
Transaction declined by merchant to security code mismatch
❌
❌
IR151
Transaction not allowed as per a validation rule
❌
❌
IR152
Processing gateway full: poll again later
❌
❌
IR153
Authorization life cycle unacceptable
❌
❌
IR154
Authorization life cycled expired
❌
❌
IR155
Card authentication failed
❌
❌
IR156
Fraudulent transaction prior to embossed valid date
❌
❌
IR157
Credit not received
❌
❌
IR158
Allowable PAN entries warning -- approved
❌
❌
IR159
Transaction approved with card overdraft protection
❌
❌
IR160
Security code is invalid
❌
❌
IR161
Internal transaction processing error
❌
❌
IR162
Check not acceptable for cash
❌
❌
IR163
Check not acceptable
❌
❌
IR164
Check deposit limit exceeded
❌
❌
IR165
Cash back limit exceeded
❌
❌
IR166
Check amount does not match courtesy amount
❌
❌
IR167
PIN not selected for card
❌
❌
IR168
PIN already selected for card
❌
❌
IR169
Unmatched voucher information
❌
❌
IR170
Card number entered too many times
✅
❌
IR171
Expiration date not valid for card
✅
❌
IR172
Card status is set to inactive
❌
❌
IR173
Expiration date mismatch: request a new card
✅
❌
IR174
Item suspected for stop pay
❌
❌
IR175
Account associated with card was closed
❌
❌
IR176
Account associated with card is ineligible for the transaction
❌
❌
IR177
Duplicate transaction
❌
❌
IR178
No account associated with card on file
❌
❌
IR179
Unable to locate card
❌
❌
IR180
Transaction denied
❌
❌
IR181
Transaction settled via ACH
❌
❌
IR182
Cross-reference card not found
❌
❌
IR183
Category limit exceeded
❌
❌
IR184
Transaction limit exceeded
❌
❌
IR185
Daily limit exceeded
❌
❌
IR186
Monthly limit exceeded
❌
❌
IR187
Invalid secret code
✅
❌
IR188
Pin key sync error
❌
❌
IR189
Bad security code
❌
❌
IR190
Transaction ordered to be stopped
❌
❌
IR191
Transaction authorization revoked
❌
❌
IR192
Stop reoccurring payments
❌
❌
IR193
Card lost: do not honor
❌
❌
IR194
Account associated with the card is closed
❌
❌
IR195
Account associated with the card is inactive
❌
❌
IR196
Card has unique conditions: do not honor
❌
❌
IR197
Purchase only approval for purchase with cash back transaction
❌
❌
IR198
Card does not have sufficient funds for the transaction fees (NSF Card)
❌
❌
IR199
Card chip failed during transaction
❌
❌
IR200
PIN compromised
✅
❌
IR201
MasterCard MoneySend Error: Incorrect Expiration date
❌
❌
IR202
MasterCard MoneySend Error: Card declined due to an unknown reason
❌
❌
IR203
MasterCard MoneySend Error: Card declined due to unsupported card type
❌
❌
IR204
MasterCard MoneySend Error: Card declined due to an unknown reason
❌
❌
IR205
MasterCard MoneySend Error: Card declined due to an unknown Reason
❌
❌
IR206
MasterCard MoneySend Error: Card transaction request has an unknown status
❌
❌
IR999
Unauthorized Chargeback return
✅
✅
Card processing presents both return and chargeback risk, which are different types of returns. An interchange return refers to a transaction being rejected by the network when it is unable to be processed for a variety of reasons. Meanwhile, chargebacks take place when a transaction occurs and settles, but a user disputes the transaction with the card issuer.
All IR
failure codes are instant, except IR999
. IR999
is considered an unauthorized chargeback. This means that the customer claims that they did not authorize this transaction and the user has up to 120 days to dispute interchange transactions with this failure code.
High chargeback rates can potentially lead to substantial fines by card networks, inclusion on the Terminated Merchant File for up to 5 years (a list of merchants deemed high-risk by card networks), and/or suspension from the card networks.
Chargebacks also present financial loss risk as any negative balance, resulting from chargebacks will be reconciled from the platform’s reserve account.
An exception to the zero-liability policies would occur if there is evidence that the user was grossly negligent or if there was a substantial delay by the user in reporting the unauthorized transaction to its card issuance institution. Evaluating when this exception applies will be at the discretion of the card networks, platforms can submit evidence prior to evaluation of their case.
Unlike ACH and Interchange, FedWires do not pose a financial risk to you as they are only outgoing, so there is no risk of returns and financial losses. However, it's important to note that FedWires are irreversible. So it is important to ensure that they were indeed originated by the sender and all the details submitted are accurate before originating them with us.
This can be done by features like enabling MFA right before originating a FedWire and showing the customer a summary page and urging them to check all the details before origination.
Though FedWires do not fail for lack of funds, they can still fail for the following reasons:
Code
Description
WR01
Return Per Customer Request - Returned per customer request.
WR02
Return Per Platform Request - Returned per platform request.
WR03
Account Closed/Frozen - The receiving account is closed/restricted/frozen, therefore the wire cannot be credited.
WR04
Compliance Concerns (Additional Documents Required) - We have identified red flags which require further investigation. The wire has been returned and we have requested additional documentation.
WR05
Country Not Allowed - The specified country is not allowed per the platform's controls and the wire has been returned.
WR06
Exceeds User's Limits - The transaction exceeds the user's daily, monthly, and/or annual limits.
WR07
Exceeds Platform's Limits - The transaction exceeds the platforms' daily, monthly, and/or annual limits.
WR08
Name Mismatch - The recipient's name in the wire instructions does not match the name on file with us.
WR09
Inactive Account - The receiving account is inactive, or unverified therefore the wire cannot be credited.
WR10
Invalid Account Number - The account number in the wire instructions does not match the account number on file with us.
WR11
Duplicate Transaction - Duplicate transaction, the duplicate has been returned.
WR12
Outside of Allowed Flow of Funds - The account number in the wire instructions is not a valid account number on file with us.
SWIFT behaves similarly to FedWires. They do not pose a financial risk to you as they are only outgoing, so there is no risk of returns and financial losses. However, it's important to note that SWIFT Wires are irreversible. So it is important to ensure that they were indeed originated by the sender and all the details submitted are accurate before originating them with us.
This can be done by features like enabling MFA right before originating a SWIFT Wire and showing the customer a summary page and urging them to check all the details before origination.
Though SWIFT Wires do not fail for lack of funds, they can still fail for the following reasons:
Code
Description
R69
multiple errors: {e}
Failed to establish a new connection: Connection timed out
SSL: CERTIFICATE_VERIFY_FAILED
R83
transaction failure: {e}
Issue with Transfer API - Transfer failed to create
uncategorized error: {e}
Pending RouteFusion KYC Verification
Pending RouteFusion Beneficiary Verification
Unable to Retrieve Transfer
User Not Found
WR01
Return Per Customer Request - Returned per customer request.
WR02
Return Per Platform Request - Returned per platform request.
WR03
Account Closed/Frozen - The receiving account is closed/restricted/frozen, therefore the wire cannot be credited.
WR04
Compliance Concerns (Additional Documents Required) - Synapse has identified red flags which require further investigation. The wire has been returned and we have requested additional documentation.
missing information: {e}
The beneficiary country (FR) requires that the bank account be provided in IBAN format.
Issue with Beneficiary API - Missing Payload Information
WR05
Country Not Allowed - The specified country is not allowed per the platform's controls and the wire has been returned.
WR06
Exceeds User's Limits - The transaction exceeds the user's daily, monthly, and/or annual limits.
WR07
Exceeds Platform's Limits - The transaction exceeds the platforms' daily, monthly, and/or annual limits.
WR08
Name Mismatch - The recipient's name in the wire instructions does not match the name on file with Synapse for the account.
WR09
Inactive Account - The receiving account is inactive, or unverified therefore the wire cannot be credited.
WR10
Invalid Account Number - The account number in the wire instructions does not match the account number on file with Synapse.
WR11
Duplicate Transaction - Duplicate transaction, the duplicate has been returned.
WR12
Outside of Allowed Flow of Funds - The account number in the wire instructions is not a valid account number on file with Synapse.
WR13
Return per ODFI Request (Recall Received) - Returned per sending FI's request, a recall was received.
WR14
Detailed transaction reason not sufficient - The transaction details are not sufficient for Synapse to understand the purpose of the wire.
WR15
Beneficiary address invalid - The beneficiary’s address is either incomplete or invalid.
WR16
Beneficiary name invalid - The beneficiary’s name is either incomplete or invalid.
WR17
Below $1,000 USD minimum - Wire amount must equal at least $1,000 USD.
WR18
Verbal verification form required - The verbal verification form is missing from the transaction.
WR19
Verbal verification form invalid - The verbal verification form has at least one error that renders it invalid.
WR20
Correspondent bank details invalid - The name, address or ABA/SWIFT of the correspondent bank is invalid.
Under the hood, RPPS is just a private ACH rail. Since all RPPS transactions are push transactions, they do not pose a financial risk. Even though RPPS do not fail for lack of funds, they can still fail for the following reasons:
Code
Description
R02
Account Closed
R03
Account Number Invalid
R04
Wrong Account Number
R05
Pre-Notification Error
R06
Originator Requested Return
R07
Authorization Revoked
R08
Payment Stopped Settlement
R09
Uncollected Funds
R10
Advised Unauthorized
R12
Branch Sold
R14
Payee Deceased
R15
Beneficiary Deceased
R16
Account Frozen
R17
File Edit -Record Criteria
R18
Wrong Entry Date
R19
Account Error
R20
Non Transaction Account
R21
Wrong BillerId
R22
Account Number Mistake
R23
Payment refused by Biller
R24
Duplicate Entry
R25
Fair share Amount
R29
Advised Unauthorized
R31
Permissible Return Entry
R42
Routing Number Error / Check Digit Error
R43
DFI account Number
R61
Misrouted Return
R62
Trace Number Error
R63
Dollar Amount Mismatch
R64
Individual Identification
R65
Invalid Transaction Code
R66
Invalid Company Identification
R67
Duplicate Return
R68
Untimely Return
R69
Multiple Errors
R70
Permissible Return Entry Not Accepted
R71
Misrouted Dishonored Return
R72
Untimely Dishonored Timely
R73
Timely Original Return
R74
Corrected Return
R80
Cross Border Payment Coding Error
R81
Non-Cross Border Participant
R82
Foreigner Receiver ID
R83
Unable to Settle
R84
Not Processed
R85
Fair Share Rebate
Like RPPS, checks are another way for your users to pay bills. Since they are credit only, they do not pose a financial risk. Even though checks do not fail for lack of funds, they can still fail for the following reasons:
Code
Description
CHR03
Stop payment – a stop payment has been placed on the item
CHR15
Unable to process
Like ACH, RDC is a one-way messaging system for payment processing. Meaning, that a transaction in RDC is assumed to have succeeded unless the receiving bank sends a failure notice.
Based on the reason for failure, the receiving bank can have up to 60 days to fail a transaction. This means, if you released an RDC credit in 3 business days to your user, you might still receive a failure note (also known as a Return) up to 57 days later. Here are the most common return reasons:
Code
Description
CHR01
NSF – customer does not have sufficient funds to cover the item
CHR02
UCF – uncollected funds hold
CHR03
Stop payment – a stop payment has been placed on the item
CHR04
Closed account – the item’s account has been closed
CHR05
UTLA – unable to locate account
CHR06
Frozen/blocked account – account has restrictions placed by customer or bank
CHR07
Stale dated – the date on the item is more than 6 months old
CHR08
Post dated – the date on the item is in the future
CHR09
Endorsement missing
CHR10
Endorsement irregular
CHR11
Signature(s) missing
CHR12
Signature(s) irregular, suspected forgery
CHR13
Non-cash item (non negotiable)
CHR14
Altered/fictitious item/Suspected counterfeit/Counterfeit
CHR15
Unable to process
CHR16
Items exceeds stated max value
CHR17
Not Authorized (Includes Drafts/Remotely Created Checks) – Unauthorized item such as a draft/RCC
CHR18
Branch/account sold (Wrong Bank)
CHR19
Refer to Maker
CHR20
Item cannot be re-presented (exceeds allowable number of presentments
CHR21
Unusable image
CHR22
Cannot determine amount
CHR23
Refer to image – return reason is contained within the image of the item
CHR24
Duplicate Presentment (Supporting documentation shall be readily available)
CHR25
Forgery – an affidavit shall be available upon request
CHR26
Warranty breach (includes Rule 8 & 9 claims)
CHR27
RCC warranty breach
CHR28
Forged and counterfeit warranty breach (Rule 9)
CHR29
Retired/ineligible routing number
CHR30
Image Missing
CHR31
Ineligible Item
CHR32
Item cannot be re-presented (exceeds number of allowable times for presentment)
CHR33
unusable image
CHR34
Image fails security check
CHR35
Duplicate presentment
CHR36
Does not conform with ANS X9.100-181
CHR37
Does not conform to the Industry’s Universal Companion Document
CHR38
Warranty Breach (includes Rule 8 & Rule 9 claims)
CHR39
RCC Warranty Breach (Rule 8)
CHR40
Forged and Counterfeit Warranty Breach
CHR41
Retired/Ineligible Routing Number
These returns are broken into three categories:
These returns occur when the account holder of the bank account that the check belongs to informs their bank (receiving bank) that the transaction was not authorized by them or points out some other fraudulent issues with the check. RDC guidelines allow account holders to take up to 60 days to report checks as unauthorized. Return codes CHR03, CHR14, CHR17, CHR24, CHR25, and CHR26 signify unauthorized returns.
Administrative returns indicate that a transaction was returned due to administrative or account data errors. They occur within 3 business days of settlement. Return codes CHR02, CHR03, and CHR04 signify administrative returns.
The rest of the returns are other types of returns allowed by the RDC network. Like Administrative, these returns also occur within 3 business days of settlement.
If an RDC is returned due to forgery, there is no time limit against its return.
For that reason, it's important for you to have a credit underwriting strategy. A good credit underwriting strategy should try to assess two things:
Propensity to Pay
Willingness to Pay
A good way to understand a user's willingness to pay is to measure the user's engagement with your platform. If a user finds value in your products and services, they will be more inclined to pay back the obligations through your platform over others.
Based on the above definitions, here are some examples of how you might choose to design your Credit Risk Policy, based on your overall risk appetite:
Risk Appetite
Policy
Conservative
We will not provide any unsecured credit products. Customers will be required to keep funds in a loan reserve which will equal to total credit issued to them.
Moderate
Policy Propensity to Pay
Willingness to Pay
We will only solicit the user for a credit account after they have been using the platform for over 6 months.
Ladder Up
The users that do not fit the above parameters will only be offered secured loans and later laddered up into an unsecured loan.
Aggressive
We will provide $100 line of credits to customers to measure their willingness to pay and assume this as the cost of customer acquisition. Once history is built, the user will be able to request higher amount of loans.
Regulatory Risk can lead to regulatory fines. Which impacts your operating capital and in extreme cases can cause suspension of your program altogether.
Synapse is responsible for transaction monitoring as part of our relationship with our partner banks. We work with our financial institutions behind the scenes to investigate and report activity as we monitor transactions across your platform. Due to the confidential nature of these reports, we are unable to share if or when we recommend a transaction or a user to be reported to FinCEN and/or other government agencies.
It is important to understand that Synapse's transaction monitoring and reporting structure does not absolve any obligations that you may have as a company independent of Synapse. For example, if your business is registered with FinCEN, and therefore has its own screening and reporting obligations, Synapse does not provide these controls as a service to you.
Credit Hub is a platform that allows you to open various types of credit accounts for individuals or businesses via an API call.
Our mission is to ensure that everyone has access to high quality financial services. So it doesn't matter if your customers are underbanked, recently immigrated, small/medium/large business owners. With Credit Hub, you can onboard customers from all walks of life.
The different accounts we offer have different characteristics, regulatory restrictions, among other distinctions. This variety allows us to offer the best solution for each use case. Please refer to the tables below for an idea of the distinctions between our accounts.
Account Type
Account Code
Description
Open
OPEN
Open Credit Accounts have flexible credit limits which are tied to the funds the user is holding in their deposit account. This account type is ideal for building a neo banking platform on a credit BIN for higher interchange or for charge cards.
Revolving
REVOLVING
The credit limit is determined at the time the credit account is created and is backed by funds in the user’s reserve account for secured credit cards, or not, in case of unsecured credit cards.
One-Time
ONE-TIME
This Credit account is meant for one time use only. Ideal for POS financing or cash advance products.
Cash Advance
REPAY-US
This account is meant for payroll-based cash advances. Ideal for overdraft protection type products built on top of Deposit Hub or external bank accounts.
Credit Hub can be used for pretty much any application that requires an embedded credit account. But we have seen our customers building the following use cases most frequently with this offering:
Use Case
Description
Buy Now Pay Later
Issue one time loans to your customers to enable online or in-person shopping. Either disburse the loan via a card issued by you or in an external account via ACH or Push to Card.
Spend Card
Enable customers to enjoy flexible credit limits based on the cash at hand, spend on a credit BIN for cashback rewards, or build credit.
Credit Builder
Issue one-time or revolving loans to enable your customers to build credit.
Credit Card
Issue a secured or unsecured revolving loan and a card to unlock a traditional credit card experience for your customers.
Please note, KYC requirements will differ between individuals and business users, and might further vary depending on the use case and the nature of the user. Here are minimum KYC requirements by account type and user type:
Account Type
Individuals
Businesses
OPEN
Name, Date of Birth, Address, Email, Phone, and SSN.
On Business:
Business Name, Address, Entity Formation Date, Entity Type (LLC, Corp, etc), Entity Scope (Industry), Email, Phone Number of the Business, and TIN.
On Beneficial Owners:
Name, Date of Birth, Address, Email, Phone, and SSN.
REVOLVING
Name, Date of Birth, Address, Email, Phone, and SSN.
On Business:
Business Name, Address, Entity Formation Date, Entity Type (LLC, Corp, etc), Entity Scope (Industry), Email, Phone Number of the Business, and TIN.
On Beneficial Owners:
Name, Date of Birth, Address, Email, Phone, and SSN.
ONE-TIME
Name, Date of Birth, Address, Email, Phone, and SSN.
On Business:
Business Name, Address, Entity Formation Date, Entity Type (LLC, Corp, etc), Entity Scope (Industry), Email, Phone Number of the Business, and TIN.
On Beneficial Owners:
Name, Date of Birth, Address, Email, Phone, and SSN.
REPAY-US
Name, Date of Birth, Address, Email, Phone, and SSN.
On Business:
Business Name, Address, Entity Formation Date, Entity Type (LLC, Corp, etc), Entity Scope (Industry), Email, Phone Number of the Business, and TIN.
On Beneficial Owners:
Name, Date of Birth, Address, Email, Phone, and SSN.
Synapse's lending entity Synapse Credit LLC will be the lender for the loans. This means it will be underwriting all the lines and serving the loans to the end users or businesses.
To reduce the risk of losses for our lending entity, either the end user will be required to put 1:1 collateral in a reserve account (in case of secured loan products) or you (the platform) will be required to do so while acting as a guarantor of the loans. So in instances where loans default, the reserves will be tapped for covering the losses.
You may also choose to enable credit reporting with us. Currently, if enabled, all credit accounts of your customers will be reported by the 10th of each month for the previous calendar month. Since Synapse's lending entity Synapse Credit LLC is the lender of record, the credit report may show only Synapse Credit LLC or both Synapse Credit LLC and your name on the credit file, depending on the configuration of your program with Synapse.
As a part of any good responsible credit model, a robust credit decisioning policy is a core part of the program. When building credit policies, please consider the following decisioning constructs:
You can filter which of your users has the option to apply for a loan based on various decisioning criteria, we refer to these as prerequisites. Common examples are that the user has been in the platform ecosystem for over six months or that they are part of the platform's premium service.
Although you can propose prerequisites, they will all have to be communicated in detail and be approved by us as the lender of record. Furthermore, if you wish to make a change to your prerequisites, the change will have to be first explained in detail and approved by Synapse for the same reasons.
At a basic level a loan can be rejected based on the following criteria:
Lending is not currently available for the user's CIP tag or user type.
The requested amount is above the defined maximum per user loan size of your platform.
The loan will put you over the limits of the amount (in dollar value) of loans you are allowed to issue.
We handle basic decisioning on our end.
Outside of Prerequisites and Basic Decisioning, some use cases will also require the option to reject a loan after the application process has started. For example, you may receive the user's income level and decide that it is too low. Because this information might be captured after the loan application process started, it cannot reasonably be considered a prerequisite.
As a part of the Fair Lending Act, we are responsible for ensuring that all applicants are being impacted (not just treated) equally and not being discriminated against. As a part of that commitment, we will also be doing regular audits in our system to check for any direct or indirect discriminatory decisioning.
You can supply the APR on a loan at the time of creating a credit account for the end user. At loan creation, you will have the option to set the APR from 0% up to your maximum APR. The maximum rate that can be charged on a loan varies by state.
Since you are not the lender of record, you cannot directly benefit from the interest charged on the loan. For that reason, interest payments go from the user's credit account to Synapse Credit LLC's account.
In some cases, user accounts are eligible to receive payments for deposits kept with us. Here is how those logistics work:
Interest is accrued daily on active credit nodes and impacts the balance.
The interest transaction will be coming from the loan node and go to a Synapse Credit LLC node, with from.meta.type:LOAN_INTEREST
and extra.note:LOAN_INTEREST
.
Interest will be calculated and defined at the moment of the user’s loan approval and will accrue and compound daily against the outstanding balance based on the APR set for the loan node.
Like standard credit cards, revolving lines do not charge interest if the total statement balance is paid on or before the statement payment due date (e.g. before the end of the month following the statement cycle). The statement cycle starts on the first day of the month and ends on the last day of the month.
The statement balance is the balance at the end of the statement cycle (i.e. the balance on the last day of the month). Interest will start to accrue for the statement balance at the beginning of the next statement cycle (i.e. the next day, which will be the first day of the month). Interest will not be charged if the statement balance is paid on the statement payment due date, but the user will owe any accrued interest for any balance remaining after the statement payment due date.
The next statement balance will include any withdrawals and payments made in that month, as well as any unpaid balance from previous months plus the unpaid accrued interest for that month. Once the statement cycle ends, the new statement balance is defined and this amount will be owed. This means that if the new statement balance is paid in full by the statement payment due date, no interest will be owed.
For example, if at the close of a statement cycle, the outstanding balance is -$500.
This means that if the statement is delivered on the 7th of the next month, the user would be responsible for paying the -$500 statement balance in full by the end of the month to avoid paying interest charges on that balance.
Please keep in mind that interest will start to accrue on the -$500 statement balance immediately. If payment is made after the grace period (i.e. at or past the end of the month), the user will have to pay all of the accrued interest for the statement balance from the beginning of the current month.
If the user makes a partial payment before the statement payment due date (i.e. before month-end), the payment will count towards the statement balance due and the user will be responsible for paying the interest accrued on the remaining amount.
Our Advance product allows you to issue interest-free, fee-free, short-term one-time advances to users. Our current implementation only allows for 0% APR advances with no fees per provided advance due to regulatory constraints on payroll cash advances.
If a user is delinquent on one or more loan payments, interest will continue to accrue and compound daily.
Interest will continue to accrue until the loan reaches the cap amount set for the loan. Once interest charges reach the cap amount, interest will stop accruing. Currently, if a credit account has had no positive payments for 90 days or more, we consider the credit account to be in delinquent status.
Synapse has added Minimum Payment support to give Platforms the ability to offer relief to consumers that are having difficulty paying their entire balance each month. The Synapse minimum payment feature is in compliance with CFPB guidelines. The minimum payment is configurable on the Platform level via the Synapse Spec Sheet. Once configured, the minimum payment is calculated and added to the consumer's monthly statement. The statement also includes the CFPB minimum payment warning, which calculates the amount the consumer will pay in interest over time if they make only the minimum payment. The promissory note for revolving and open loans contains a new paragraph governing minimum payments.
To spin up a Credit Hub for a user, here are the steps you can follow:
The first step is to create a user account and supply all of their KYC. Once the user account has been created, grab the refresh_token
from the response which will be needed to issue an OAuth key for the user.
To avoid 2FA, please use the fingerprint value that you used while creating the user account. Once the OAuth key is issued, grab oauth_key
which will be needed to launch credit hub.
You have an ACH-US
node linked to the user profile. This means that the user can repay balances on their credit account via an external bank account or if funds are available on the credit account, the user will be able to cash out into the external bank account.
Before launching a Credit Hub, please ensure one of the following has happened:
That's it. You've successfully created a credit account for your user.
Now let's enable some features on this credit account. Please note, these features are available for all credit accounts except Cash Advances.
Now your user has a fully functioning Credit Hub! We would also recommend trying the following:
Deposit Hub is a platform that allows you to open deposit accounts for individuals or businesses via an API call.
Our mission is to ensure that everyone has access to high quality financial services. So it doesn't matter if your customers are underbanked, recently immigrated, small/medium/large business owners. With Deposit Hub, you can onboard customers from all walks of life.
The different deposit accounts we offer have different characteristics, KYC requirements, regulatory restrictions, among other distinctions. This variety allows us to offer the best solution for each use case. Please refer to the tables below for an idea of the distinctions between our deposit accounts.
Account Type
Account Code
BIN Type
Description
Interest Carrying Deposit Account
IC-DEPOSIT-US
Debit
A bank account that carries interest. This account is ideal for creating a debit card product.
FBO Sub Account
SUBACCOUNT-US
Debit
A Sub Account issued to the end user inside your FBO Account. This account is ideal for creating a low KYC automated savings product.
Custody Account
CUSTODY-US
Pre-Paid
An alternative to the deposit account, where the account is held under a trust vs a bank allowing a lower KYC wallet solution. Ideal for creating Fiat Wallet products.
Clearing Account
CLEARING-US
Credit
Non-FDIC insured account created for payment processing purposes. Ideal for creating merchant processing or payment processing solutions.
Deposit Hub can be used for pretty much any application that requires an embedded deposit account. But we have seen our customers building the following use cases most frequently with this offering:
Use Case
Description
Digital Wallet
A digital wallet enables your customers to store funds with you and use our full stack payment features to enable access to funds.
Merchant Processing
Use our deposit and payments stack to create fully white-labeled payment processing solutions that include merchant processing accounts for your customers.
Savings Account
Create interest-bearing savings accounts to enable healthier financial habits for your customers.
Debit Card
Open deposit accounts, issue cards, and account numbers to create a neo-banking platform for your customers.
Spend Card
Open a custody account, issue a card, use instant auth to fund the card at the time of transaction.
KYC will vary if the account is opened for an individual or a business and also by the type of Deposit account being opened. Here are minimum KYC requirements by account type and user type:
Account Type
Individuals
Businesses
IC-DEPOSIT-US
Name, Date of Birth, Address, Email, Phone, and SSN.
On Business:
Business Name, Address, Entity Formation Date, Entity Type (LLC, Corp, etc), Entity Scope (Industry), Email, Phone Number of the Business, TIN, EIN Verification Letter issued by IRS, Company Bylaws and Articles of Incorporation.
On Beneficial Owners:
Name, Date of Birth, Address, Email, Phone, and SSN.
SUBACCOUNT-US
Name, Date of Birth, Address, Email, and Phone.
On Business:
Business Name, Address, Entity Formation Date, Entity Type (LLC, Corp, etc), Entity Scope (Industry), Email and Phone Number of the Business.
On Beneficial Owners:
Name, Date of Birth, Address, Email, and Phone.
CUSTODY-US
Name, Date of Birth, Address, Email, Phone, and SSN.
On Business:
Business Name, Address, Entity Formation Date, Entity Type (LLC, Corp, etc), Entity Scope (Industry), Email, Phone Number of the Business, and TIN.
On Beneficial Owners:
Name, Date of Birth, Address, Email, Phone, and SSN.
CLEARING-US
Name, Date of Birth, Address, Email, and Phone.
On Business:
Business Name, Address, Entity Formation Date, Entity Type (LLC, Corp, etc), Entity Scope (Industry), Email and Phone Number of the Business.
On Beneficial Owners:
Name, Date of Birth, Address, Email, and Phone.
We reconcile negative balances for deposit accounts in two ways:
Instantly: If an account reaches a negative balance of -$300 or lower, the user account will be closed and the negative balance will be reconciled immediately.
In 30 days: For any account with more than -$300 in balance, we reconcile negative balances when accounts remain negative with no settled transaction with a created on date within the last 30 days. Post reconciliation, the user account will be closed.
For example: If a user has a negative balance of -$250 and they pay +$150 toward that negative balance before the 30-day period is up, we will reset the 30-day countdown based on the created on date of that successful transaction. If another 30 days pass and there is no successful activity, we will try to reconcile the remaining negative balance of -$100 from the user's other accounts, and if there are no other accounts or there are insufficient funds, we will reconcile the -$100 from your reserve funds.
Once the User account is closed, it will be closed for permission_code:NEGATIVE_BALANCE
in this state, the user will not be allowed to send new payments, but the user will still be allowed to create Me2Me transfers going into the account that was closed due to negative balance. Once that transaction settles, the user account will be reopened again, since the user would've effectively reconciled their negative balance.
If the account balance is greater than $0 we will send a check with the remaining balance to the mailing address or base doc address we have on file for the user.
If the final balance payment returns to us (e.g. the account was closed, the address is out-of-date or "undeliverable", etc.), then the funds will stay in the closed account until a new payment to an updated account is initiated by you.
In some cases, user accounts are eligible to receive payments for deposits kept with us. Here is how those logistics work:
Interest is accrued daily and disbursed monthly to accounts that provide interest. This is done automatically (on the 2nd business day of the following month) and not initiated by the platform. We will also track fractional interest to distribute when the fractional interest reaches an integer amount.
The interest transaction will be coming from node type EXTERNAL-US
. These transactions will have from.meta.type
value as INTEREST
.
In some cases, you are eligible to receive payments for deposits kept with us. Here is how those logistics work:
Rebate is accrued daily and disbursed monthly to your platform deposit account. This is done automatically on the 15th of the following month. We will also track fractional interest to distribute when the fractional interest reaches an integer amount.
The interest transaction will be coming from node type EXTERNAL-US
. These transactions will have from.meta.type
value as REBATE
.
Our vision for Deposit Hub is to empower FinTech companies to be live with multiple banks at the same time. Our Multi Bank feature is our first step in that direction.
Here is a good visualization of how Multi-Bank Functions:
If enabled, Multi Bank automatically sweeps and stores customer deposits at 2-3 banks, while still giving the user access to all the funds they have in their deposit account. Sweeping funds over $250K per bank extends the FDIC coverage from $250K to $500-750K for your customers.
Since this feature is enabled behind the scenes, no API updates are needed on your side. You will however need to update the following:
Disclosures in your product collateral for the increased FDIC Coverage and also to add the partner banks participating in the Multi Bank program.
Put in opt-in language for your customers so that they can subscribe to the program and agree to us sweeping their deposits.
To spin up a Deposit Hub for a user, here are the steps you can follow:
The first step is to create a user account and supply all of their KYC. Once the user account has been created, grab the refresh_token
from the response which is needed to issue an OAuth key for the user.
To avoid 2FA, please use the fingerprint value that you used while creating the user account. Once the OAuth key is issued, grab oauth_key
which will be needed to launch deposit hub.
First please preview the deposit agreement to the user, once they agree, create the deposit account.
That's it. You've successfully created a deposit account for your user.
Now let's enable some features on this deposit account.
Now you have an ACH-US
node linked under the user profile. This means the user can fund their deposit account via an external bank account or if funds are available on the deposit account, the user will be able to cash out into the external bank account.
Now the user's deposit account will also have an account and routing number associated with it. This can be used for direct deposit (payroll, Paypal, Venmo, etc.) or direct debit (billpay, Venmo, Paypal, etc.).
Now your user has a fully functioning Deposit Hub! We would also recommend trying the following:
OAuth keys currently expire after 2 hours. After an OAuth key expires, you can use a refresh token to generate a new OAuth Key. Please remember to take OAuth key expiration into account when building out your application.
Please note that you can only store up-to 110 valid fingerprints per user and the fingerprints follow a first in first out logic (FIFO).
This architectural decision is made to keep a limited number of fingerprints registered with a user profile to reduce security risks. A first in first out logic is chosen so that the oldest fingerprints are cycled out first.
If you OAuth with a new device (i.e. a new fingerprint), you will need to Register New Fingerprint.
Along with OAuth, we also use device fingerprints for authentication. Fingerprints are used to identify the device that is trying to access a user's information. You need to supply fingerprints when you create a user. The fingerprint supplied during the POST
user creation is the registered fingerprint associated with the user.
If the user supplies a non-verified fingerprint during login, the user will be directed to the 2FA flow. We return the linked phone numbers in the API call response with key phone_numbers
. You can let the user select the phone number from that list and then make the API call again by specifying the phone_number
you want the 2FA to be sent. This will trigger the 2FA protocol and a PIN will be sent to the selected phone number. The user will be able to verify the device via this API call itself. You can supply validation_pin
under the user object and the verification will be triggered.
We strongly recommend using 2FA or some form of MFA within your authentication process.
If you do not want to use our 2FA, store the fingerprint used when creating the user and supply the fingerprint when performing actions with the user. This way the system will not detect a new device and no 2FAs will be triggered.
Alternatively, you can also pass a hashed version of your user_pk
+client_id
+client_secret
. That way the value is still somewhat secret and you won't need to store a different fingerprint for each user.
That's it! Now you have everything you need to be able to start playing with Synapse's APIs.
We usually recommend downloading Postman and getting a feel for our APIs before writing code. The following steps will make this process easier.
If you've downloaded our Postman collection, you should be seeing our APIs on the left and the appropriate environment variables on the right.
The next step is to add your own client keys into the environment variables.
The next step is to create a user account and supply all of their KYC.
If you are curious about the user profile and want to see more details, just click on the user, the dashboard will show you all the information you just added to the user profile.
Same as before, we will automatically set the appropriate OAuth key for you.
Also, when you Sign in as a User on the dashboard, the same operation is happening behind the scenes.
You can Sign In by supplying the fingerprint you created the user account with:
Now, you can perform all the actions on behalf of the user from the dashboard, like how you can with the APIs.
Now if you'll go back to the dashboard, you will see the Deposit Node under the user profile.
Congratulations! 🎊 🎈 🎉 You've successfully created a deposit account for your user.
Now let's enable some features on this deposit account.
In this case, our user would like to enable ACH Credits and Debits via an External Account. So let's link an external ACH account:
Now let's verify the ACH account via Micro-deposits:
Now if you go to the dashboard, you will see an ACH-US
node linked under the user profile with Credit and Debit
permissions.
Our user would also like to issue an account and routing number that they can give to their payroll provider and apps like Venmo and PayPal. So let's issue an account number for them:
Now if you go to the dashboard, Sign In as User, and click on the Deposit Account, you will see the account and routing numbers issued on the account:
Our user would also like to issue a card so they can use this account for shopping and other expenses. So let's issue one for them:
Now if you go to the dashboard, Sign In as User, and click on the Deposit Account, you will see the card number issued on the account:
Now your user has a fully functioning Deposit Hub!! 😀
Let's get our Webhook URL:
Now let's create a Subscription:
You will be able to see this subscription created on the dashboard as well:
To test this, let's issue another account number for our user:
Since we had subscribed to SUBNETS|POST
updates, you will see a webhook set to your Webhook Site link:
You can view the logs on the dashboard as well:
As our final step of this tutorial, let's fund our user's deposit account so that they can go out and spend:
If you'll go to the dashboard, you will see the transaction created:
In a few minutes, the transaction will move to settled:
Now our user has funds in their account to spend:
To provide the right solution for your use case, we offer a variety of payment accounts. Please refer to this section for more information on our payment solutions and specifics for each payment type. These are the payment accounts we currently support:
We offer Same-Day and Standard (Next-Day) ACH transfers for both ACH pushes (credits) and ACH pulls (debits).
ACH transfers are batch-processed by the Federal Reserve, which requires institutions to adhere to cutoff times for the transaction batches.
We will require a short additional time to process ACH transactions on our end before transmitting the transaction data to the Federal Reserve. Our cutoff times are:
We are assuming that:
If that is true, then here is how you can initiate ACH:
We currently support Pulls and Pushes for Credit, Debit and Prepaid cards issued by Visa, Mastercard, and some smaller networks such as STAR, Pulse, Accel, and NYCE. Please note, that not all issuers enable push to card on their side. So pushing funds to those cards will fail.
Interchange transfers do not have cutoff times because they are processed near real-time and can sometimes take up to 30 minutes to settle.
We are assuming that:
If that is true, then here is how you can initiate Interchange Transactions:
Wire transfers have cutoff times because the bank's have account reconciliation obligations with the Fed. Our cutoff times are:
We are assuming that:
If that is true, then here is how you can initiate a Fedwire:
Wire transfers have cutoff times because the bank's have account reconciliation obligations with SWIFT. Our cutoff times are:
We are assuming that:
If that is true, then here is how you can initiate a SWIFT transfer:
We send and receive wires in USD. Any currency conversions will be performed either by the sending financial institution (for incoming wires) or the receiving financial institution (for outgoing wires) rather than by Synapse directly. Exchange rates can differ by the currency being converted, the entity performing the currency conversion, and even by the associated correspondent bank. Please note that the exchange rates provided to you by the entity performing the conversion will likely differ from rates you may see online (e.g. from Google search results). The entity should provide proper disclosures with both the amount in USD and the amount in the foreign currency.
Wire transfers have cutoff times because the bank's have account reconciliation obligations with RPPS. Our cutoff times are:
We are assuming that:
If that is true, then here is how you can initiate a RPPS transfer:
Check transfers have cutoff times because all check payments are printed and batched together once a day. Our cutoff times are:
We are assuming that:
If that is true, then here is how you can initiate a Check transfer:
RDC transfers are batch-processed by the Federal Reserve, which requires institutions to adhere to cutoff times for the transaction batches.
We will require a short additional time to process RDC transactions on our end before transmitting the transaction data to the Federal Reserve. Our cutoff times are:
We are assuming that:
If that is true, then here is how you can initiate a RDC transfer:
Checks are verified by our computer vision modules and for that reason it's very important to ensure that a clean image of the check is submitted to our system. The image should have all 4 corners of the check visible, without additional background and everything should be well lit and clearly visible.
The RDC image processing system does use advanced processing techniques such as image orientation, cropping and noise reduction to help eliminate manual reviews of check images and allow faster processing overall.
Internal transfers do not have cutoff times because they are near real-time and can sometimes take up to 30 minutes to settle.
We are assuming that:
They are trying to move money between two Synapse managed nodes.
If that is true, then here is how you can initiate Internal Transactions:
Virtual Doc values to include meta.country_code
, .
Virtual Doc values must include meta.country_code
, .
Physical Doc values must include meta.state_code
, meta.country_code
and meta.id_number
as well, .
Virtual Doc values must include meta.country_code
, .
Physical Doc values must include meta.state_code
, meta.country_code
and meta.id_number
as well, .
Virtual Doc values must include meta.country_code
, .
Physical Doc values must include meta.state_code
, meta.country_code
and meta.id_number
as well, .
Virtual Doc values must include meta.country_code
, .
Physical Doc values must include meta.state_code
, meta.country_code
and meta.id_number
as well, .
Virtual Doc values must include meta.country_code
, .
Physical Doc values must include meta.state_code
, meta.country_code
and meta.id_number
as well, .
Virtual Doc values must include meta.country_code
, .
Physical Doc values must include meta.state_code
, meta.country_code
and meta.id_number
as well, .
Financial Risk exists when a user spends funds in their account without intending to repay them or uses the "float" (the time it takes for transactions to process and settle) to overspend. In the case of , this can occur by taking credit from you, but then defaulting on the repayment obligation. While in the case of , it can occur by funding their account via one of the and spending the funds knowing that that original transaction will return, thus overdrawing their balance and leaving the platform with limited options to recoup funds. Other than and , financial risk is primarily created by providing customers access to . Since payments can return up to 60 days after a credit has been applied to a customer's account, payment processing exposes you to financial loss risk.
Based on the above statement, a valid conclusion is that most of your financial risk can be adjusted by adjusting access to . With that in mind, here are some examples of how you might choose to design your Financial Risk Policy, based on your overall risk appetite:
We currently provide a solution for ID Score. Go to Product Guide to learn more.
Card returns don’t create direct financial risk to platforms because transactions are immediately rejected and funds are sent back to the user in real time. Nevertheless, it's good practice for you to build logic to keep track of card returns, we have found that successive returns can be a red flag for future chargebacks and/or fraudulent activity. TRAN|PATCH
will notify when returns occur.
Regulation E sets forth time limitations for disputed transaction investigations. Financial institutions may take up to 120 days to investigate the reported dispute/error. During the beginning of this period, you have the option to submit evidence against the dispute via the API call. Common examples of evidence are email communication & interactions, shipping verification, phone call transcripts, live chat transcripts, social media interactions, and similar. We will submit all evidence to the network for investigation.
Due to the zero-liability policies of card networks (e.g. , ), if the transaction is proven to be unauthorized you will have to pay the amount of the chargeback (i.e. the funds the platform received plus the interchange fee of the original transaction), regardless of whether they believe the transaction is fraudulent or not. The end user will receive credit for the transaction.
Recalling a wire is a process that requires us to contact the receiving bank and requesting them to reverse the wire back to us. This process is manual and the likelihood of success is low. It is also important to understand that financial institutions have no requirement to respond to our recalls. For that reason, we recommend . But in rare situations that wires still need to be recalled, please create a ticket requesting a wire recall by emailing .
Recalling a wire is a process that requires us to contact the receiving bank and requesting them to reverse the wire back to us. This process is manual and the likelihood of success is low. It is also important to understand that financial institutions have no requirement to respond to our recalls. For that reason, we recommend . But in rare situations that wires still need to be recalled, please create a ticket requesting a wire recall by emailing .
If a check payment has not SETTLED
yet (refer to ), the user can still choose to stop the check payment using API call.
Even though we are the lender of record on all loans issued through , you are still the guarantor of all credits extended through your platform (see to learn more).
A good way to understand a user's propensity to pay is by getting a holistic understanding of the user's debt-to-income ratio. This means understanding all the income sources and all the debt obligations the user has on a regular basis. There are quite a few tools in the market for this like traditional FICO or Assets and Liability features are a good way to measure a user's debt-to-income ratio.
We will use Assets and Liability features to measure a customer's propensity to pay. All users will need to have a debt-to-income ratio of lower than 0.5 to be approved for the loan. All loans provided will have an installment less than or equal to half of the user's monthly disposable income (income - existing debts).
If you are going to issue Debit or Credit Cards to your users, then you also need to consider the financial risk of issuing provisional credits. Since you will lose most disputes, these credits are a source of financial losses for all FinTech platforms providing card products. Most card transactions that are , are entitled to a provisional credit.
To learn more about Card Disputes and Provisional Credits, See .
As a part of building a financial product, you are also expected to comply with , , , and any other applicable financial regulations. As we build your program, we also provide specific guidance on how to comply with those regulations.
Please note that the above requirements assume that (which includes real-time SSN verification) is being used for Individuals and Beneficial Owners. If not, US Government Photo ID (GOVT_ID
,GOVT_ID_BACK
) will also be required for all users and beneficial owners.
Please note, filtering the user before solicitation is considered a prerequisite. If you are deciding to decline a loan after the loan application flow has begun, that requires booking an adverse action. Please see for more details.
The user does not have SEND-AND-RECEIVE
permissions (which occurs when not all relevant KYC has been submitted or verified) or if the user is a match in one of our sanctions lists. Go to page to learn more.
For any loans that you reject, you will be required to book an adverse action in our system so that we have a record of this action. Please see for more details.
If a user is delinquent in making their loan payments, as described above, a transaction will be created from your reserve account to the user's credit account to zero out the balance. At that point, the node will be set to INACTIVE
with ACCOUNT_CLOSED
as the allowed code. To learn more about which values are allowed, go to .
Once a credit account is terminated, you would find a termination letter (also known as "Loan Termination Adverse Action Notice") in the response (within the info.agreements
object in the response with type TERMINATION_LETTER
). You are required to share it with the user via email as this is considered an Adverse Action. To learn more about potential agreement types, go to .
The next step will be to start performing actions on behalf of the user. To do that, you need to grab an token for the user.
To do that, usually, you make a API call and grab the refresh_token
from the user profile or get the refresh token from the create user call (like above).
Linking an external ACH account is a good way to have a disbursement and repayment account ready before a loan is issued. You can also enable your users to link an or even just use for the same purpose.
If you wish to provide unsecured loans, please make sure your loan reserve account is funded for the portfolio that you wish to issue. Go to to learn more.
Or, if the product is secured, please ensure that the customer's loan reserve account (LOAN-RESERVE-US
) has been . If you are issuing an open loan, then you can just issue an open loan without any funds in the customer's loan reserve account since open loans have dynamic limits and are a function of the funds available in the reserve account. But if you are issuing a revolving loan, please ensure that the customer loan reserve account has been before issuing a loan.
The next step is to have the customer preview the credit account agreement to the user, once they agree, create the credit account (, , or ).
Now the user's credit account will also have a card number associated with it. The card can be for spending online or through the of choice. The card can also be so that the user has a physical card at hand for use. You can also use our to emulate some transactions.
This will enable your platform to always stay up to date when changes/updates to the , , or objects occur.
Please note that the above requirements assume that (which includes real-time SSN verification) is being used for Individuals and Beneficial Owners. If not, US Government Photo ID (GOVT_ID
,GOVT_ID_BACK
) will also be required for all users and beneficial owners.
These reconciliations occur throughout the day, and funds will be debited from the user's other accounts (if available) or from your Reserve Account to reconcile the balance. We recommend setting up to monitor your reserve account balance. This will help you automatically fund your reserve when it falls below your required minimum balance.
To learn more about how an account can be overdrawn, go to .
Before closing an account, we strongly recommend moving the funds out of the account being closed to another internal or external account. However, if you fail to move the funds prior to account closure and the account closure reason allows for auto-cashout (see ), payout of the remaining balance will occur the following way:
For IC-DEPOSIT-US
nodes, we will generate users' 1099-INT tax forms at the end of the year. This can be accessed via .
We will generate users' 1099-INT tax forms for the rebate provided to you at the end of the year. You will be able to access the forms via or through the dashboard.
If you are interested in enabling Multi Bank, .
The next step will be to start performing actions on behalf of the user. To do that, you need to grab an token for the user.
To do that, usually, you make a API call and grab the refresh_token
from the user profile or get the refresh token from the create user call (like above).
Now the user's deposit account will also have a card number associated with it. The card can be for spending online or through the of choice. The card can also be so that the user has a physical card at hand for use. You can also use our to emulate some transactions.
This will enable your platform to always stay up to date when changes/updates to the , , or objects occur.
We use a variation of OAuth 2.0 for user authentication. This means that to perform any user actions, or to make any changes to a user, you need to supply a valid OAuth Key in the header field of the API request. Read more about what to include in our headers .
An OAuth key is a token representing a user's identity. See for more information on creating an OAuth key. The OAuth key will be returned in the response of this API call and will be used in the headers of subsequent API calls to allow users to perform other actions.
To get the OAuth key for a new user, find refresh_token
from the or .
Additionally, you can incorporate two-factor authentication ("2FA") into your user login process when your user connects with a different device. To do so, just supply the new, non-verified fingerprint. See to register a new device fingerprint to the user account and use our two-factor authentication (2FA) security protocols.
, to sign up for a sandbox account.
2. Finish On-Boarding. This step might feel onerous, but behind the scenes, it gives us the information we need to enable the appropriate features for you on sandbox. KYC information supplied here can be fake or real. If it is real, we can use this information to enable production access for you when you are ready to go live with us. If fake, you will need to finish the same setup on our .
3. to get client credentials.
|
Once the user account is created, to see the user there. If everything is right, you will see the user go to Send and Receive
Permissions on the dashboard.
The next step will be to start performing actions on behalf of the user. To do that, you need to grab an token for the user.
To do that, usually, make a API call and grab the refresh_token
from the user profile. With our Postman collection, all of that is automated.
So the next step is to . Currently, we will make an OAuth key with all the scopes. .
In this section, pick a hub you wish to enable for the user ( or ). In this example, we will pick Deposit Hub.
PS: We would also recommend trying out our to emulate some card transactions.
In our next step, let's use to test subscribing to updates as they occur in the system.
As next steps, we would recommend: 1. Taking our language SDKs for a spin: | | | | .
2. Reviewing our Resource.
3. when ready.
ACH (Automated Clearing House) payments are an electronic form of payment between US bank accounts. They are a common and cost-effective way to transmit funds. Unlike other payment types, ACH transfers are not guaranteed funds and face the risk of returns up to 60 days after the transaction is settled (although most returns occur within 2-3 days). Read more about ACH Risk under .
ACH Transactions are enabled in your Spec Sheet. To learn more, go to .
The user you wish to enable transfers for is already in our system and has SEND-AND-RECEIVE
permissions. Go to API Refs to learn more.
There is already a or account created in the system where the funds need to be sent from or to.
There are two ways to link an ACH account. Either by supplying the login credentials to the user's bank account or by supplying the account and routing numbers. Both are highlighted under section.
The next step is to . Either from
an ACH node or to
an ACH node.
Storing or transmitting card numbers requires platforms to be . So please do not store card numbers in your system unless you are PCI compliant.
Interchange Processing pushes/pulls funds for external debit or credit cards. Interchange Transactions are near-instant, and thus much faster than alternative transaction methods. However, they expose the platform to chargeback risk and are generally more expensive than ACH transactions, especially for larger amounts, as their cost (with the exception of Push-to-Debit) is in part based on a percentage of the transferred amount. Read more about Interchange Risk under .
Interchange Transactions are enabled in your Spec Sheet. To learn more, go to .
The user you wish to enable transfers for is already in our system and has SEND-AND-RECEIVE
permissions. Go to API Refs to learn more.
There is already a or account created in the system where the funds need to be sent from or to.
The first step is to instance in our system. Once that is done, the node will either have DEBIT
, CREDIT
or CREDIT-AND-DEBIT
permissions which would guide you in what types of transfers are enabled on this card by the issuer. Go to to learn more.
The next step is to . Either from
an Interchange node or to
an Interchange node.
Wires offer the benefit of being guaranteed funds that settle relatively quickly. While wires are more expensive than ACH transactions, they face no return risk, making them ideal for large sum transactions or situations where return risks need to be eliminated. Because they can't be returned, wires do pose some risks for the originator. Go to to learn more.
We currently use for this feature.
Fedwire Transactions are enabled in your Spec Sheet. To learn more about that, go to .
The user you wish to enable transfers for is already in our system and has SEND-AND-RECEIVE
permissions. Go to API Refs to learn more.
There is already a or account created in the system where the funds need to be sent from.
The first step is to instance in our system. Once that is done, the node will have CREDIT
permissions. Go to to learn more.
The next step is to . You will be sending funds from
the deposit or credit account, to
the Wire node.
SWIFT offers a way to send funds to family, friends, and businesses outside of the US. Additionally, while wires are more expensive than domestic transactions, they face no return risk, making them ideal for situations where return risks need to be eliminated. Due to the non-return nature of SWIFT, they do pose some risks for the originator. Go to to learn more.
SWIFT Transactions are enabled in your Spec Sheet. To learn more, go to .
The user you wish to enable transfers for is already in our system and has SEND-AND-RECEIVE
permissions. Go to API Refs to learn more.
There is already a or account created in the system where the funds need to be sent from.
The first step is to instance in our system. Once that is done, the node will have CREDIT
permissions. Go to to learn more.
The next step is to . You will be sending funds from
the deposit or credit account, to
the SWIFT node.
(Remote Payment and Present Service) is an electronic payment network that enables Platforms to provide bill payment services to consumers. RPPS provides electronic routing, settlement services, billing, and online research tools to facilitate electronic bill payments (including online bill payment request processing). While financial institutions currently cannot process bill payments to foreign merchants via RPPS, it is possible that such functionality may be available at a future date. While RPPS has reduced fraud risk, RPPS transactions can still return. Go to to learn more.
RPPS Transactions are enabled in your Spec Sheet. To learn more, go to .
The user you wish to enable transfers for is already in our system and has SEND-AND-RECEIVE
permissions. Go to API Refs to learn more.
There is already a or account created in the system where the funds need to be sent from.
The first step is to that you wish to connect.
The next step is to instance in our system. Once that is done, the node will have CREDIT
permissions. Go to to learn more.
The next step is to . You will be sending funds from
the deposit or credit account, to
the RPPS node to pay the bill.
Our checks allows you to issue and mail checks on demand from any or account. You may use checks for bill pay because they are accepted by all services and utility providers. While check issuance has reduced fraud risk, transactions can still return. Go to to learn more.
Check Transactions are enabled in your Spec Sheet. To learn more, go to .
The user you wish to enable transfers for is already in our system and has SEND-AND-RECEIVE
permissions. Go to API Refs to learn more.
There is already a or account created in the system where the funds need to be sent from.
The next step is to instance in our system. Once that is done, the node will have CREDIT
permissions. Go to to learn more.
The next step is to . You will be sending funds from
the deposit or credit account, to
the Check node.
Remote Deposit Capture (RDC) is a form of payment in which users can deposit a check by taking a picture of it. RDC is more convenient than depositing a check at an ATM or at a bank branch because it allows users to make the check deposit from the comfort of their home. However, it exposes the platform to standard RDC fraud and return risks. Similar to ACH, RDC transfers are not guaranteed funds and face the risk of returns up to 60 days after the transaction is settled (although most returns occur within 2-3 days). Read more about RDC Risk under .
RDC Transactions are enabled in your Spec Sheet. To learn more, go to .
The user you wish to enable transfers for is already in our system and has SEND-AND-RECEIVE
permissions. Go to API Refs to learn more.
There is already a or account created in the system where the funds need to be credited to.
An RDC transfer does not require creating a node, so all you need to do is to .
With Internal Transactions you can transfer funds between Synapse managed nodes (eg. , , etc.) in near real-time.
Internal Transactions are enabled in your Spec Sheet. To learn more, go to .
The user you wish to enable transfers for is already in our system and has SEND-AND-RECEIVE
permissions. Go to API Refs to learn more.
The first step is to , and there are no second steps 🙂.
ACH Type
Cutoff Time
Settlement Time
Same Day
11:00 AM PT
Same Business Day Transactions sent after the cutoff time will be included in the Next Day ACH batch at 3:00 PM PT. Same-Day pricing will still apply.
Next Day
3:00 PM PT
Next Business Day Transactions sent after the 3:00 PM PT cutoff time will be included in the following business day's ACH batch.
Cutoff Time
Settlement Time
12:00 PM PT
Same Business Day Domestic Wire transactions sent after the cutoff time will be processed the following business day.
Cutoff Time
Settlement Time
9:00 AM PT
Same Business Day International Wire transactions sent after the cutoff time will be processed the following business day.
Cutoff Time
Settlement Time
1:00 PM PT
Same Business Day Transactions sent after the cutoff time will be included in the following business day's RPPS batch.
Cutoff Time
Settlement Time
3:00 PM PT
Will vary by the external bank the check is being deposited to. Once the check has been deposited, the bank will hold the funds for a period of time before clearing the check.
Cutoff Time
Settlement Time
3:00 PM PT
Credits for RDC transactions are issued and settled in 6 business days by default. This timeline can be slightly reduced, but doing so will significantly increase your exposure to NSF returns which occur within the first 3 business days following deposits.
GET
https://api.synapsefi.com/v3.1/users
This endpoint allows you to get all users linked to your client keys.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20
.
page
integer
Page number of the paginated request. Default is 1
.
show_refresh_tokens
string
Set to NO
if you wish not to receive refresh tokens for all users returned. Default is YES
.
X-SP-USER
string
Your OAuth key and device fingerprint, separated by a pipe. For this request OAuth can be left blank since X-SP-GATEWAY
will be used for authentication. But device fingerprint is still required.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/users/:user_id
This endpoint allows you to get a specific user document.
user_id
string
ID of the user to get.
full_dehydrate
string
Set to YES
if you wish to receive all user PII in the response. Default is NO
.
X-SP-USER
string
Your OAuth key and device fingerprint, separated by a pipe. For this request OAuth can be left blank since X-SP-GATEWAY
will be used for authentication. But device fingerprint is still required.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/users/entity-types
This endpoint allows you to get and view all the available entity types.
X-SP-USER
string
Your OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/users/entity-scopes
This endpoint allows you to get and view all the avaliable entity scopes.
X-SP-USER
string
Your OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Currently we do not allow users to create multiple profiles within your environment in our system. So we use various techniques to detect duplicates in our system. In instance you run into a profile that was closed because it's a duplicate profile, the following API calls will enable you to recover a closed profile. The only way you can accomplish that is by swapping the profile by the open duplicate profile. So the closed profile opens and the open profile takes it place.
GET
https://api.synapsefi.com/v3.1/users/:user_id/get-duplicates
This endpoint returns all the accounts that are duplicates of the user.
X-SP-USER
string
OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
reason
Description
duplicate_tin
User profile detected as duplicate due to same TINs.
duplicate_ssn
User profile detected as duplicate due to same SSNs.
duplicate_name_and_address
User profile detected as duplicate due to same name and address.
duplicate_name_and_email
User profile detected as duplicate due to same name and email.
duplicate_name_and_date_of_birth
User profile detected as duplicate due to same name and dob.
duplicate_name_and_drive_license_number
User profile detected as duplicate due to same name and DLN.
blacklisted_user
User profile is closed because this user is blacklisted in our system.
not_known
Reason unknown.
PATCH
https://api.synapsefi.com/v3.1/users/:user_id/swap-duplicate-users
This endpoint allows you to swap one closed user profile with another in instances of duplicate profiles.
X-SP-USER
string
OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
swap_to_user_id
string
User ID you'd like to swap the open status with.
Key
Type
Required
Description
_id
String
N.A. Included in API response
Primary Key of the user object.
account_closure_date
Number
N.A. Included in API response
client.id
String
N.A. Included in API response
The Primary Key that denotes your client object in our system.
client.name
String
N.A. Included in API response
Your common name in our system.
documents
Array of Dict
Optional
Contains all the KYC information associated with the user profile.
extra.cip_tag
Int
Optional
extra.date_joined
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the user object was created.
extra.is_business
Boolean
Optional
If the user profile is a business, the value is true
. Default is false
.
extra.last_updated
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the user object was last updated.
flag
String
Depends. Only required if you are trying to flag a user.
If FLAGGED
, the user is flagged in our system. Default is NOT-FLAGGED
.
flag_code
String
Depends. Only required if you are trying to flag a user.
permission
String
Depends. Only required if you are trying to close or lock a user account.
permission_code
String
Depends. Only required if you are trying to close or lock a user account.
ips
Array of Strings
N.A. Included in API response. You will be supplying this in the request header when creating a user account X-SP-USER-IP
Known IPs that the user is using to operating their account.
legal_names
Array of Strings
Required during POST
Legal names the user profile will be using.
logins.email
String
Required during POST
email of user.
logins.password
String
Depends. Only required if you wish to use Synapse email/password authentication
password associated with login.
logins.scope
String
Depends. Only required if you wish to use Synapse email/password authentication
If READ
, the user credentials can only read user info. Default is READ-AND-WRITE
.
phone_numbers
Array of Strings
Required during POST
Phone number associated with user login credentials.
refresh_token
String
N.A. Included in API response
supp_id
String
Optional
Unique platform side identifier
watchlists
String
N.A. Included in API response
Flag Code
Description
Next Steps
Set By
NOT_KNOWN
Flag reason unknown.
No next steps recommend here since legacy tag.
Legacy tag, deprecated now.
ACCOUNT_CLOSURE|BLOCKED_INDUSTRY
User operates in a blocked industry.
Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
ACCOUNT_CLOSURE|HIGH_RISK
User is deemed high risk.
Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
PENDING_UPLOAD|DOC_REQUEST|CIP
Additional documents are required to be able to make a decision on user account.
Submit documents listed in documents.required_edd_docs
. Once all documents are submitted, the user will go to PENDING_REVIEW|DOC_REQUEST|CIP
. If documents not submitted, Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
PENDING_UPLOAD|DOC_REQUEST|UAR
Additional documents are required to be able to make a decision on user account.
Submit documents listed in documents.required_edd_docs
. Once all documents are submitted, the user will go to PENDING_REVIEW|DOC_REQUEST|UAR
. If documents not submitted, Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
PENDING_UPLOAD|DOC_REQUEST|SECURITY
Additional documents are required to be able to make a decision on user account.
Submit documents listed in documents.required_edd_docs
. Once all documents are submitted, the user will go to PENDING_REVIEW|DOC_REQUEST|SECURITY
. If documents not submitted, Account will be closed and the user's funds will be mailed back to them on the account_closure_date
.
us
PENDING_REVIEW|DOC_REQUEST|CIP
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
PENDING_REVIEW|DOC_REQUEST|UAR
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
PENDING_REVIEW|DOC_REQUEST|SECURITY
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
PENDING_REVIEW|ACCOUNT_CLOSURE|BLOCKED_INDUSTRY
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
PENDING_REVIEW|ACCOUNT_CLOSURE|HIGH_RISK
You have requested Synapse to review and decision the user account and any additional documents that we need have been submitted to us.
User account is under review by us. Pending a decision.
you
Permission
Description
Next Steps
Set By
UNVERIFIED
User KYC review unfinished. No account or payment activity allowed.
us
RECEIVE
User KYC review finished. User is allowed to only receive payments, not originate or authorize any payments.
us
SEND-AND-RECEIVE
If this is an acceptable final permission, no additional steps needed.
us
LOCKED
User KYC review finished and user has been locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
CLOSED
User KYC review finished and user has been closed.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
MAKE-IT-GO-AWAY
User account has been unindexed. It's like the account never existed.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
Permission
Description
Next Steps
Set By
NOT_KNOWN
Permission reason unknown.
No next steps recommend here since legacy tag.
Legacy tag, deprecated now.
UNUSUAL_ACTIVITY|COMPLIANCE_SUSPICIOUS
The user conducted suspicious activity and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
UNUSUAL_ACTIVITY|LEGAL_REQUEST
The user account has been closed due to some legal request that was received.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
KYC_FRAUD|BLOCKED_LIST
User is in a blocked list and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
KYC_FRAUD|FRAUDULENT_DOCS
User supplied fraudulent KYC documents and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
BLOCKED_INDUSTRY
User is operating in a blocked industry and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
HIGH_RETURNS
User has high returns increasing the risk of loss of funds and for that reason the account has been closed or locked.
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
NEGATIVE_BALANCE
User account has been closed due to a negative balance in their account.
Once the user is able to fund their account, either with direct deposit or payment origination, the account will return back to its previous state.
us
PLATFORM_REQUEST
User account has been closed or locked by you or by our team based on your request
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you
USER_REQUEST
User account has been closed or locked by you or by our team based on user request
Please ensure that the user has been notified of this adverse action and no funds access have been restricted and the user has been able to cash out remaining balance in their account(s).
you or us
DUPLICATE_ACCOUNT
The user account has been closed because another account with the same KYC on your platform exists in our system
Please ensure that the user has access to their open account thus eliminating the need to open a new duplicate account. You can also view all duplicate accounts for a particular user and then swap the account closure decision from one account to another.
us
Please note that the user will be cashed out automatically from the system if any one of the codes are picked:
UNUSUAL_ACTIVITY|COMPLIANCE_SUSPICIOUS
BLOCKED_INDUSTRY
PLATFORM_REQUEST
USER_REQUEST
PLATFORM_TERMINATED
NO_ACTIVITY
PERMANENT_CLOSURE
When a user is auto cashed out, we will issue a check to their mailing address, if avaliable or else to the base document address on file.
Permission
Description
Next Steps
PENDING
User Object is pending screenings review.
SOFT_MATCH|PENDING_UPLOAD
User is a soft match on one or more relevant sanctions list. A document upload is needed to further evaluate the soft match.
MATCH
User Object is a match on a sanctions screenings list.
SOFT_MATCH
User is a soft match on one or more relevant sanctions list.
No action required on your side. We will review the user object to either decision it as MATCH
or FALSE_POSITIVE
.
NO_MATCH
User Object is a not a match on any relevant sanctions screenings list.
No action required.
FALSE_POSITIVE
User Object was a soft match on one or more relevant sanctions screenings list. But now has been decisioned as a FALSE_POSITIVE
match.
No action required.
Key
Type
Required
Description
address_city
String
Yes
address_country_code
String
Yes
ISO Alpha-2 formatted Address country code of the business location or individual's residence.
address_postal_code
Integer
Yes
Address zip/postal code of the business location or individual's residence.
address_street
String
Yes
Address street of the business location or individual's residence.
address_subdivision
String
Yes
Address subdivision (state) of the business location or individual's residence.
alias
String
No
Common name for the individual/entity.
day
Integer
Yes
Day of entity formation for business or Birth date for individual.
month
Integer
Yes
Month of entity formation for business or Birth month for individual.
year
Integer
Yes
Year of entity formation for business or Birth year for individual.
company_activity
Array of String
Yes if business base doc
Allowed values: "MSB","LENDING","NON-US_OFFICE","NON-US_ACTIVITY","CRYPTO","PUBLIC","PRIVATE","REGISTERED_WITH_SEC","OTHER","NBFI-US","NBFI-FOREIGN","LISTED-US","LISTED-FOREIGN","NFP","BANK-US","BANK-FOREIGN","FUND"
.
desired_scope
String
No
doc_option_key
String
No
docs_key
String
No
docs_title
String
No
edd_status
String
N.A. Included in API response
email
String
Yes
Email of the individual/entity associated with this base document.
entity_scope
String
Yes
entity_type
String
Yes
entity_relationship
String
Yes if individual base doc on business user
Allowed values: CONTROLLING_PERSON
,UBO
.
id
String
Yes if you wish to PATCH
an existing base doc
Primary key of the base document. This value is a local primary key, meaning, it's only unique within a user object. Different user objects can have same base doc IDs.
id_score
Number
N.A. Included in API response
trust_level
String
N.A. Included in API response
ip
String
Yes
IP of the individual/entity associated with this base document.
is_active
Boolean
No
If false
, base document wont participate in user permission decisioning. Default is true
.
name
String
Yes
Name of the individual/entity associated with this base document.
maiden_name
String
No
Maiden name of the individual. Helpful to provide this in instances where the individual's maiden name is still associated with their TIN/SSN.
ownership_percentage
Number
Yes if individual base doc on business user
Percentage of the business owned by the beneficial owner.
permission_scope
String
N.A. Included in API response
phone_number
String
Yes
Phone number of the individual/entity associated with this base document.
physical_docs
Array of Objects
No
required_edd_docs
Array of String
N.A. Included in API response
screening_results
Object
N.A. Included in API response
social_docs
Array of Objects
No
Social documents linked to the base document. More details below.
title
String
Yes if individual base doc on business user
Title of the beneficial owner.
virtual_docs
Array of Objects
No
Virtual documents linked to the base document. More details below.
watchlists
String
N.A. Included in API response
Here is an example object for screening_results
object:
Here are all the possible values for individual screenings lists:
Value
Description
FAILED
Screenings have failed, we will auto-retry.
PENDING
Screenings have not been attempted yet. We will auto-run.
FALSE_POSITIVE
Base Document is a false positive on the screenings list.
MATCH
Key
Type
Required
Description
document_type
String
Yes
document_value
String
Yes
Value of the document.
id
String
Yes if you wish to PATCH
an existing virtual document
Primary key of the virtual document. This value is a local primary key, meaning, it's only unique within a base document. Different base documents can have same virtual document IDs.
last_updated
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the virtual document was last updated.
status
String
N.A. Included in API response
meta.country_code
String
Depends
meta.sub_type
String
Depends (Required with usage of BUS_REGISTRATION document type.)
Key
Type
Required
Description
document_type
String
Yes
document_value
String
Yes
Value of the document.
id
String
Yes if you wish to PATCH
an existing social document
Primary key of the social document. This value is a local primary key, meaning, it's only unique within a base document. Different base documents can have same social document IDs.
last_updated
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the social document was last updated.
status
String
N.A. Included in API response
info.address_city
String
N.A. Included in API response
Address city associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.address_country_code
String
N.A. Included in API response
ISO Alpha-2 formatted Address country code associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.address_postal_code
String
N.A. Included in API response
Address zip or postal code associated with the social document. Currently a response in MAILING_ADDRESS
social document.
into.address_street
String
N.A. Included in API response
Address street associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.address_subdivision
String
N.A. Included in API response
Address subdivision (state) associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.address_care_of
String
N.A. Included in API response
C/O name associated with the social document. Currently a response in MAILING_ADDRESS
social document.
info.invalid_reasons
Array of String
N.A. Included in API response
Currently a response in MAILING_ADDRESS
social document. Two reasons: invalid_address
and address_has_incorrect_unit
.
meta.state_code
String
Depends
meta.country_code
String
Depends
meta.address_street
String
Depends
Address street associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_city
String
Depends
Address city associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_subdivision
String
Depends
Address subdivision (state) associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_country_code
String
Depends
ISO Alpha-2 formatted Address country code associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_postal_code
Integer
Depends
Address zip or postal code associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
meta.address_care_of
String
No
C/O name associated with the social document. Currently a response in MAILING_ADDRESS
social document. This field will not be returned in any user responses.
Key
Type
Required
Description
document_type
String
Yes
document_value
String
Yes
In case of VIDEO_AUTHORIZATION
, please ensure that the user's face is clearly visible and the audio is clear and states the user saying "I authorize account opening at <name_of_platform>
."
Allowed file types for VIDEO_AUTHORIZATION
: ["mov","mp4","webm","avi","flv","mkv","ogg"]. Please limit video to 5-seconds.
id
String
Yes if you wish to PATCH
an existing virtual document
Primary key of the virtual document. This value is a local primary key, meaning, it's only unique within a base document. Different base documents can have same virtual document IDs.
last_updated
Number
N.A. Included in API response
Unix timestamp (in ms) value of when the virtual document was last updated.
status
String
N.A. Included in API response
invalid_reasons
Array of String
N.A. Included in API response
meta.state_code
String
Depends
meta.country_code
String
Depends
meta.id_number
String
Depends
Permission
Description
Next Steps
wrong_file_extension
Prompt the user to upload physical document with a valid file format.
image_not_found
No image found in provided file (e.g. file is empty).
Ensure that this is not a bug on your side and then request the user to re-upload document.
black_and_white_image
Image is black and white (e.g. a high-contrast photoscan of an ID rather than a color picture of an ID).
Prompt the user to upload the physical document in natural color.
palettised_image
The image only has a single color channel (i.e. is an indexed 256-color image) instead of having 3 (RGB) channels.
Prompt the user to upload the physical document in natural color.
poor_image_quality
The image does not contain a recognizable document, has abnormal colors, or is otherwise difficult to read.
Prompt the user to upload a higher resolution physical document in natural color.
name_mismatch
Name on physical document does not match name on Base Doc.
This can happen if the user did not submit their full legal name when submitting the base document. Prompt the user to update their name
on the base document and then resubmit the physical document.
dob_mismatch
DOB on physical document does not match DOB on Base Doc.
This can happen if the user did accidentally submitted the wrong date
, month
and year
on the base document. Prompt the user to update their dob on the base document and then resubmit the physical document.
face_undetected
No human face found in image, or unable to see eyes (e.g. due to glasses or flash).
Prompt the user to upload a higher resolution physical document in natural color.
mrz_undetected
[Applicable Only to Passports] Machine Readable Zone (MRZ) field not found.
Prompt the user to upload a passport photo with MRZ visible.
name_mismatch_mrz
[Applicable Only to Passports] Name extracted from Machine Readable Zone (MRZ) doesn’t match Base Doc.
This can happen if the user did not submit their full legal name when submitting the base document. Prompt the user to update their name
on the base document and then resubmit the physical document.
flagged_for_failing_security_feature
Flagged due to image missing missing corners, unable to read information due to glasses or flash, or ID has unusual patterns/formats (e.g. library card, non-DOD military ID card, suspected fake ID, etc.)
Prompt the user to upload a higher resolution physical document in natural color with all corners visible.
flagged_for_potential_fraud
Flagged due to information match with IDV internal blocked database.
company_name_mismatch
Name on physical document does not match name on Base Doc.
This can happen if the user did not submit their full legal name of the company when submitting the base document. Prompt the user to update their name
on the base document and then resubmit the physical document.
tax_id_mismatch
Tax ID number (TIN) on the physical document does not match the TIN
virtual document.
This can happen if the user did accidentally submitted the wrong TIN
as a virtual documents. Prompt the user to update their TIN
and then resubmit the physical document.
irs_logo_undetected
IRS logo not detected on an IRS issued document.
Prompt the user to upload a higher resolution physical document in natural color with all corners visible.
poor_video_quality
Unable to process video due to poor image quality.
Prompt the user to upload a higher resolution physical document in natural color.
poor_image_and_video_quality
Unable to process image and video files.
Prompt the user to upload a higher resolution physical document in natural color.
image_face_undetected
No human face found in image, or unable to see eyes (e.g. due to glasses or flash).
Prompt the user to upload a higher resolution physical document with face visible.
video_face_undetected
No human face found in video, or unable to see eyes (e.g. due to glasses or flash).
Prompt the user to upload a higher resolution physical document with face visible.
face_mismatch
Face from the video does not match face from previously submitted ID.
Prompt the user to upload a higher resolution physical document with face visible.
audio_comparision_failed
Audio does not match expected statement for comparison.
Prompt the user to upload a video with valid audio artifacts.
audio_undetected
No sound from the video detected.
Prompt the user to upload a video with valid audio artifacts.
image_too_large
File larger than allowed limit (4MB) for or image has higher than allowed pixel density.
Prompt the user to upload a lower resolution physical document in natural color with all corners visible.
address_mismatch
Address on physical document does not match Address on Base Doc.
This can happen if the user has submitted a different address on the base document. Prompt the user to update their address on the base document and then resubmit the physical document.
expired_document
Document is expired.
Prompt the user to upload a non-expired document.
expired_document_possible_misread_retry
Expiration field on physical document is not recognizable, or difficult to read.
Prompt the user to upload a higher resolution document in natural color.
date_not_detected
No date detected on the document.
Prompt the user to upload a non-expired document. In most cases this means that the user is submitting an incorrect type of document.
logo_not_detected
No logo detected on the document.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
unable_to_classify_as_bank_or_bill
Logo on document could not be classified as a known bank or utility provider.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
date_or_logo_failed
Date or logo missing in the document.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
atleast_one_text_field_failed
At least one text field (e.g. name, address, or date) was missing missing or couldn't be matched with Base Doc.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
hq_logo_hq_address_or_date
Logo detected with a high level of confidence, and either address or date detected with a high level of confidence.
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
hq_logo_mq_address_and_date
Logo detected with a high level of confidence, but date and address only detected with a medium level of confidence
Prompt the user to upload a valid document. In most cases this means that the user is submitting an incorrect type of document.
Status
Description
Next Steps
SUBMITTED|REVIEWING
Document is pending review.
SUBMITTED|VALID
Document is valid.
Document has been marked as valid.
SUBMITTED|INVALID
Document is invalid.
Prompt the user to upload a valid document.
SUBMITTED
Document has been submitted to us. This status means we currently lack the capability to verify this type of document automatically.
In most cases we recommend using a third-party provider to automatically verify the authenticity of the document before submitting. Once submitted to us, the user is free to be moved to the next onboarding step.
[1] In some instances, if we are unable to automatically verify a document. In those instances the document is queued to be reviewed manually by an agent on our side. This review is completed in 2 business days or less.
The following details will help assist on proper setup when submitting passports.
Passport Document Types
document_type = GOVT_ID,
used when submitting a passport issued by the United States of America.
document_type = PASSPORT_BIODATA
, used when submitting a passport issued by a country other then the United States of America.
When submitting a passport, the country code will be validated based on the value being US or not if you submit the incorrect document_type. document_types that will fail this check, including PASSPORT_BIODATA, are:
NATIONAL_ID
DRIVER_LICENSE
VOTER_REGISTRATION_CARD
PERMANENT_RESIDENT_CARD
PASSPORT_BIODATA
For users submitting passports issued in the United States of America, verification of a Social Security Number is also required. This is regardless of the user's country of residence.
Key
Type
Required
Description
client_id
String
N.A. Included in API response.
The Primary Key that denotes your client object in our system.
client_name
String
N.A. Included in API response.
Your common name in our system.
expires_at
Number
N.A. Included in API response.
Unix timestamp (in ms) value of when the OAuth object was created.
expires_in
Integer
N.A. Included in API response.
Countdown (in sec) of when the OAuth key will expire.
oauth_key
String
N.A. Included in API response.
OAuth key that you will be using to authenticate user level requests.
refresh_expires_in
Integer
N.A. Included in API response.
Number of times the same refresh token can be used to issue a new OAuth key.
refresh_token
String
Yes. But the response might have a new value if your supplied refresh token will expire after this request.
Token used to generate an OAuth Object.
scope
Array of String
user_id
String
N.A. Included in API response.
The Primary Key that denotes the user object in our system.
Scope
Description
USER|PATCH
PATCH
requests on /users/userid
can be sent. Eg. Updating KYC on user object.
USER|GET
GET
requests on /users/userid
can be sent. Eg. Viewing user KYC.
NODES|POST
POST
requests on /users/userid/nodes
can be sent. Eg. Creating a deposit account.
NODES|GET
GET
requests on /users/userid/nodes
can be sent. Eg. Viewing all payment accounts liked to the user.
NODE|PATCH
PATCH
requests on /users/userid/nodes/nodeid
can be sent. Eg. Verifying micro-deposits.
NODE|DELETE
DELETE
requests on /users/userid/nodes/nodeid
can be sent. Eg. Deleting a payment account from the user profile.
TRANS|POST
POST
requests on /users/userid/nodes/nodeid/trans
can be sent. Eg. Creating a new payment transaction.
TRANS|GET
GET
requests on /users/userid/nodes/nodeid/trans
can be sent. Eg. Viewing all payment transactions the user has made or received.
TRAN|GET
GET
requests on /users/userid/nodes/nodeid/trans/tranid
can be sent. Eg. Viewing a specific payment that was either sent or received by the user.
TRAN|PATCH
PATCH
requests on /users/userid/nodes/nodeid/trans/tranid
can be sent. Eg. Commenting on the transaction or approving a quote.
TRAN|DELETE
DELETE
requests on /users/userid/nodes/nodeid/trans/tranid
can be sent. Eg. Canceling a transaction.
SUBNETS|POST
POST
requests on /users/userid/nodes/nodeid/subnets
can be sent. Eg. Issuing a card.
SUBNETS|GET
GET
requests on /users/userid/nodes/nodeid/subnets
can be sent. Eg. View all cards issued to the user.
SUBNET|GET
GET requests on /users/userid/nodes/nodeid/subnets/subnetid
can be sent. Eg. View a card.
SUBNET|PATCH
PATCH
requests on /users/userid/nodes/nodeid/subnets/subnetid
can be sent. Eg. Activating a card.
STATEMENTS|GET
GET
requests on /users/userid/nodes/nodeid/statements can
be sent. Eg. Viewing all statements associated with a node.
STATEMENT|GET
GET requests on /users/userid/nodes/nodeid/statements/statementid
can be sent. Eg. Viewing a statement.
STATEMENTS|POST
POST requests on /users/userid/nodes/nodeid/statements
can be sent. Eg. Generating an AdHoc statement.
CONVERSATIONS|POST
Currently scope in internal testing. More to come later.
CONVERSATIONS|GET
Currently scope in internal testing. More to come later.
CONVERSATION|GET
Currently scope in internal testing. More to come later.
CONVERSATION|PATCH
Currently scope in internal testing. More to come later.
MESSAGES|POST
Currently scope in internal testing. More to come later.
MESSAGES|GET
Currently scope in internal testing. More to come later.
MESSAGE|GET
Currently scope in internal testing. More to come later.
MESSAGE|PATCH
Currently scope in internal testing. More to come later.
The users resource is used to create personal, joint or business user accounts. A user resource stores and managers user's KYC and authentication information. No bank account level details are stored on the object.
The user creation process allows you to create a user and add KYC ("Know Your Customer"). The required KYC is based on the requirements listed in your spec sheet. Please see below for details on the user creation process.
This call allows you create a user with the required KYC, as listed in your spec sheet. Please note that because KYC is processed asynchronously, we recommend that you submit all KYC in the same call as you create the user.
If you need to supply multiple base documents (as is the case for business or joint accounts), please supply a unique email/phone combination. This is because the base document ID is a hash of the email/phone, so duplicates will overwrite the existing base document.
If the user has SEND-AND-RECEIVE
permissions, all documents were processed successfully.
If the user does not have SEND-AND-RECEIVE
permissions, all documents may not have processed successfully or the user may be a potential match in a sanctions list.
For the latter, check the user's watchlists
flag to determine if the user was flagged as a possible match by Synapse's KYC verification system.
If the flag's value is SOFT_MATCH|PENDING_UPLOAD
, you will need to upload a government ID (GOVT_ID
) to allow either for our KYC verification system or for our compliance team to recheck the user.
If the flag's value is SOFT_MATCH
you will need to wait for the results of a compliance check.
We typically process and verify KYC within a couple of seconds. However, this can vary, depending on traffic, number and size of documents submitted. If all documentation was successfully processed we will give the user SEND-AND-RECEIVE
permissions (i.e. the ability to create nodes, and originate and receive transactions).
Please note that in instances where a Physical Document requires manual verification, the document will stay in SUBMITTED|REVIEWING
for up-to 2 full business day. These instances can be reduced if the image is clear, with all corners visible in case of a document with legible text. In case of videos, by ensuring that the video is clear with ample light and audio is clear and without distortion or disturbance.
Because we verify SSNs by making an immediate initial verification followed by a more in-depth verification with the IRS in up to 2 full business days. So there will be some instances where the SSN will return back as SUBMITTED|VALID
initially and later transition to SUBMITTED|INVALID
.
In instances where the SSN returns as SUBMITTED|INVALID
, the user will be able to either upload their valid SSN (upto two more times) or an SSN card for further review and approval.
Although we might not require government ID for a specific product we recommend to always build the user interface. As stated above, should a user be flagged on one of our sanction lists we will require the submission of a government ID.
Providing an accurate IP address of the user helps us and platforms combat fraud, and creating transactions from to/from/within sanctioned countries. Occasionally, certain platforms will submit their own IP on the API call header, we recommend not do so for the above described reasons.
To avoid race conditions for subsequent patch calls to users, nodes, and subnets, please consider doing one of the following:
adding a 4-5 second delay
waiting for a webhook response
adding all the document information into one patch or post call.
Base docs and virtual documents are validated through public and private databases and other APIs that we have integrated with. Meanwhile, physical documents, such as government IDs, are validated through our proprietary software, which includes:
Image rotation, cropping, and enhancement
Facial detection
OCR on certain text fields to be verified against base document values (such as name and DOB).
We validate addresses submitted both internally and externally through the use of external vendors to verify addresses. Addresses are a crucial part of our base documentation and fulfilling KYC/KYB requirements during onboarding. Furthermore, valid address inputs are important as they are used for things such as mailing account balances in case of account abandonment or termination.
Address Requirements:
Physical Addresses Only: We currently only accept current physical addresses. Examples of acceptable addresses include residential or business addresses. PO Box addresses are not accepted and will be automatically marked as invalid.
Address Validation Process:
Verification: Every submitted address undergoes a rigorous verification process for accuracy and completeness, using both internal checks and external verification through our vendor partners.
Invalid Address Handling: If a PO Box address is submitted, it will be flagged as invalid. The API response for such cases will include an error message in the id_score_meta
response field: invalid_physical_address -- Cannot use PO Box for physical address field. Please provide a valid physical address
. This message is found under the reason key. The same error message will appear under the address_input_error
key in the ADDRESS
meta object.
For international phone numbers to properly validate, the number must be of the form:
+[country code][national number]
The + sign is required.
Social Security Numbers (SSN) are initially verified with W-9 certification by the users and checked against additional databases to ensure they are not associated with a deceased individual. Furthermore, every 24 hours we will verify SSNs directly with the IRS. It is because of this lag that we might require further submission of a Social Security card up to 24 hours after initial KYC was submitted. For users submitting passports issued in the United States of America, verification of a Social Security Number is also required. This is regardless of the user's country of residence.
Employer Identification Numbers (EINs) and other tax IDs are validated against information provided to Synapse when available. We typically require an EIN letter issued by the IRS or similar document (e.g. 147c). The value on the physical EIN letter will be verified against the virtual tax ID value entered, and we will also perform checks to confirm the veracity of the document itself.
We will close duplicate user accounts within the platform’s environment, as this practice helps mitigate widespread fraud.
We perform basic duplicate user checks based on user data that generally should be able to uniquely identify users within the same CIP tag. These checks include:
Combination of Name + Date of Birth (DOB)
Combination of Name + Driver's License Number (DLN)
Combination of Name + Physical Address
Combination of Name + Email Address
Social Security Number (SSN)
The new simplified duplicate user account logic will prioritize the latest user account (i.e. keep that user open while closing others), determined by taking the most recent date among the following:
the most recent user account creation date (i.e. date user joined the Platform)
the most recent node creation date (please note that nodes older than 92 days will be ignored)
the most recent transaction date (please note that transactions older than 92 days will be ignored)
Synapse will run all users through our sanctions screening lists to comply with the requirements set forth in the Bank Secrecy Act, aimed to avoid facilitating transactions on behalf of sanctioned individuals, sanctioned entities, and/or wanted criminals. We will asynchronously run the KYC of each user through sanctions lists as well as additional screenings (e.g. FBI most wanted databases).
Our screenings lists are continuously updated to reflect changes in real-time.
The first step of the screening process is automated, based on controls in our KYC verification system that automatically flag potential matches. These soft matches (watchlists
: SOFT_MATCH
) are manually reviewed by members of Synapse's compliance team who will assess the validity of the alert. Please note that upload of a government ID (GOVT_ID
) may be required before a full compliance check can occur (watchlists
: SOFT_MATCH|PENDING_UPLOAD
). Our compliance team will then determine if the document that triggered a user's soft match is either a true sanctions list match (MATCH
) or a false positive (FALSE_POSITVE
). If the the compliance team determines that the flag was a false positive, the user will be given SEND-AND-RECEIVE
permissions and should be able to transact.
The collection of KYC documentation from end users is an important step in the on-boarding process. This not only helps facilitate compliance with the Bank Secrecy Act, but also helps prevent account takeovers and fraudulent user activity. The identifying documents collected for both platforms and individuals helps us understand who our customers are, the nature of their relationship with us, and their expected activity. Different products and limits will have different KYC requirements because the underlying risks can vary greatly. We encourage platforms to collect more KYC than our minimum requirements.
This page (and its related sub-pages) are not intended to outline a Customer Identification Program (CIP), or set forth minimal KYC requirements (which will be detailed in your spec sheet), but rather to explain what we do with the information we collect.
Please note, although we continually strive to prevent fraud at any level, we do not and cannot guarantee a fraud-free product. We actively encourage our platforms to take the necessary steps to mitigate fraud, as the platforms will still be liable for user fraud and negative balances incurred as a result of fraudulent activity.
While Synapse does monitor for unusual activity to assist our partner banks in their compliance with the Bank Secrecy Act reporting requirements, Synapse does not file SARs directly with FinCEN. Any platforms registered as MSBs, or otherwise required to file SARs (registered broker dealers) should remain vigilant in their reporting obligations. We do, however, encourage our platforms to report instances of fraud and or suspicious activity to Synapse for further review; our compliance team is equipped to perform further investigation.
We have the capability to on-board foreign users, if certain conditions are met. In these cases we will work with the platform to define KYC requirements that take into account the documentation those users have available but that also fulfill the security needs of KYC collection.
We block sanctioned countries automatically on our end both at the transaction level and the user address level. We continuously update this list. We recommend platforms also perform their own monitoring.
Please do not submit real KYC in sandbox. You cannot verify real identities and document information in sandbox.
With the exception of addresses test base document requirements are non-rigorous. Any value following the appropriate format for the specific document (Ex. name@email.com, phone: 000.000.0000) will be accepted.
It is mandatory to have an up-to-date physical address for all users, as PO BOXES are not accepted for the ADDRESS document type. A valid USPS mailable address is required for all transactions and communications. This ensures compliance with our KYC/KYB requirements and facilitates direct and secure communication.
Value
Result
123 Fail Address, Fail City, FS 00000
Supplied address is invalid / Unable to verify address
1 Market Street Suite 1000, San Francisco, CA 94105
Validation is successful
325 S Santa Claus Ln North Pole, AK 99705
Validation successful.
Will trigger an AVS exception when attempting to create an INTERCHANGE-US
node (i.e. when attempting to link an external card in Sandbox).
Value
Result
2222
Validation Successful
Any other value
Validation Fails
Value
Result
data:image/invalid;base64,SUQs==
Validation Fails
Any other value
Validation Successful
Type
Value
Result
EMAIL_2FA
123456
Validation Succesful
PHONE_NUMBER_2FA
123456
Validation Succesful
EMAIL
invalid@gmail.com
Validation Fails
IP
255.255.255.0
Validation Fails
FACEBOOK
https://www.facebook.com/invalid
Validation Fails
LINKEDIN
https://www.linkedin.com/invalid
Validation Fails
TWITTER
https://twitter.com/invalid
Validation Fails
PHONE_NUMBER
541-754-3010
Validation Fails
Fingerprint
Validation PIN
static_pin
123456
ID Score
Trust Score
Email containing @testlowidscore.com
0.2
Does not support
Email containing @lowtrustlevel.com
0.2
low
Email containing@medtrustlevel.com
0.6
med
Any other Email
0.9
high
Value
Failure Reason
9000
invalid_tin|not_issued
2225
invalid_tin|name_mismatch
0010
invalid_tin|duplicate_request
6666
invalid_tin|dmf
2220
invalid_tin|info_mismatch
2800
invalid_tin|reason_unknown
0005
invalid_tin|missing_info
OAuth Details
refresh_token
String
Required during POST
Token used to generate an OAuth Object.
scope
Array of Strings
Required during POST
As fingerprints are required for OAuth key generation calls, there are options to consider related to the users fingerprint.
is_active
Boolean
Optional
Will execute the MFA flow, to allow changing of is_protected fingerprint value.
is_protected
Boolean
Optional (Requires is_active:true)
POST
https://api.synapsefi.com/v3.1/oauth/:user_id
This endpoint allows you to generate an OAuth token for a specific user so that you can perform necessary actions on behalf of the user.
user_id
string
ID of the user you wish to generate an OAuth token for.
X-SP-USER
string
OAuth key and device fingerprint of the user separated by a pipe. In this API call, only the device fingerprint is required.
X-SP-USER-IP
string
IP Address of the user device.
X-SP-GATEWAY
string
Your Client ID and Secret separated by a pipe.
validation_pin
string
In case of MFA verification, the code delivered to the phone_number.
phone_number
string
Phone number where the MFA code will be sent in an instance of a new fingerprint registration.
scope
array
Array of Scopes the OAuth key will allow. Go to Possible Scopes to learn more.
refresh_token
string
Refresh token associated with the user.
Please note that both POST
and PATCH
calls on the user document perform various asynchronous operations. So it's not recommended to make subsequent POST
and then PATCH
requests on the same user document as that can lead to various race conditions. We recommend submitting all documents at once vs performing subsequent operations on the same document.
PATCH
https://api.synapsefi.com/v3.1/users/:user_id
This endpoint allows you to create a user document.
X-SP-USER
string
OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Needed for Business Users Only.
UBO or Ultimate Beneficial Owner documents is used to declare who is the ultimate beneficial owner of a business or major shareholder.
Please note that both POST
and PATCH
calls on the user document perform various asynchronous operations. So it's not recommended to make subsequent POST
and then PATCH
requests on the same user document as that can lead to various race conditions. We recommend submitting all documents at once vs performing subsequent operations on the same document.
PATCH
https://api.synapsefi.com/v3.1/users/:user_id/ubo
This endpoint allows you to create a user document.
X-SP-USER
string
OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Key
Type
Required
Description
entity_info
Object
Yes
signer.document_id
String
Yes
signer.relationship_to_entity
String
Yes
Relationship of the signer with the entity. Eg. CEO
, CRO
, etc.
compliance_contact.document_id
String
Yes
compliance_contact.relationship_to_entity
String
Yes
Relationship of the compliance contact with the entity. Eg. CEO
, CCO
, etc.
primary_controlling_contact.document_id
String
Yes
primary_controlling_contact.relationship_to_entity
String
Yes
Relationship of the primary controlling contact with the entity. Eg. CEO
, CCO
, etc.
owners.document_id
String
Yes
owners.title
String
Yes
Relationship of the owner with the entity. Eg. CEO
, CCO
, etc.
owners.ownership
Number
Yes
Percentage ownership of the owner.
attested*
boolean
Yes
Certification and Agreement to Notify See below
*attested signifies the following statement is true: I certify that the following information was submitted to Platform for all beneficial owners (holding 25% or more ownership) and controlling persons & executives:
US Person(s): SSN + US Government Issued Photo ID
Foreign Person(s): Tax Identification Number (if available) + Passport Number & Country of Issuance. In lieu of passport number, foreign persons may also provide an alien identification card number, or number and country of issuance of any other government issued photo ID evidencing nationality or residence.
Key
Type
Required
Description
document_id
String
Yes
cryptocurrency
Boolean
Yes
Set as false
if business is not involved with cryptocurrency.
msb.federal
Boolean
Yes
Set as false
if business does not have Money Transmission Licenses (MTL) in any states.
msb.states
List of String
Yes
List of states that business has Money Transmission Licenses (MTL) in.
public_company
Boolean
Yes
Set as false
if business is not a public company.
majority_owned_by_listed
String
Yes
Set as false
if business is not majority owned (50% or more) by a public company.
registered_SEC
String
Yes
Set as false
if business is not registered with U.S. Securities and Exchange Commission (SEC).
regulated_financial
String
Yes
Set as false
if business is not a regulated financial company.
gambling
String
Yes
Set as false
if business is not involved with the internet gambling business.
Please note that both POST
and PATCH
calls on the user document perform various asynchronous operations. So it's not recommended to make subsequent POST
and then PATCH
requests on the same user document as that can lead to various race conditions. We recommend submitting all documents at once vs performing subsequent operations on the same document.
POST
https://api.synapsefi.com/v3.1/users
This endpoint allows you to create a user document.
X-SP-USER
string
OAuth key and device fingerprint, separated by a pipe. For this request OAuth can be left blank since X-SP-GATEWAY
will be used for authentication. But device fingerprint is still required.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
POST
https://api.synapsefi.com/v3.1/oauth/:user_id/login
This endpoint allows you to generate a refresh token for the user linked to your client credentials.
user_id
string
ID of the user you wish to generate an OAuth token for.
X-SP-USER
string
OAuth key and device fingerprint of the user separated by a pipe. In this API call, only the device fingerprint is required.
X-SP-USER-IP
string
IP Address of the user device.
X-SP-GATEWAY
string
Your Client ID and Secret separated by a pipe.
string
Email associated with the user login object.
password
string
Password associated with the same user login object.
PATCH
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id
This endpoint allows you to create a node.
Following are a few Credit specific update node examples:
Please send the user their termination letter when terminating the loan. This can be found in the agreements
value of the response.
Following are a few ACH specific update node examples:
Micro-deposits are automatically initiated when a bank account is linked with Account/Routing, assuming the user's KYC is complete Within 1-2 business days, the user will see two small transactions (less than $1 each) on their bank account statement. The user must return to your application and submit the two micro-deposit amounts in any order. If the amounts are correct, the node will receive CREDIT-AND-DEBIT
permissions.
Please note that we set a limit of 3 micro-deposit attempts per ACH node. Any attempts past this limit will return a max_microdeposits_sent
error.
Since ACH accounts can be linked two ways: either by supplying the account and routing number, or by supplying the bank login credentials, here are the best scenarios for both:
When adding a new node, append any of these values to the end of the password. When doing a force_refresh
on the node, it will trigger the corresponding error.
Appending “_needs_relink
” to the password (e.g. test1234_savings_needs_relink
) will link a node that will return the 401/110
error message when you try doing a force_refresh
. It falls in line with our current sandbox test values so you can add _needs_relink
to the end of any of the passwords above.
If a bank account is added with AC/RT numbers, we automatically send micro-deposits to the user's external bank account for verification. Here are the micro-deposit values for sandbox:
Any valid address will work for testing CHECK-US
.
POST
https://api.synapsefi.com/v3.1/users/:user_id/nodes
This endpoint allows you to create a node.
We require that you first generate a preview of the node agreement, display it to the user to get their consent and then create the account. To generate a preview, add "preview_only":true
to the payload.
We require that you first generate a preview of the node agreement, display it to the user to get their consent and then create the account. To generate a preview, add "preview_only":true
to the payload.
There are four types of credit accounts -- Repay, One-Time, Open and Revolving. Following are examples of opening all four:
We require that you first generate a preview of the node agreement, display it to the user to get their consent and then create the account. To generate a preview, add "preview_only":true
to the payload.
We require that you first generate a preview of the node agreement, display it to the user to get their consent and then create the account. To generate a preview, add "preview_only":true
to the payload.
We require that you first generate a preview of the node agreement, display it to the user to get their consent and then create the account. To generate a preview, add "preview_only":true
to the payload.
We require that you first generate a preview of the node agreement, display it to the user to get their consent and then create the account. To generate a preview, add "preview_only":true
to the payload.
There are two ways to link an ACH account with us:
Method #2: Link via Account Aggregation (with a 3rd Party Vendor)
To link an ACH account using a 3rd party vendor, supply data from the 3rd party vendor in the following format. Please note that you will require 3 months minimum of the user's transaction data in order to skip micro-deposits. Please designate negative values with "debit" : true/false
(boolean).
To enable additional address validation, please make a request via support or your growth manager, for an update to your platform configuration. AVS is configured per CIP tag. To fully utilize this service, you will need to provide:
The results of AVS validation include:
Unix timestamp (in ms) value of when the account will auto close. Only utilized in instances of a flagged account that needs to be closed. Go to to learn more.
CIP Tag associated with the user object. Go to to learn more.
The reason for user flag. Go to to learn more.
The current permission of the user object. Go to to learn more.
The reason for user flag. Go to to learn more.
Refresh token you will be using to the user.
Represents if the user is on a meaningful screenings list. Go to to learn more.
Ensure all KYC has been supplied and is marked as valid by us. Go to to learn more.
If this is an acceptable final permission, no additional steps needed. If you also wish to originate or authorize payments on behalf of the user, ensure all KYC has been supplied and is marked as valid by us. Go to to learn more.
User KYC review finished. User is allowed to operate the account as allowed by the spec sheet. Go to to learn more.
Unless your program is configured differently, all values except NO_MATCH
and FALSE_POSITIVE
will impact user permissions and will keep the as UNVERIFIED
until further review.
We will automatically run sanctions screenings, you can poll GET
user or use to be able to notified of the update.
Traverse through documents
to see which base document is watchlists:SOFT_MATCH|PENDING_UPLOAD
. If it's a business base doc, please upload a valid EIN_DOC
. If individual base doc, please upload a valid GOVT_ID or DRIVER_LICENSE
. Go to to learn more.
Lock user account for an appropriate . In this case that would beUNUSUAL_ACTIVITY|LEGAL_REQUEST
.
Address city of the business location or individual's residence. If the user wishes to receive mail elsewhere, you can add that as a MAILING_ADDRESS
social document. Go to to learn more. We recommend to prevent failure.
Desired scope for base document. Go to to learn more.
The key of the document you intend to submit. Go to to learn more.
The key of the document option you intend to submit. Go to to learn more.
The title of the document option you intend to submit. Go to to learn more.
Included for business user's business base document. Possible values: VALID
, INVALID
, REVIEWING
. Go to to learn more.
Industry or profession of business or individual. Go to response section to see all the possible values.
Type of business or gender of the individual. Go to response section to see all the possible values.
Included for an individual's base document (either for business, joint or individual accounts). Value ranges from 0-1. Go to to learn more.
Included for an individual's base document (either for business, joint or individual accounts). Value can be low
, med
or high
. Go to to learn more.
Permission scope of the base document. Go to to learn more.
Physical documents linked to the base document. Go to to learn more.
Documents required to decision a flagged user. Go to to learn more.
This object contains all the sanctions screenings lists the user has been run against. This object is just a detailed response that decides the value of watchlists
. Our recommendation is not to pay attention to this field but just the watchlists
key instead. Go to to learn more.
Represents if the document is on a meaningful screenings list. Go to to learn more.
Please note that not all sanctions lists will be appropriate for your use-case. Your spec sheet dictates which sanctions lists affect the . Go to to learn more.
Base Document is a soft or actual match on the screenings list. Final determination will happen at the level.
Type of virtual document being submitted. Go to response section to see all the possible values.
Status of the virtual document. Go to to learn more.
ISO Alpha-2 formatted Address country code of the issuing country of the virtual document. Go to response section to see which virtual documents require this field. This field will not be returned in any user responses.
Native government issued name or common name of the document type of issuing country of virtual document. eg for Brazil sole proprietors they may have a “CNPJ” number. This would be the meta.sub_type of BUS_REGISTRATION. Go to response section to see which virtual documents require this field. This field will not be returned in any user responses.
Type of social document being submitted. Go to response section to see all the possible values.
Status of the social document. Go to to learn more.
ISO Alpha-2 formatted Address country code of the issuing state of the virtual document. Go to response section to see which social documents require this field. This field will not be returned in any user responses.
ISO Alpha-2 formatted Address country code of the issuing country of the virtual document. Go to response section to see which social documents require this field. This field will not be returned in any user responses.
Type of physical document being submitted. Go to response section to see all the possible values. For additional details on passports click .
Value of the document. Physical documents must be encoded before being uploaded to our system. Please ensure that the image is clear, with all corners visible in case of a document with legible text. In case of videos, please ensure that the video is clear with ample light and audio is clear and without distortion or disturbance.
Status of the virtual document. Go to to learn more.
If the document status is SUBMITTED|INVALID
, invalid_reasons
describes the reasons for why the document was marked as invalid. Go to to learn more.
ISO Alpha-2 formatted state code of the issuing state of the physical document. Go to response section to see which physical documents require this field. This field will not be returned in any user responses.
ISO Alpha-2 formatted country code of the issuing country of the physical document. Go to response section to see which physical documents require this field. This field will not be returned in any user responses.
ID number associated with the physical document. Go to response section to see which physical documents require this field. This field will not be returned in any user responses.
Incorrect file type (e.g. not png, jpeg, jpg). Go to response section to see which file extensions are allowed per physical document.
Lock user account for an appropriate . In this case that would be KYC_FRAUD|FRAUDULENT_DOCS
.
We will automatically or in rare instances, manually review [1] the document. You can poll GET
user or use to get notified when the document is reviewed.
No. Default are all .
Scopes denote which API calls and actions the OAuth key is allowed to do. This field is worth customizing if you will be sending the OAuth key to the client device for certain actions reducing the damage a attack can do.
If you haven't done so already, to inform you when a user has been created, or permissions/statuses have changed.
Upon submitting KYC, the user's and statuses will change as documents get validated asynchronously.
To check for the former, look at the status
of each submitted document and .
For more details about this process, please refer to .
After creating a user successfully, to perform actions for that user.
Please refer to the page for more details.
Physical documents are verified by our computer vision modules and are also periodically reviewed by the Synapse compliance and/or audit team. The manual audit may result from unusual or unexpected activity, or may be part of a regular sample audit to ensure that the documents provided to us fulfill the items listed in each platform’s spec sheet. The Synapse team may mark items “invalid” as appropriate should the document be determined to be insufficient. Please note that this may result in the user becoming unverified, it is important to ensure proper documents are provided to Synapse. Any document that does not have automated verification built will be marked as SUBMITTED
on our system instead of SUBMITTED|VALID
or SUBMITTED|INVALID
. Go to to learn more.
Learn more about how to .
We return a weighted numerical score indicating our relative confidence in the captured KYC. For more information please refer to the .
We strive to always improve the quality of all our services. We are continuously launching enhancements for our KYC validation service and to our related micro-services. To keep track of these changes, then please look at .
For more details please go to .
In addition to automated processes for closing accounts due to and , we also have an enhanced due diligence (EDD) processes for flagging high-risk users for analysis, review, and closure.
A user subject to EDD review will be flagged (flag:FLAGGED
) with a user flag code (flag_code
) to indicate the reason the user was flagged (see to learn more). Along with this, if any additional documents are needed, you will see those show up under documents.required_edd_docs
. The user will be expected to upload these documents to be able to unflag their account.
Please note, when a user is flagged for EDD, an account_closure_date
is set as well. If an end-user fails to provide adequate documentation by that date, the account will be closed automatically. More details are provided under .
What KYC is required depends on which account types are being opened for your customers. We strive to keep the KYC burden as low as possible. Your KYC program is customized during the implementation process. If you are already a customer who wishes to further reduce the KYC requirements, please .
All users must accept Synapse's Privacy Policy which explains the data we collect and how we use such data. Synapse keeps aggregated and anonymized data for internal research and development, risk mitigation and machine learning purposes. Further information about how Synapse uses and stores its users’ data is available in .
To be able to generate a sample base64
string, you can go to . They make it very easy to generate a padded base64
string for any image. You can then use that base64 string to test with our APIs.
If you wish to automate testing , use the following values when creating a user to automate 2FA testing.
The following values can be used to trigger both EDD and Non-EDD flows for ID Score (See: ) on sandbox:
Please note the failure reasons and status codes below are only available on a and when Realtime SSN is included in your spec sheet.
Scopes denote which API calls and actions the OAuth key is allowed to do. This field is worth customizing if you will be sending the OAuth key to the client device for certain actions reducing the damage a attack can do.
Setting to true prevents a fingerprint from being removed once the is reached.
Go to to see all the required and optional body parameters allowed during user creation. Following are example requests:
Information about the business. Go to to learn more.
Document ID of the of the signer.
Document ID of the of the compliance contact.
Document ID of the of the primary controlling contact.
Document ID of the of the owner.
Document ID of the of the entity.
Go to to see all the required and optional body parameters allowed during user creation.
Verifying Addresses We validate addresses to ensure an address is mailable. Prior to submitting an address, we encourage you to . We also recommend that you use , the or similar tools to autocomplete addresses prior to verifying. This should reduce the risk of submitting improperly formatted addresses.
In most cases a refresh token is already present when you . In instances where a refresh token is not avaliable, it can be generated by using a Basic Auth by supplying the user's username and password. These combinations exist in the logins
object of the user. Go to to learn more.
The node resource is used to create or link various types of liquidity accounts to the user. The purpose of this is to allow you to easily interface and build with , , asset or various .
The different accounts we offer have different characteristics, KYC requirements, regulatory restrictions, among other distinctions). This variety allows us to offer the best solution for each use case. To learn more, please go to product guide.
The different accounts we offer have different characteristics, KYC requirements, regulatory restrictions, among other distinctions). This variety allows us to offer the best solution for each use case. To learn more, please go to product guide.
We offer a variety of payment accounts, this allows us to provide you with the proper array of solutions unique to their respective use cases. Please refer to the pages of this section for more information on the general characteristics of our payment solutions and the specifics for each payment type. To learn more, please go to product guide.
Go to to see all the required and optional body parameters allowed during node updates. Following are some examples of most common update calls:
Go to and to learn more.
After Reauthorizing the ACH-US
transaction node's status to CREDIT
and micro-deposits will be sent automatically. You will then need to change the node's status to CREDIT-AND-DEBIT
.
Please note that this is a subset of the cards provided by Apple (under "Test Cards for Apps and the Web" ).
Go to to see all the required and optional body parameters allowed during node creation. Following are a few examples of various nodes and how to create them:
In some instances, you will need to book in our system. Here is an example of how to do that:
Method #1: Link via Account/Routing Number May require if indicated in your spec sheet.
In the following example the card number and expiration date are encrypted. Go to to learn more.
Below is the minimum request body to create a WIRE-INT node, some countries will require additional information. Please refer to for other country specific required attributes.
In the following example the account number is encrypted. Go to to learn more.
Also go to to learn how to get biller_id
.
type
string
Type of node you wish to query.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20
.
page
integer
Page number of the paginated request. Default is 1
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
node_id
string
ID of the node.
user_id
string
ID of the user.
reauth
string
Set to YES if you wish to reauth a locked node. Currently only avaliable for ACH-US.
resend_micro
string
Set to YES if you wish to resend micro deposits.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
node_id
string
ID of the node.
user_id
string
ID of the user.
tx_date_end
string
If performing force refresh this param can be used to specify the date range of transactions that should be pulled. Format: %Y-%m-%d
.
tx_date_start
string
If performing force refresh this param can be used to specify the date range of transactions that should be pulled. Format: %Y-%m-%d
.
force_refresh
string
Set to YES
if you wish to refresh the ACH-US bank data. Only works for ACH accounts linked using Account Aggregation. Default is NO
.
full_dehydrate
string
Set to YES
if you wish to receive all node PII in the response. Default is NO
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Username
Password
MFA
Bank Name
test_good
test1234
again
For multiple MFAs.
test_answer
For single MFA.
fake
synapse_good
test1234
again
For multiple MFAs.
test_answer
For single MFA.
fake
synapse_good
test1234_one
again
For multiple MFAs.
test_answer
For single MFA.
fake
synapse_good
test1234_checking
again
For multiple MFAs.
test_answer
For single MFA.
fake
synapse_good
test1234_savings
again
For multiple MFAs.
test_answer
For single MFA.
fake
synapse_good
test1234_random
again
For multiple MFAs.
test_answer
For single MFA.
fake
synapse_nomfa
test1234
No MFA necessary
fake
synapse_code_mfa
test1234
123456
fake
HTTP_CODE
ERROR_CODE
Append to Password
Description
503
503
_sync_unavailable
Refresh unavailable
400
410
_sync_not_allowed
Refresh not allowed
401
110
_needs_relink
Bad credentials
500
500
_sync_unknown_error
Unknown refresh error
Account Number
Routing Number
Any Number between 5-25 digits
Any Valid Routing Number
Micro-Deposit Amount 1 (in cents)
Micro-Deposit Amount 2 (in cents)
10
10
Number
Network
Card Type
Permission
9999999999999999
Exp: 202412
VISA
DEBIT
For testing duplicate card check functionality ONLY.
9401100999999992
VISA
DEBIT
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
9401101999999990
VISA
DEBIT
CREDIT
9401110999999991
VISA
DEBIT
DEBIT
9401113999999995
VISA
DEBIT
CREDIT-AND-DEBIT
9401200999999990
VISA
CREDIT
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
9401201999999998
VISA
CREDIT
CREDIT
9401210999999999
VISA
CREDIT
DEBIT
9401211999999997
VISA
CREDIT
CREDIT-AND-DEBIT
9401300999999998
VISA
PREPAID
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
9401301999999996
VISA
PREPAID
CREDIT
9401310999999997
VISA
PREPAID
DEBIT
9401311999999995
VISA
PREPAID
CREDIT-AND-DEBIT
9501100999999991
MASTERCARD
DEBIT
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
9951101999999994
MONEYSEND
DEBIT
CREDIT
9501110999999990
MASTERCARD
DEBIT
DEBIT
9501200999999999
MASTERCARD
CREDIT
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
9951201999999992
MONEYSEND
CREDIT
CREDIT
9501210999999998
MASTERCARD
CREDIT
DEBIT
9501300999999997
MASTERCARD
PREPAID
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
9951301999999990
MONEYSEND
PREPAID
CREDIT
9501310999999996
MASTERCARD
PREPAID
DEBIT
9601210999999997
DISCOVER
CREDIT
DEBIT
9601200999999998
DISCOVER
CREDIT
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
9810203999999999
DISCOVER
CREDIT
CREDIT
Card Number
Processor
Type
Permission
5204247750001471
Mastercard
Debit
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
5204247750001505
Mastercard
Debit
CREDIT
5204247750001497
Mastercard
Debit
DEBIT
5204247750001489
Mastercard
Debit
CREDIT-AND-DEBIT
5204247750001463
Mastercard
Credit
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
5204245250001496
Mastercard
Credit
CREDIT
5204245250001512
Mastercard
Credit
DEBIT
5204245250001504
Mastercard
Credit
CREDIT-AND-DEBIT
5204245250001488
Mastercard
Prepaid
CREDIT-AND-DEBIT
5204245250001470
Mastercard
Prepaid
DEBIT
4761120010000492
Visa
Debit
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
4761349750010326
Visa
Debit
CREDIT
4761209980011439
Visa
Debit
DEBIT
4761262260004228
Visa
Debit
CREDIT-AND-DEBIT
4051069302200121
Visa
Credit
NONE (which means both credits and debits have been disabled by cardholder. So adding this card would fail.)
4761369980320253
Visa
Credit
CREDIT
4622943120054839
Visa
Credit
DEBIT
4761229700150465
Visa
Credit
CREDIT-AND-DEBIT
4180620070230189
Visa
Prepaid
CREDIT-AND-DEBIT
4123400073320224
Visa
Prepaid
DEBIT
Account Number
Routing Number
Any Number between 5-25 digits
Any Valid Routing Number
Account Number
SWIFT Code
Any Number between 5-25 digits
Any Valid SWIFT Code
Account Number
Biller ID
Any Number between 5-25 digits
Any Valid Biller ID
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
info.security_code
String
Yes
Used to complete AVS validation. This is the card CVV. NOTE: Use same encoding method as with card number and expiration date.
info.strict_avs_validation
Boolean
No
If AVS check fails, with this set to True, the node will not be created.
extra.other.avs.avs_match
Boolean
No
Address validated, or not.
extra.other.avs.result
String
No
When present, results will be DECLINED or NOT_DECLINED. NOTE: Results are filtered to avoid fraud. Reach out to support if additional detail is needed.
X-SP-USER
string
Your OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/nodes/types
This endpoint allows you to get and view all the avaliable node types.
X-SP-USER
string
Your OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/nodes/atms
This endpoint allows you to get and view all the available ATMs around a location.
lat
number
Latitude of the location
lon
number
Longitude of the location
radius
integer
Radius of the geofence (miles)
NOTE: green_dot
does not support the use of radius
as a parameter
page
integer
Page number of the paginated request. Default is 1.
per_page
number
Number of objects to return per page. Default is 20.
atm_network_type
string
Type of atm network. Options: all_point
, money_pass
or green_dot
.
X-SP-USER
string
Your OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets
This endpoint allows you to get all subnets linked to a node.
user_id
string
ID of the user.
string
ID of the node.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20
.
page
integer
Page number of the paginated request. Default is 1
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Key
Type
Required
Description
_id
String
N.A. Included in API response.
Primary Key of the node object.
allowed
String
Depends. Only required if you are trying to verify micro-deposit or close a node.
allowed_status_code
String
Depends. Only required if you are trying to close a node.
is_active
Boolean
Only required when trying to unindex a node.
client.id
String
N.A. Included in API response.
The Primary Key that denotes your client object in our system.
client.name
String
N.A. Included in API response.
Your common name in our system.
extra.note
String
Only required when you are trying to register a loan rejection in our system.
extra.supp_id
String
No
You can use this field to store the Primary Key of this object in your system.
timeline.date
Number
N.A. Included in API response.
Unix timestamp (in ms) value of when the timeline object was created.
timeline.note
String
N.A. Included in API response.
Human readable notes associated with the timeline object.
info
Object
Some values Yes.
interest.fee
Number
No
Charges the user a loan origination fee. Is added as part of the APR and requires a payment_node_id
.
Reason
Description
Set By
INCOME|INSUFFICIENT
Income insufficient for amount of credit requested.
You
INCOME|NOINFO
Cash flow information is insufficient.
You
INCOME|UNVERIFIABLE
Unable to verify income.
You
ACCOUNT|TOOSHORT
Length of account is too short with you.
You
ASSETS|INSUFFICIENT
Loan rejected because the amount in their checking account is lower than the amount of their first installment.
You
ACCOUNT|OVERMAXLOANS
Us
ACCOUNT|OVERMAXAMOUNT
Us
ACCOUNT|WRONGTYPE
Us
USER|NOKYC
KYC is not finished on the user. Please finish KYC and try again.
Us
ASSETS|INSUFFICIENT
Loan rejected because the amount in your checkings account is lower than the amount of your first installment.
You
LOAN|INSUFFICIENT
This loan is intended to help you pay down your debt, and we have determined your approved loan amount is insufficient to cover your debts at this point in time.
You
USER|UNVERIFIABLE
Your request for a loan was not able to be processed because we were unable to validate your identity with the details and credentials provided.
You
Allowed
Description
Next Steps
CREDIT-AND-DEBIT
Funds can be debited or credited from this node.
No action required.
CREDIT
Funds can only be sent to this node. No Debits allowed.
If this node is ACH-US, next step could be micro-deposit verification. If not, no action required. This is the final allowed permission. For example, in instances of a check, you can only send money to it, cannot debit from a check node.
DEBIT
Funds can only be debited from this node. No Credits allowed.
This is a common allowed value for Interchange nodes in instances where push to card has not been enabled my the issuer of the card. If the user wishes to push to card, ask the user to link another card.
INACTIVE
Currently the node is not active and is unable to transact.
Currently only used for One-time Credit Accounts. These nodes are set to INACTIVE
after 60 days of inactivity. You can also use this status to suspend a loan with a PATCH
API call. If you have set allowed to INACTIVE
, please ensure that the end user has been notified of this change.
NOTE: Unable to set LOAN-US node of REVOLVING or OPEN types to INACTIVE if node age is under one month or any non-cancelled or returned transaction created during past month exists.
LOCKED
The node has been locked.
REJECTED
Loan request was rejected.
Allowed Status Code
Description
Next Steps
USER_REQUESTED
User requested the allowed status change.
No action required.
ISSUER_DIRECTED
Issuer of the node requested status change. Mostly used when an ACH or Interchange account needs to be locked for suspicious activity or invalid details.
Please ensure that the end user has been notified of this outcome.
ACCOUNT_CLOSED
Since the user account was being closed, the node was closed as well.
Please ensure that the end user has been notified of this outcome.
ACCOUNT_LOCKED
Since the user account was bing locked, the node was locked as well.
Please ensure that the end user has been notified of this outcome.
NOT_KNOWN
Allowed status change reason unknown.
No next steps recommend here since legacy tag.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "Default Checking Account".
balance.amount
Number
N.A. Included in API response
Balance held in the deposit node.
balance.currency
String
N.A. Included in API response
Currency of the deposit node.
monthly_withdrawals_remaining
Integer
N.A. Included in API response
If the deposit node has withdrawal restrictions, this value will denote how many more withdrawals are allowed. This value resets every month.
document_id
String
Yes
bank_code
String
N.A. Included in API response
Code of the bank where this account resides. Since we have multiple partner banks, this code can vary based on the bank partner where this account was opened.
agreements.type
String
N.A. Included in API response
agreements.url
String
N.A. Included in API response
The PDF URL of the appropriate agreement. Each agreement contains the IP, Timestamp and Device Fingerprint of the user at the time of node creation.
info.balance.interest
Number
N.A. Included in API response
Daily interest accrual of interest (accumulator). Will zero out on the following month after interest rate payout to the user.
Key
Type
Required
agreements.type
String
N.A. Included in API response
agreements.url
String
N.A. Included in API response
The PDF URL of the appropriate agreement. Each agreement contains the IP, Timestamp and Device Fingerprint of the user at the time of node creation.
bank_code
String
N.A. Included in API response
Code of the bank where all the processing for this account will happen. Since we have multiple partner banks, this code can vary.
document_id
String
N.A. Included in API response
bank_code
String
N.A. Included in API response
Code of the bank where this account resides. Since we have multiple partner banks, this code can vary based on the bank partner where this account was opened.
custody
String
Yes
Custody values include: FDIC
or MMF.
risk
String
Yes
Risk values include: CONSERVATIVE
, MODERATE
or AGGRESSIVE
. Please note, in case of FDIC custody, risk values currently do not change impact on which banks funds are swept to.
balances
Object
N.A. Included in API response
Object containing the balances in the CMA account. The key is the accounts currency and the value is the amount of funds per currency. Eg. for USD, the key-value pair would be USD:100.00
.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "Default Credit Account".
balance.amount
Number
N.A. Included in API response
Current Balance owed by the user on this credit node.
balance.currency
String
N.A. Included in API response
Currency of the credit node.
credit_limit.amount
Number
Yes
Max credit extended to the user.
credit_limit.currency
String
Yes
Currency of the credit node.
interest.apr
Number
Yes
Current APR rate in %.
interest.cap
Number
Yes
Max interest owed by the user in appropriate currency.
interest.accrued
Number
N.A. Included in API response
Interest accrued so far.
interest.fee
Number
No
Charges the user a loan origination fee. Is added as part of the APR and requires a payment_node_id
.
agreements.type
String
N.A. Included in API response
agreements.url
String
N.A. Included in API response
The PDF URL of the appropriate agreement. Each agreement contains the IP, Timestamp and Device Fingerprint of the user at the time of node creation.
document_id
String
Yes
schedule
String
Yes.
Payment schedule associated with the credit node. Currently only MONTHLY
allowed.
bank_code
String
N.A. Included in API response
Code of the bank where all the processing for this account will happen. Since we have multiple partner banks, this code can vary.
reserve_node_id
String
No
If the resolving loan is intended to be a secured loan. Reserve Node ID can be used to supply the ID of the collateral/reserve account associated with the secured loan.
split_ratio
Integer
No
If the only is partially secured, supplying this value will require only upto the supplied value split in the reserve_node_id
. For instance if split_ratio
is 30, that means only 30% of credit_limit needs to be in reserve_node_id
.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "Default Credit Account".
balance.amount
Number
N.A. Included in API response.
Current Balance owed by the user on this credit node.
balance.currency
String
N.A. Included in API response.
Currency of the credit node.
interest.apr
Number
Yes
Current APR rate in %.
interest.cap
Number
Yes
Max interest owed by the user in appropriate currency.
interest.accrued
Number
Yes
Interest accrued so far.
agreements.type
String
N.A. Included in API response.
agreements.url
String
N.A. Included in API response.
The PDF URL of the appropriate agreement. Each agreement contains the IP, Timestamp and Device Fingerprint of the user at the time of node creation.
document_id
String
Yes
schedule
String
Yes
Payment schedule associated with the credit node. Currently only MONTHLY
allowed.
bank_code
String
N.A. Included in API response.
Code of the bank where all the processing for this account will happen. Since we have multiple partner banks, this code can vary.
reserve_node_id
String
Yes
ID of the collateral/reserve account associated with the open loan.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "Default Credit Account".
balance.amount
String
N.A. Included in API response.
Current Balance owed by the user on this credit node.
balance.currency
String
N.A. Included in API response.
Currency of the credit node.
credit_limit.amount
Number
Yes
Max credit extended to the user.
credit_limit.currency
String
Yes
Currency of the credit node.
interest.apr
Number
Yes
Current APR rate in %.
interest.cap
Number
Yes
Max interest owed by the user in appropriate currency.
interest.accrued
Number
N.A. Included in API response.
Interest accrued so far.
agreements.type
String
N.A. Included in API response.
agreements.url
String
N.A. Included in API response.
The PDF URL of the appropriate agreement. Each agreement contains the IP, Timestamp and Device Fingerprint of the user at the time of node creation.
auto_pay
Boolean
No
If true
, users will be charged automatically based on their payment schedule. Default is false
.
payment_node_id
String
No
Node ID where the repayment would come from when auto_pay
is set to true
.
disbursement_node_id
String
Yes
Node ID where the loan should be disbursed.
document_id
String
Yes
schedule
String
Yes
Payment schedule associated with the credit node. Currently only MONTHLY
allowed.
next_payment
Number
Yes
Unix timestamp (in ms) value of when the next payment is due. When creating the loan, you need to supply an int value of how many days from today the next payment should happen.
NOTE: next_payment
is updated automatically if auto_pay
is set to True, otherwise it must be updated manually
num_payments
Integer
Yes
Number of installments to break the repayment into.
installments.amount
Number
N.A. Included in API response.
Amount due for the installment.
installments.date
Number
N.A. Included in API response.
Unix timestamp (in ms) value of when the installment payment is due.
bank_code
String
N.A. Included in API response.
Code of the bank where all the processing for this account will happen. Since we have multiple partner banks, this code can vary.
reserve_node_id
String
No
ID of the collateral/reserve account associated with the open loan.
split_ratio
Integer
No
If the only is partially secured, supplying this value will require only upto the supplied value split in the reserve_node_id
. For instance if split_ratio
is 30, that means only 30% of credit_limit needs to be in reserve_node_id
.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "BofA Checking Account".
account_num
String
Yes
Account number of the bank account.
routing_num
String
Yes
Routing number of the bank account.
speeds
Array of Strings
N.A. Included in API response.
Returns possible speeds at which payments can be sent to this account.
Possible values are NEXTDAY
,SAMEDAY
,RTP
.
In all cases, whenNEXTDAY
is supported, SAMEDAY
is as well. So functional variance will be RTP
support or not.
match_info.email_match
String
N.A. Included in API response.
If bank account is liked with our account aggregation feature, here you can see if email listed on the bank account is a match with the email on the base document. Possible values: not_found/match/no_match
.
match_info.phonenumber_match
String
N.A. Included in API response.
If bank account is liked with our account aggregation feature, here you can see if email listed on the bank account is a match with the phone on the base document. Possible values: not_found/match/no_match
.
match_info.name_match
String
N.A. Included in API response.
If bank account is liked with our account aggregation feature, here you can see if email listed on the bank account is a match with the name on the base document. Possible values: not_found/match/no_match
.
type
String
Yes if not through our account aggregation feature.
Type of ACH account. Possible values: PERSONAL
, BUSINESS
.
class
String
Yes if link not happening through our account aggregation feature.
Class of ACH account. Possible Values: CHECKING
, SAVINGS
, GENERAL_LEDGER
, LOAN
.
bank_name
String
N.A. Included in API response.
Name of bank.
bank_long_name
String
N.A. Included in API response.
Full name of the bank. In most cased bank_name
and bank_long_name
have the same value.
bank_logo
String
N.A. Included in API response.
Logo of the bank.
address
String
N.A. Included in API response.
Non-normalized address of the bank.
bank_code
String
Yes if link happening through our account aggregation feature.
Bank code used by us to denote this bank.
bank_hlogo
String
N.A. Included in API response.
Horizontal orientation friendly logo of the bank.
bank_url
String
N.A. Included in API response.
URL of the banks's website.
bank_address.address_city
String
N.A. Included in API response.
Address city of the bank's primary location.
bank_address.address_country_code
String
N.A. Included in API response.
ISO Alpha-2 formatted Address country code of the bank's primary location.
bank_address.address_postal_code
String
N.A. Included in API response.
Address zip/postal code of the bank's primary location.
bank_address.address_street
String
N.A. Included in API response.
Address street of the bank's primary location.
bank_address.address_subdivision
String
N.A. Included in API response.
Address subdivision (state) of the bank's primary location.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "BofA Debit Card".
document_id
String
Yes
card_hash
String
N.A. Included in API response.
Hash of the card details. This value can help you identify if the same card is being linked again and again throughout your platform.
card_number
String
Yes. Not in response.
exp_date
String
Yes. Not in response.
is_international
Boolean
N.A. Included in API response.
If the card is a non-US based card.
network
String
N.A. Included in API response.
Card's primary network. Possible values: AMEX
, CCPay
, Discover
, IntlMasterCard
, IntlVisa
, MasterCard
, MasterCardSend
, MoneySend
, Visa
, VisaFF
.
type
String
N.A. Included in API response.
Type of card. Possible values: Debit
, Credit
, PrePaid
.
Please use PKCS1_v1_5
padding to encrypt your data.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "Comcast Account".
account_num
String
Yes
biller_id
String
Yes
ID of the biller.
Please use PKCS1_v1_5
padding to encrypt your data.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "Rent Check".
payee_name
String
Yes
Name of the individual or business who will be receiving the check
payee_address.address_street
String
Yes
Address street of the payee.
payee_address.address_city
String
Yes
Address city of the payee.
payee_address.address_subdivision
String
Yes
Address subdivision (state) of the payee.
payee_address.address_country_code
String
Yes
ISO Alpha-2 formatted Address country code of the payee.
payee_address.address_postal_code
String
Yes
Address zip/postal code of the payee.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "Chase Checking Account".
account_num
String
Yes
Account number of the bank account.
routing_num
String
Yes
Routing number of the bank account.
bank_name
String
N.A. Included in API response.
Name of bank.
bank_long_name
String
N.A. Included in API response.
Full name of the bank. In most cased bank_name
and bank_long_name
have the same value.
bank_logo
String
N.A. Included in API response.
Logo of the bank.
address
String
N.A. Included in API response.
Non-normalized address of the bank.
bank_code
String
N.A. Included in API response.
Bank code used by us to denote this bank.
bank_hlogo
String
N.A. Included in API response.
Horizontal orientation friendly logo of the bank.
bank_url
String
N.A. Included in API response.
URL of the banks's website.
bank_address.address_city
String
N.A. Included in API response.
Address city of the bank's primary location.
bank_address.address_country_code
String
N.A. Included in API response.
ISO Alpha-2 formatted Address country code of the bank's primary location.
bank_address.address_postal_code
String
N.A. Included in API response.
Address zip/postal code of the bank's primary location.
bank_address.address_street
String
N.A. Included in API response.
Address street of the bank's primary location.
bank_address.address_subdivision
String
N.A. Included in API response.
Address subdivision (state) of the bank's primary location.
correspondent_info.routing_num
String
No
Routing number of the correspondent bank.
correspondent_info.bank_name
String
No
Name of the correspondent bank.
correspondent_info.address
String
No
Address of the correspondent bank.
Key
Type
Required
Description
nickname
String
Yes
Common name you wish to assign to the node. Eg. "HSBC Checking Account".
account_num
String
Yes
Account number of the bank account. NOTE: some countries require the account number to be in IBAN format. Please contact Synapse for a full list of countries that require IBAN account numbers.
swift
String
Yes
Routing number of the bank account in SWIFT format.
bank_name
String
N.A. Included in API response.
Name of bank.
bank_long_name
String
N.A. Included in API response.
Full name of the bank. In most cased bank_name
and bank_long_name
have the same value.
bank_logo
String
N.A. Included in API response.
Logo of the bank.
address
String
N.A. Included in API response.
Non-normalized address of the bank.
bank_code
String
N.A. Included in API response.
Bank code used by us to denote this bank.
bank_hlogo
String
N.A. Included in API response.
Horizontal orientation friendly logo of the bank.
bank_url
String
N.A. Included in API response.
URL of the banks's website.
bank_address.address_city
String
N.A. Included in API response.
Address city of the bank's primary location.
bank_address.address_country_code
String
N.A. Included in API response.
ISO Alpha-2 formatted Address country code of the bank's primary location.
bank_address.address_postal_code
String
N.A. Included in API response.
Address zip/postal code of the bank's primary location.
bank_address.address_street
String
N.A. Included in API response.
Address street of the bank's primary location.
bank_address.address_subdivision
String
Included in API response.
Address subdivision (state / province) of the bank's primary location. Required for banks in Canada (CA).
correspondent_info.routing_num
String
No
Routing number of the correspondent bank.
correspondent_info.bank_name
String
No
Name of the correspondent bank.
correspondent_info.address
String
No
Address of the correspondent bank.
bsb_number
String
No
State branch of the bank. Only needed for banks in AU
.
branch_code
String
No
Branch code of the bank. Only needed for banks in BR
,ID
,UY
.
branch_name
String
No
Branch name of the bank. Only needed for banks in CN
.
clabe
INT (18)
No
CLABE number of the bank. Only needed for banks in MX
.
routing_number
String
No
Routing number of the bank. Only needed for banks in PH
.
tax_number
String
No
Tax or Government ID number of the recipient. Required for some countries. AR
, CO
, CR
, DO
, GT
, PE
, RU
.
Type
Description
NODE_AGREEMENT
Agreement associated with node creation. This is the agreement that was presented to the user before the node was created. Please ensure that the end user has access to a copy of this agreement.
ADVERSE_ACTION
TERMINATION_LETTER
Only used in case of Credit Accounts in instances when a credit account is terminated. Please ensure that the end user has been notified of this outcome.
POST
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/barcode
This endpoint allows you to generate a barcode for Greendot's eCash feature. Currently only avaliable for Deposit Accounts.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
amount.amount
number
The amount the user wishes to deposit.
amount.currency
string
The currency of the amount.
retailer_id
integer
Greendot supports eCash for a limited number of retailers. See IDs below: - 2481 for 7-Eleven
- 2433 for CVS - 2460 for Rite Aid - 2812 for Walmart
View Green Dot Locations
Our account/routing numbers (subnets) are identical to those found at traditional banks and allow for the same functionality (e.g. the user crediting or debiting their deposit account on our system from an external bank via ACH). Users simply need to provide their assigned account and routing number to their external bank or third party software.
We also have the capability to issue cards on top of our accounts. They follow the functionality of those issued by traditional banks (e.g. ATM access, consumer protection), and give access to the interchange rails (e.g. providing the ability to push funds to the card/account).
Key
Type
Required
Description
_id
String
N.A. Included in API response.
Primary Key of the subnet object.
user_id
String
N.A. Included in API response.
ID of the user who owns this subnet.
node_id
String
N.A. Included in API response.
ID of the node who owns this subnet.
client.id
String
N.A. Included in API response.
The Primary Key that denotes your client object in our system.
client.name
String
N.A. Included in API response.
Your common name in our system.
nickname
String
Yes
Common name you wish to assign to the subnet. Eg. "Checking Account".
account_class
String
Yes
Account class of subnet. Allowed values: CHECKING
, SAVINGS
, CARD
.
status
String
No
status_code
String
No
created_on
String
N.A. Included in API response.
Unix timestamp (in ms) value of when the subnet was created.
updated_on
String
N.A. Included in API response.
Unix timestamp (in ms) value of when the subnet was last updated.
supp_id
String
No
You can use this field to store the Primary Key of this object in your system.
agreements.type
String
N.A. Included in API response or async through webhook.
Type of agreement attached on the subnet. Possible values: SUBNET_AGREEMENT
.
agreements.url
String
N.A. Included in API response or async through webhook.
The PDF URL of the appropriate agreement. Each agreement contains the IP, Timestamp and Device Fingerprint of the user at the time of subnet creation.
tokens.is_active
Boolean
No.
Current state of the linked card in the mobile wallet.
tokens.unique_reference
String or null
No.
The Mastercard unique token reference to the mobile wallet (Google Pay, Apple Pay, etc).
Key
Type
Required
Description
card_number
String
N.A. Included in API response.
Card number issued to the subnet.
cvc
String
N.A. Included in API response.
CVC associated with the subnet.
pin
String
No. Value not returned in the response.
exp
String
N.A. Included in API response.
Expiration date of card (in YYYY-MM-DD).
card_style_id
String
No
wallet_style_id
String
No
preferences.allow_foreign_transactions
Boolean
No
If True
, foreign transactions will be enabled on card.
preferences.daily_transaction_limit
Number or null
No
Daily total transaction amount (in cents) allowed on the card. Datetime tracked in UTC.
When null
, the card limits will default to your program limits.
preferences.daily_cash_limit
Number or null
No
Daily total amount in cash transactions (in cents) allowed on the card. Datetime tracked in UTC.
When null
, the card limits will default to your program limits.
preferences.monthly_transaction_limit
Number or null
No
Currently in UAT Only
Monthly overall transactions allowed on the card. Datetime tracked in UTC.
When null
, the card limits will default to your program limits.
preferences.monthly_cash_limit
Number or null
No
Currently in UAT Only
Monthly cash transactions allowed on the card. Datetime tracked in UTC.
When null
, the card limits will default to your program limits.
Key
Type
Required
Description
account_num
String
N.A. Included in API response.
Account number assigned to the subnet.
routing_num.wire
String
N.A. Included in API response.
Wire routing number assigned to the subnet.
routing_num.ach
String
N.A. Included in API response.
ACH routing number assigned to the subnet.
Please use PKCS1_v1_5
padding to encrypt your data.
Allowed
Description
INACTIVE
Currently the subnet is not active and unable to transact except for force posts.
TERMINATED
The subnet has been terminated and unable to transact except for force posts.
ACTIVE
Subnet is active and ready for use.
Allowed Status Code
Description
Next Steps
USER_REQUESTED
User requested the allowed status change. Subnet will remain inactive upon account reopen.
No action required.
FRAUD_ALERT
Either the network, Synapse or you changed the status due to fraud concerns. Subnet will remain inactive upon account reopen.
Please ensure that the end user has been notified of this update.
ACCOUNT_CLOSED
Since the user account was being closed, the subnet was closed as well. When the user account opens, the subnet will go back to active.
Please ensure that the end user has been notified of this outcome.
ACCOUNT_LOCKED
Since the user account was locked, the subnet was locked as well. When the user account opens, the subnet will go back to active.
Please ensure that the end user has been notified of this outcome.
NOT_KNOWN
Allowed status change reason unknown. When the user account opens, the subnet will go back to active.
No next steps recommend here since legacy tag.
POST
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets
This endpoint allows you to create a subnet.
We require that you first generate a preview of the subnet agreement, display it to the user to get their consent and then create the subnet. To generate a preview, add "preview_only":true
to the payload.
PATCH
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets/:subnet_id
This endpoint allows you to update a subnet.
Note: When patching subnet preferences, use USD amounts. When viewing the subnet object using a GET call, the amounts will be shown in cUSD (cents).
Mobile Wallets are digital wallets held on mobile devices that transact with merchants by turning Native Card Primary Account Numbers (PANs) into digital tokens (e.g. for use with Apple Pay, G
POST
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets/:subnet_id/push
This endpoint allows you generate a token to push card to digital wallet.
Below is an overview of the data you must pass from Synapse's API response to Apple's PKAddPaymentPassRequest
:
activationData
: This is the activation_data
returned in Synapse's API response.
encryptedPassData
: This is the encrypted_data
returned in Synapse's API response.
ephemeralPublicKey
: This is the public_key
returned in Synapse's API response.
The Opaque Payment Card ('OPC') object is a combination of the encrypted_data
and activation_data
returned in Synapse's API response, and can be constructed as follows:
Here is an example:
Once you have the OPC object, you should encode it as Base64. The above object would be:
Finally, this is the call your app would make to Google:
The current allowed permissions of the node object. Go to to learn more.
The reason for the current allowed value. Go to to learn more.
If false
, the node will not be shown in response. This feature is used to remove old accounts from a user list call if the user is not intending to use them anymore, usually used for old . If you wish to update the transaction ability of a node, please review the allowed
field. Toggling is_active
does not impact the ability of a node to transact.
This value stores the loan rejection reasons. Go to to learn more.
Go to to learn more.
They have reached the maximum number of loans that can be offered at one time. This is defined in your spec sheet. Go to to learn more.
The amount requested is higher than what can be offered. This is defined in your spec sheet. Go to to learn more.
Wrong loan type being requested. This is defined in your spec sheet. Go to to learn more.
If this is set by you, please ensure that a proper allowed status code has been supplied with it. Go to to learn more. Please ensure that the end user has been notified of this change.
Currently used for credit accounts, this code denotes that the loan request was rejected. This can be done by you when calling POST
node API call or our internal rules could cause a rejection as well. The score card is documented on your spec sheet. Go to to learn more. Please ensure that the end user has been notified of this outcome.
The node resource is used to create or link various types of liquidity accounts to the user. The purpose of this is to allow you to easily interface and build with , or . For that reason, various types of nodes have various types of information avaliable inside the info
object.
ID of the who is the primary owner of this node.
Type of agreement attached on the node. Go to to learn more.
Type of agreement attached on the node. Go to to learn more.
ID of the who is the primary owner of this node.
Type of agreement attached on the node. Go to to learn more.
ID of the who is the primary owner of this node.
Type of agreement attached on the node. Go to to learn more.
ID of the who is the primary owner of this node.
Type of agreement attached on the node. Go to to learn more.
ID of the who is the primary owner of this node.
ID of the who is the primary owner of this node.
Encrypted card number. Go to .
Encrypted expiration date in YYYYMM format. Go to .
Encrypted account number. .
Only used in case of Credit Accounts, this is an . Go to to learn more. Please ensure that the end user has been notified of this outcome.
To view available Green Dot Locations, use our endpoint. This endpoint shows locations that participate in both of Green Dot's available features: eCash and/or Swipe to Deposit.
Subnet Object issues external facing “addresses” for Synapse Wallets ( and ), which enable Synapse Wallets to interface with the outside world. The idea is pretty simple, by default all Synapse Wallets are closed loop, issuing subnets should give them a public address that can be used by other networks to interoperate with these wallets. Currently we support issuing Account Numbers that enable ACH and Wire interoperability and also Card Numbers that enable Interchange based interoperability.
Accounts don't automatically come with subnets - that is optional so you have the ability to create closed-looped systems. However, we encourage you to use account number issuance to receive funds, as there is little return risk for credits. This is especially helpful with large transactions or risky payment flows. We also recommend using account number issuance to set up direct deposit for payroll (when applicable). Please note that check issuance from these account/routing numbers is not supported. If you require check issuance, we recommend looking into our .
Cards can be issued on top of our and products. They can be virtual or physical and for businesses or individuals. We can issue debit BINs (cards that are used in the card networks' "debit card" payment network) and credit BINs (only available when the card is used for a account; makes use of the card networks' "credit card" payment network).
Status of the subnet. Go to to learn more.
Reason for status update. Go to to learn more.
Encrypted 4 digit card PIN. See . Some terminals will require a pin for debit transactions. Setting one is recommended.
Style ID of card. Used when a card is shipped. Go to to learn more.
Style ID of card when loaded on to a wallet. You can only set up pre approved wallet style ids like card style ids. Approved wallet style ids will be avaliable in your spec sheet. Go to to learn more.
Testing for Subnets on UAT mostly focuses on testing Subnet transactions. To test Card Subnet transactions, please go to . While to test Account Number Subnet transactions, please go to .
If you wish to add custom decisioning rules for subnet withdrawals, please also review add .
Shipment Objects manage all the shipping requests submitted to us. Currently we support printing and shipping a .
Go to to see all the required and optional body parameters allowed during subnet creation. Following are a few examples of various subnets and how to create them:
Go to to see all the required and optional body parameters allowed during node updates. Following are some examples of most common update calls:
Go to and to learn more.
In the following example the pin is encrypted. Go to to learn more.
Please review Apple's for additional information on how to implement push provisioning in your iOS app. Apple has 3 different "Payment Data Configurations" - Synapse uses Configuration 1.
Please review Google's for additional information on how to implement push provisioning in your Android app.
subnet_id
string
ID of the subnet.
node_id
string
ID of the node.
user_id
string
ID of the user.
full_dehydrate
string
Set to YES
if you wish to receive all subnet PII in the response. Default is NO
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
subnet_id
string
ID of the subnet.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Value
Description
STANDARD
Shipment will go through regular mail.
STANDARD|TRACKING
Shipment will go through regular mail with tracking.
EXPEDITE
Shipment will be expedited for faster delivery.
OVERNIGHT
Shipment will be spent overnight.
Value
Description
USPS
Delivery Carrier for this shipment is USPS.
FEDEX
Delivery Carrier for this shipment is FedEx.
UPS
Delivery Carrier for this shipment is UPS.
Value
Description
CREATED
Shipment has been created but not shipped yet.
BATCHED
Shipment has been issued to the card printer.
ACCEPTED
Shipment has been accepted by our card printer.
SHIPPED
Shipment has been shipped.
RETURNED
Shipment was shipped but returned.
CANCELED
Shipment was canceled and not shipped.
subnet_id
string
ID of the subnet.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
type
string
Instant provisioning type. Can be set as APPLE_PUSH
, GOOGLE_PUSH
, or SAMSUNG_PUSH
.
nonce
string
Base64-encoded nonce provided by Apple.
nonce_signature
string
Base64-encoded nonce signature provided by Apple.
certificates
string
Array of 2 certificates provided by Apple.
Key
Type
Required
Description
_id
String
N.A. Included in API response
Primary Key of the user object.
client.id
String
N.A. Included in API response
The Primary Key that denotes your client object in our system.
client.name
String
N.A. Included in API response
Your common name in our system.
ending_balance
Number
N.A. Included in API response
Ending balance of the node for this statement cycle.
opening_balance
String
N.A. Included in API response
Starting balance of the node for this statement cycle.
end_date
Number
Yes
Unix timestamp (in ms) value of the end date of cycle for this statement cycle.
start_date
Number
Yes
Unix timestamp (in ms) value of the start date of cycle for this statement cycle.
urls.csv
String
N.A. Included in API response
URL of the csv version of the statement.
urls.pdf
String
N.A. Included in API response
URL of the pdf version of the statement.
urls.json
String
N.A. Included in API response
URL of the json version of the statement.
type
String
N.A. Included in API response
Type of statement. Possible types:
On Demand Requests
(ex:ONDEMAND_STATEMENT
)
Monthly Statements
(ex: JANUARY_2021_STATEMENT
)
1099-INT Tax Forms
(ex: 1099_INT_2020
)
GET
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets/:subnet_id/ship
This endpoint allows you to get all shipments linked to a subnet.
subnet_id
string
ID of Subnet.
node_id
string
ID of Node.
user_id
string
ID of User.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20
.
page
integer
Page number of the paginated request. Default is 1
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets/:subnet_id/ship/:ship_id
This endpoint allows you to get a specific shipment.
ship_id
string
ID of the shipment.
subnet_id
string
ID of the subnet.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Key
Type
Required
Description
_id
String
N.A. Included in API response
Primary Key of the user object.
card_style_id
String
Yes
fee_node_id
String
Yes. Not included in response.
ID of the node where the shipment fee should be charged. This can only be a node that is linked to your user ID or the end user's user ID.
name
String
No
secondary_label
String
No
Optional field to include with as an additional line beneath the cardholder name (e.g. a business name).
address.address_line_1
String
N.A. Included in API response
address.address_city
String
N.A. Included in API response
address.address_state
String
N.A. Included in API response
address.address_zipcode
String
N.A. Included in API response
address.address_country_code
String
N.A. Included in API response
address.address_care_of
String
N.A. Included in API response
When address taken from MAILING_ADDRESS
and address_care_of
field is supplied there it auto-populates here.
subnet_id
String
N.A. Included in API response
Subnet ID associated with the shipment.
delivery
String
Yes
delivery_carrier
String
N.A. Included in API response
tracking
String
N.A. Included in API response
Tracking number of the shipment. Only avaliable if delivery is STANDARD|TRACKING
, EXPEDITE
or OVERNIGHT
.
created_on
String
N.A. Included in API response
Unix timestamp (in ms) value of when the shipment was created.
status
String
N.A. Included in API response
Account Type
Statement Availability
Deposit
15th of every month (EOD) for the previous month.
Credit
7th of every month (EOD) for the previous month
DELETE
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets/:subnet_id/ship/:ship_id
This endpoint allows you to cancel a specific shipment.
ship_id
string
ID of the shipment.
subnet_id
string
ID of the subnet.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
POST
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/subnets/:subnet_id/ship
This endpoint allows you to create a shipment.
subnet_id
string
ID of the subnet.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
We offer a variety of transaction features, this allows us to provide you with the proper array of solutions unique to their respective use cases.
Style ID of card. Go to to learn more.
Name of the card holder. By default grabbed from the .
Address street where the shipment was sent. By default grabbed from the unless MAILING_ADDRESS
is avaliable on social_docs
.
Address city where the shipment was sent. By default grabbed from the unless MAILING_ADDRESS
is avaliable on social_docs
.
Address state where the shipment was sent. By default grabbed from the unless MAILING_ADDRESS
is avaliable on social_docs
.
Address zipcode where the shipment was sent. By default grabbed from the unless MAILING_ADDRESS
is avaliable on social_docs
.
ISO Alpha-2 formatted Address country code where the shipment was sent. By default grabbed from the unless MAILING_ADDRESS
is avaliable on social_docs
.
Delivery speed of the shipment. Go to .
Carrier of the shipment. Go to .
Status of the shipment. Go to .
Monthly statements must be issued to the end user for all their and nodes.
Statements can be viewed at the or at the . Here is schedule for statements availability:
The goal with the statements endpoint is to enable you to easily fetch statements for all the accounts that are opened and managed using our APIs. We require that you send an email to the end users every month to deliver their monthly statements to them to comply with and .
Please note that the Shipment has to be in CREATED
status for cancellation to work. Go to to learn more.
Go to to see all the required and optional body parameters allowed during shipment creation.
To learn more about all Transaction types we support, please go to . Outside of payment accounts, we also support internal transfers between and Hubs.
user_id
string
ID of User.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20
.
page
integer
Page number of the paginated request. Default is 1
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/users/:user_id/trans
This endpoint allows you to get all transactions linked to a user.
user_id
string
ID of User.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20
.
page
integer
Page number of the paginated request. Default is 1
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/statements
This endpoint allows you to get all statements linked to a node.
node_id
string
ID of Node.
user_id
string
ID of User.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20
.
page
integer
Page number of the paginated request. Default is 1
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Amount (in USD)
Type
Return Code
222.22
DEBIT
R01 -- Insufficient Funds
222.23
CREDIT
R02 -- Account Closed
222.24
CREDIT-AND-DEBIT
R03 -- No Account/Unable to Locate Account
222.25
CREDIT-AND-DEBIT
R04 -- Invalid Account Number
222.26
CREDIT
R06 -- Returned Per ODFI's Request
222.27
DEBIT
R07 -- Authorization Revoked by Customer
222.28
DEBIT
R08 -- Payment Stopped
222.29
DEBIT
R09 -- Uncollected Funds
222.30
DEBIT
R10 -- Customer Advises Not Authorized
222.31
CREDIT-AND-DEBIT
R11 -- Check Safekeeping Entry Return
222.32
CREDIT-AND-DEBIT
R12 -- Branch Sold To Another DFI
222.33
CREDIT
R13 -- RDFI Not Qualified to Participate
222.34
CREDIT-AND-DEBIT
R14 -- Account Holder Deceased
222.35
CREDIT-AND-DEBIT
R16 -- Account Frozen
222.36
CREDIT-AND-DEBIT
R17 -- File Record Edit Criteria
222.37
CREDIT-AND-DEBIT
R20 -- Non-Transaction Account
222.38
CREDIT-AND-DEBIT
R21 -- Invalid Company Identification
222.39
CREDIT-AND-DEBIT
R22 -- Invalid Individual ID Number
222.40
CREDIT
R23 -- Credit Refused by Receiver
222.41
CREDIT-AND-DEBIT
R24 -- Duplicate Entry
222.42
DEBIT
R29 -- Corporate Customer Advises Not Authorized
222.43
CREDIT-AND-DEBIT
R31 -- Permissible Return Entry
222.44
CREDIT-AND-DEBIT
R33 -- Return of XCK Entry
222.45
CREDIT-AND-DEBIT
R34 -- Limited participation DFI
Amount (in USD)
Type
Response
222.55
CREDIT-AND-DEBIT
IR05 -- Suspicious activity; do not honor this card's transactions
222.56
CREDIT-AND-DEBIT
IR14 -- Card number does not exist
222.57
CREDIT-AND-DEBIT
IR15 -- Card issuer does not exist
222.58
CREDIT-AND-DEBIT
IR17 -- Customer cancelled/reversed payment
222.59
CREDIT-AND-DEBIT
IR18 -- The customer reversed the transaction: chargeback
222.60
CREDIT-AND-DEBIT
IR33 -- Expired card, pick-up
222.61
CREDIT-AND-DEBIT
IR36 -- Restricted card, pick-up
222.62
CREDIT-AND-DEBIT
IR38 -- PIN tried too many times; request a new card or try again later
222.63
CREDIT-AND-DEBIT
IR41 -- Lost card: request a new card
222.64
CREDIT-AND-DEBIT
IR43 -- Stolen card: request a new card
222.65
CREDIT-AND-DEBIT
IR54 -- Card Expired: request a new card
222.66
CREDIT-AND-DEBIT
IR56 -- No record of the validity of the card
222.67
CREDIT-AND-DEBIT
IR57 -- Transaction not permitted to cardholder
222.68
CREDIT-AND-DEBIT
IR58 -- Transaction denied by acceptor(Potential chargeback detected)
222.69
CREDIT-AND-DEBIT
IR59 -- Suspected Fraud
222.70
CREDIT-AND-DEBIT
IR63 -- Card information compromised(Potential chargeback detected)
222.71
CREDIT-AND-DEBIT
IR66 -- Merchant must contact the card acquirer
222.72
CREDIT-AND-DEBIT
IR67 -- Hard capture
222.73
CREDIT-AND-DEBIT
IR75 -- Allowable number of PIN tries exceeded
222.74
CREDIT-AND-DEBIT
IR79 -- Invalid digital signature
222.75
CREDIT-AND-DEBIT
IR86 -- Cannot verify PIN
222.76
CREDIT-AND-DEBIT
IR88 -- Card information not on file
222.77
CREDIT-AND-DEBIT
IR89 -- Security code verification failed
222.78
CREDIT-AND-DEBIT
IR93 -- Transaction is in violation of the law and will not be completed
222.79
CREDIT-AND-DEBIT
IR132 -- Country of the card issuer is blocked by this merchant
222.80
CREDIT-AND-DEBIT
IR140 -- Card product code is blocked
222.81
CREDIT-AND-DEBIT
IR144 -- CARD_ID is not valid
222.82
CREDIT-AND-DEBIT
IR150 -- Transaction declined by merchant to security code mismatch
222.83
CREDIT-AND-DEBIT
IR151 -- Transaction not allowed as per a validation rule
222.84
CREDIT-AND-DEBIT
IR156 -- Fraudulent transaction prior to embossed valid date
222.85
CREDIT-AND-DEBIT
IR158 -- Allowable PAN entries warning -- approved
222.86
CREDIT-AND-DEBIT
IR160 -- Security code is invalid
222.87
CREDIT-AND-DEBIT
IR174 -- Item suspected for stop pay
222.88
CREDIT-AND-DEBIT
IR174 -- Item suspected for stop pay
222.89
CREDIT-AND-DEBIT
IR175 -- Account associated with card was closed
222.90
CREDIT-AND-DEBIT
IR176 -- Account associated with card is ineligible for the transaction
222.91
CREDIT-AND-DEBIT
IR178 -- No account associated with card on file
222.92
CREDIT-AND-DEBIT
IR179 -- Unable to locate card
222.93
CREDIT-AND-DEBIT
IR189 -- Bad security code
222.94
CREDIT-AND-DEBIT
IR190 -- Transaction ordered to be stopped
222.95
CREDIT-AND-DEBIT
IR191 -- Transaction authorization revoked"
222.96
CREDIT-AND-DEBIT
IR193 -- Card lost: do not honor
222.97
CREDIT-AND-DEBIT
IR194 -- Account associated with the card is closed
222.98
DEBIT
IR201 -- Incorrect Expiration date
222.99
DEBIT
IR202 -- Card declined due to an unknown reason
223.00
DEBIT
IR203 -- Card card declined due to unsupported card type
223.01
DEBIT
IR204 -- Card declined due to an unknown reason
223.02
DEBIT
IR205 -- Card declined due to an unknown Reason
223.03
DEBIT
IR206 -- Card transaction request has an unknown status
224.01
DEBIT
IR999 -- Unauthorized Chargeback return
Amount (in USD)
Response
223.04
WR01 -- Return per customer request
223.05
WR02 -- Return per platform request
223.06
WR03 -- UTA - Account closed/frozen
223.07
WR04 -- UTA - Additional documents required
223.08
WR05 -- UTA - Country not allowed
223.09
WR06 -- UTA - Exceeds limits
223.10
WR07 -- UTA - Information mismatch
223.11
WR08 -- UTA - No Account/Unable to Locate Account
Amount (in USD)
Response
223.53
R02 - Account Closed
223.54
R03 - Account Number Invalid / no longer valid
223.55
R04 - Wrong account number
223.56
R05 - Pre-notification Error
223.57
R06 - Originator Requested Return
223.58
R07 - Authorization Revoked
223.59
R08 - Payment stopped settlement
223.60
R09 - Uncollected Funds
223.61
R10 - Advised unauthorized
223.62
R12 - Branch Sold
223.63
R14 - payee deceased
223.64
R15 - Beneficiary deceased
223.65
R16 - account frozen
223.66
R17- File Edit -record criteria
223.67
R18 - Wrong Entry Date
223.68
R19 - Account Error
223.69
R20 - Non Transaction Account
223.70
R21 - Wrong BillerId
223.71
R22 - Account Number Mistake
223.72
R23 - Payment refused by Biller
223.73
R24 - Duplicate Entry
223.74
R25 - Fair share Amount
223.75
R29 - Advised Unauthorized
223.76
R31 - Permissible Return Entry
223.77
R42 - Routing Number Error / Check Digit Error
223.78
R43 - DFI account Number
223.79
R61 - Misrouted Return
223.80
R62 - Trace number Error
223.81
R63 - Dollar Amount Mismatch
223.82
R64 - Individual Identification
223.83
R65 - Invalid Transaction Code
223.84
R66 - Invalid Company Identification
223.85
R67 - Duplicate Return
223.86
R68 - Untimely Return
223.87
R69 - Multiple Errors
223.88
R70 - Permissible Return Entry not Accepted
223.89
R71 - Misrouted Dishonored return
223.90
R72 - Untimely Dishonored Timely
223.91
R73 - Timely Original Return
223.92
R74 - Corrected Return
223.93
R80 - Cross Border Payment coding Error
223.94
R81 - Non-Cross Border Participant
223.95
R82 - Foreigner Receiver ID
223.96
R83 - Unable to Settle
223.97
R84 - Not Processed
223.98
R85 - Fair Share Rebate
Amount (in USD)
Response
223.12
CHR01 -- NSF – customer does not have sufficient funds to cover the item
223.13
CHR02 -- UCF – uncollected funds hold
223.14
CHR03 -- Stop payment – a stop payment has been placed on the item
223.15
CHR05 -- Closed account – the item’s account has been closed
223.16
CHR06 -- UTLA – unable to locate account
223.17
CHR07 -- Frozen/blocked account – account has restrictions placed by customer or bank
223.18
CHR08 -- Stale dated – the date on the item is more than 6 months old
223.19
CHR09 -- Post dated – the date on the item is in the future ‘I’ Endorsement missing
223.20
CHR10 -- Endorsement irregular
223.21
CHR11 -- Signature(s) missing
223.22
CHR12 -- Signature(s) irregular, suspected forgery
223.23
CHR13 -- Non-cash item (non negotiable)
223.24
CHR14 -- Altered/fictitious item/Suspected counterfeit/Counterfeit
223.25
CHR15 -- Unable to process
223.26
CHR16 -- Items exceeds stated max value
223.27
CHR17 -- Not authorized RCC
223.28
CHR18 -- Branch/account sold (Wrong Bank)
223.29
CHR19 -- Refer to Maker
223.30
CHR20 -- Item cannot be re-presented (exceeds allowable number of presentments
223.31
CHR21 -- unusable image
223.32
CHR22 -- Cannot determine amount
223.33
CHR23 -- Refer to image – return reason is contained within the image of the item
223.34
CHR24 -- Duplicate presentment
223.35
CHR25 -- Forgery – an affidavit shall be available upon request
223.36
CHR26 -- Warranty breach (includes Rule 8 & 9 claims)
223.37
CHR27 -- RCC warranty breach
223.38
CHR28 -- Forged and counterfeit warranty breach (Rule 9)
223.39
CHR29 -- Retired/ineligible routing number
223.40
CHR30 -- Image Missing
223.41
CHR31 -- Ineligible Item
223.42
CHR32 -- Item cannot be re-presented (exceeds number of allowable times for presentment)
223.43
CHR33 -- Unusable Image
223.44
CHR34 -- Image fails security check
223.45
CHR35 -- Duplicate presentment
223.46
CHR36 -- Does not conform with ANS X9.100-181
223.47
CHR37 -- Does not conform to the Industry’s Universal Companion Document
223.48
CHR38 -- Warranty Breach (includes Rule 8 & Rule 9 claims)
223.49
CHR39 -- RCC Warranty Breach (Rule 8)
223.50
CHR40 -- Forged and Counterfeit Warranty Breach (Rule 9)
223.51
CHR41 -- Retired/Ineligible Routing Number
tran_id
string
ID of Transaction.
node_id
string
ID of Node.
user_id
string
ID of User.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
POST
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/batch-trans
This endpoint allows you to create up-to 500 transactions (100 in sandbox) from one node at once.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
transactions
array
Go to Transaction Object Details to see all the required and optional body parameters allowed during transaction creation
When creating batch transactions, multiple transactions are processed simultaneously. Please make sure the withdrawal node has sufficient funds to process all of the transactions or the node may be depleted to a negative balance.
To enable idempotency controls per transaction, add extra.idempotency_key
inside each transaction object. Example:
GET
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/trans
This endpoint allows you to get all transactions linked to a node.
node_id
string
ID of Node.
user_id
string
ID of User.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20
.
page
integer
Page number of the paginated request. Default is 1
.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
POST
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/trans
This endpoint allows you to create a transaction.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
For a submitted RDC transaction to be processed, we also look for the following:
The image is clear enough to read all of the text on the front and back of the check. (i.e no glare, shadows on the check images) and all corners of the check are visible.
The check does not have “VOID” or “VOIDED” written on it.
The check is not a traveler’s check or substitute check.
The check amount is in U.S. dollars (USD).
The two amounts written on the check are for the same amount.
The routing number in the MIRC line has 9 digits.
The handwriting on the check looks consistent in all fields.
The payee’s name is the same as the Synapse account holder’s name.
The check number in the MICR line is the same as the check number in the top right corner.
The check written date is in the past.
The payer’s bank information has a logo and name.
The check has security features: microprinting on the signature line, security screen on the back of the check, and/or the words “original document” on the back of the check.
The check signature does not have any stains or gaps around it, nor a digitized appearance (pixelated), or unnecessary up and down pen strokes.
Nothing on either the front or back of the check appears forged or altered.
The check is signed on the back in the “Endorse here” section.
The signature on the back is different from the signature on the front.
“For mobile deposit only” is written on the back of the check.
Please Note: Attempt to deposit in person before remote submittal will cause check to be declined.
If it is a cashier’s check:
The payee’s name is printed onto the check.
The bank phone number is shown on the check.
If it is a Deluxe or e-check:
The check does not include any confirmation requirement prior to depositing it.
By default, fees are deducted from the fund recipient. This means if you send $1, the fund recipient will receive $1 minus the transaction fee.
If you prefer to cover your user's transaction fees, pre-fund a deposit account from which fees will be deducted. Then set fees.fee
to the negative of whatever the transaction fee will be, and fees.to.id
to the node ID of the pre-funded deposit account.
Note: fees.fee
is expected to be a float in dollars (USD).
In the response, you will see two fees: one positive & one negative (corresponding with our Synapse-owned node & your pre-funded node respectively).
Please note that this payload only applies to transactions initiated via the API. To cover incoming wire fees from an EXTERNAL-US
node, update your wire fee preferences in the dashboard.
Given that funds are made unavailable during the processing-debit stage in a transactions lifecycle, it is advised to not generate new transactions against the same node too quickly. The impact otherwise can be that a later transaction can settle before an earlier transaction, causing a node to go negative.
Suggestions to avoid this scenario include:
Delay same node transaction creation 4 to 5 seconds in-between.
Wait for the create webhook to be received.
DELETE
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/trans/:tran_id
This endpoint allows you to cancel a specific transaction.
tran_id
string
ID of the transaction.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
Key
Type
Required
Description
_id
String
N.A. Included in API response.
Primary Key of the transaction object.
client.id
String
N.A. Included in API response.
The Primary Key that denotes your client object in our system.
client.name
String
N.A. Included in API response.
Your common name in our system.
from.type
String
Yes. Only for RDC
transactions.
from.id
String
N.A. Included in API response.
ID of from node. In case of RDC
or EXTERNAL-US
its null
.
from.nickname
String
N.A. Included in API response.
Nickname of the node. In case of RDC
or EXTERNAL-US
its null
. This is meant to be an easy to use label, if node nickname changes in the future, nickname here wont change.
from.user._id
String
N.A. Included in API response.
ID of the user who owns the from node. In case of RDC
or EXTERNAL-US
its null
.
from.user.legal_names
Array of String
N.A. Included in API response.
Legal Name on the user profile. In case of RDC
its null
. In case of EXTERNAL-US
its the merchant or send name. This is meant to be an easy to use label, if legal names shuffle on the user profile, legal names here wont change.
from.meta
Object
Yes. Only for RDC
transactions.
to.id
String
Yes
ID of to node. In case of EXTERNAL-US
its null
.
to.nickname
String
N.A. Included in API response.
Nickname of the node. In case of EXTERNAL-US
its null
. This is meant to be an easy to use label, if node nickname changes in the future, nickname here wont change.
to.user._id
String
N.A. Included in API response.
ID of the user who owns the from node. In case of EXTERNAL-US
its null
.
to.user.legal_names
Array of String
N.A. Included in API response.
Legal Name on the user profile. In case of EXTERNAL-US
its the merchant or send name. This is meant to be an easy to use label, if legal names shuffle on the user profile, legal names here wont change.
amount.amount
Number
Yes
Amount of the transaction.
amount.currency
String
Yes
Currency of the transaction.
fees.fee
Float
No
Fee amount going to (if +ve) or being taken (if -ve) from the node, in dollars(USD).
fees.note
String
No
Note associated with the fee object. 140 Characters.
fees.to.id
String
No
ID of the fee node.
recent_status.date
Number
N.A. Included in API response.
Unix timestamp (in ms) value of when the recent status was updated.
recent_status.note
String
N.A. Included in API response.
Note associated with the recent status.
recent_status.status
String
N.A. Included in API response.
recentstatus.status_id
String
N.A. Included in API response.
timeline.date
String
N.A. Included in API response.
Unix timestamp (in ms) value of when the timeline object was created.
timeline.note
String
N.A. Included in API response.
Human readable notes associated with the timeline object.
timeline.status
String
N.A. Included in API response.
timeline.status_id
String
N.A. Included in API response.
extra
Object
Depends
Status
Status ID
Comment
QUEUED-BY-SYNAPSE
-1
Transaction has been queued by Synapse. Once reviewed, the transaction will either go to CREATED
or CANCELED
.
CREATED
1
Transaction created
PROCESSING-DEBIT
2
Funds have been pulled from the sending node.
PROCESSING-CREDIT
3
Funds are being sent to the receiving node.
SETTLED
4
Funds have been sent to the receiving node.
CANCELED
5
Transaction has been canceled.
RETURNED
6
Transaction has returned This is how ACH Returns, Card Chargebacks, Returned Wires, and similar are expressed in our system.
Key
Type
Required
Description
account_num
String
N.A. Included in API response.
Account number located on the check.
amount
String
N.A. Included in API response.
Amount located on the check.
back_signature
Boolean
N.A. Included in API response.
True
if the check has been signed at the back, else False
.
check_back
String
Yes
check_front
String
Yes
check_number
String
N.A. Included in API response.
Check number specified on the check image.
check_quality_bucket_num
String
N.A. Included in API response.
Indicates the quality of predictions made by us which ranges from 1-7 where 1 is excellent and 7 is very poor and is not an indication of the quality of the image provided.
front_signature
Boolean
N.A. Included in API response.
True
if the check has been signed on the front, else False
.
is_check
Boolean
N.A. Included in API response.
True
if the image can be auto-recognized as a check, else False
.
is_endorsed
Boolean
N.A. Included in API response.
True
if the check has been endorsed, else False
.
name
String
N.A. Included in API response.
Name of the check recipient.
original_check_back
String
N.A. Included in API response.
URL of back of the check originally supplied by you.
original_check_front
String
N.A. Included in API response.
URL of front of the check originally supplied by you.
routing_number
String
N.A. Included in API response.
Routing number located on the check.
Key
Type
Required
Description
account_num
String
N.A. Included in API response.
Account number of the sender.
addenda
String
N.A. Included in API response.
Additional payment info supplied with the transaction.
company_entry_description
String
N.A. Included in API response.
This field describes the purpose or intent of a transaction. Only avaliable for ACH Transactions.
company_id
String
N.A. Included in API response.
Unique identifier used for identifying entities. Only available for ACH Transactions.
company_name
String
N.A. Included in API response.
Name of entity who sent the payment instruction.
entry_class
String
N.A. Included in API response.
Type of transaction type.
In case of ACH
, its terms of ACH
transfers, valid SEC codes are (WEB
, PPD
, IAT
, CTX
, CCD
and TXP
). Other ACH types remain unsupported and will be rejected immediately.
In case of Wires, it's just WIRE
.
high_risk
Boolean
N.A. Included in API response.
True
if we think the transaction is a high risk transaction.
individual_id
String
N.A. Included in API response.
The number used by the originating business to identify the individual being paid or charged. Only avaliable for ACH Transactions.
monitoring_class
String
N.A. Included in API response.
name
String
N.A. Included in API response.
Name of the receiver that the payment is intended for.
posted_date
String
N.A. Included in API response.
Date of when the transaction is supposed to be posted on. Format: YYYY-MM-DD
.
posting_data
String
N.A. Included in API response.
Additional payment info supplied with the transaction.
routing_num
String
N.A. Included in API response.
Routing number of the sender.
subnet_id
String
N.A. Included in API response.
ID of the subnet where the payment instruction was sent to.
tracking_id
String
N.A. Included in API response.
Tracking number of the transaction. Trace ID for ACH and IMAD for Wires.
type
String
N.A. Included in API response.
Type of EXTERNAL-US
transaction. In this case ACH
or WIRE
.
monitoring_class
ValuesValue
Description
3rd_party_processor
Payment to a merchant processed with a third party entity
child_support
Child support payment
e-commerce
E-commerce payment
gym_membership
Fitness center monthly membership
loan
Loan payment
payroll_credits
Payroll payment
retail
Payment to a store-branded debit card
utility
Utility bill payment
accounting
Bookkeeping payments (bookkeeping software, CPAs etc.)
credit_card
Credit card payment
external_bank_transfer
Transfer to/from an external bank account
insurance
Insurance premiums
microdeposits
Micro-deposit transaction
prepaid_card
Transfer to/from a prepaid card
social_security
Social security benefit payment
veteranmilitary
Veteran military benefits payment
canpay
Payment to CanPay app
fedstate_taxes
Federal/State tax payment
investments
Transfer to/from an investment account
misc_ach
Not elsewhere classified
rent
Rent payment
unemployment
Unemployment benefits payment
Key
Type
Required
Description
routing_num
String
N.A. Included in API response.
Routing number of the sender.
tracking_id
String
N.A. Included in API response.
ID that can be used to trace the transaction internally in our network.
type
String
N.A. Included in API response.
Type of EXTERNAL-US
transaction. In this case INTERNAL_TRANSFER
.
Key
Type
Required
Description
acquirer_reference_number
String
N/A
A 23-digit identifier assigned by the merchant to uniquely identify this transaction on the card network. This is only available once a transaction is SETTLED
.
address.street
String
Yes
The street where the merchant's terminal is located. This may also be the merchant's name for e-commerce transactions.
address.city
String
Yes
The city where the merchant's terminal is located.
address.state
String
Yes
The state where the merchant's terminal is located. This field may be an empty string for international transactions.
address.zipcode
String
Yes
The zipcode where the merchant's terminal is located.
address.country
String
Yes
The country where the merchant's terminal is located. This will be the ISO 3166-1 alpha-2 country code.
approval_code
String
Yes
A 6-character alphanumeric code the Synapse provides to the merchant when approving a transaction.
condition_code
N/A
N/A
This field is always null
.
conversion_meta.settlement_currency
String
Yes
This field is always cUSD
.
conversion_meta.settlement_currency_conversion_rate
Number
Yes
The exchange rate used to convert the transaction amount in the merchant's currency to USD.
conversion_meta.transaction_currency
String
Yes
The ISO 4217 currency code
enriched_info.entity_id
String
No
Entity ID (i.e. the unique identifier that maps to the business entity / Corporate Entity Profile associated with the transaction).
enriched_info.facilitator_id
String
No
Facilitator ID (i.e. the unique identifier that maps to the facilitator / Facilitator Profile associated with transaction).
enriched_info.location_id
String
No
Location ID (i.e. the unique identifier that maps to the specific retail location / Location Profile associated with the transaction)
enriched_info.status
String
No
The status for the merchant information in the Knowledge Repository. The value can either be SETTLED
or PENDING
.
fees.amount
Number
No
The amount of the fee, in cents.
fees.type
String
No
foreign_transaction
Boolean
Yes
This field indicates whether the transaction was performed in a country other than the cardholder's home country.
is_recurring
Boolean
Yes
This field indicates whether the transaction was previously authorized as a recurring transaction.
is_force_post
Boolean
Yes
mcc
String
Yes
The 4-digit "Merchant Category Code".
mid
String
Yes
The "Merchant Identifier" used by the card network to identify the merchant.
pan_entry_mode
String
Yes
partial_approval_allowed
Boolean
Yes
This field indicates whether the transaction can be "partially approved" for an amount less than the requested transaction amount.
pin_entry_mode
String
Yes
presentment_info.card_presence
String
Yes
presentment_info.cardholder_presence
String
Yes
presentment_info.security_concern
String
Yes
presentment_info.type
String
Yes
rebates.amount
Number
No
rebates.type
String
No
revenues.amount
Number
No
The total amount of interchange revenue generated by the transaction (in cents).
revenues.type
String
No
The kind of revenue; either a switch_fee
charged by the network or interchange
generated by the transaction.
revenues.meta.program
String
No
The interchange rate category of the transaction.
revenues.meta.cap
Number
No
The maximum amount of revenue that can be assigned to a transaction in the given interchange category.
revenues.meta.fixed_rate
Number
No
The flat amount of revenue generated by a transaction independent of the transaction value.
revenues.meta.variable_rate
Number
No
The percentage (in basis points) of the transaction amount that will be paid as revenue in addition to the fixed_rate.
revenues.meta.daily_adjustment_rate
Number
No
The amount (in cents) added to the unadjusted_value
to compute the final revenues amount
. This value is based on the total revenue reported by the card network (e.g. Mastercard or Visa)
revenues.meta.unadjusted_value
Number
No
The amount (in cents) of the total revenue generated by a transaction before the daily_adjustment_rate
was applied.
sub_amounts.amount
Number
No
The amount, in cents.
sub_amounts.type
String
No
subnet_id
String
Yes
The Synapse subnet ID.
terminal_id
String
Yes
A value assigned by the merchant that is used to identify the terminal where this transaction originated.
terminal_info.attendance
String
Yes
terminal_info.card_input_capability
String
Yes
terminal_info.card_retention_capability
String
Yes
terminal_info.location
String
Yes
terminal_info.operator
String
Yes
terminal_info.type
String
Yes
type
String
Yes
pan_entry_mode
ValuesValue
Description
UNSPECIFIED
PAN entry mode unknown.
MANUAL
PAN manual entry.
INTEGRATED_CIRCUIT_CARD
PAN auto-entry via EMV chip.
QR_OR_BARCODE
PAN auto-entry via QR or barcode reader.
OCR
PAN auto-entry via optical character reader (OCR).
KEY_ENTERED
PAN manual entry.
CONTACTLESS
PAN auto-entry via contactless EMV chip.
ELECTRONIC
PAN/Token entry via electronic commerce containing DSRP (Digital Secure Remote Payments) cryptogram.
CHIP_FAILURE_USED_MANUAL
A hybrid terminal with an online connection to the acquirer failed in sending a chip fallback transaction (CHIP_FAILURE_USED_TRACK
). To complete the transaction, a voice transaction takes place during which the merchant communicates the PAN and the expiry date originating from the magnetic stripe to the acquirer.
CHIP_FAILURE_USED_TRACK
Chip card at chip-capable terminal was unable to process transaction using data on the chip; therefore, the terminal defaulted to the magnetic stripe-read PAN. The full track data has been read from the data encoded on the card and transmitted to Synapse.
FROM_FILE
Credential on file.
FROM_SERVER
PAN auto entry via server (issuer, acquirer, or third party vendor system).
FROM_OTHER_CARDLESS_ENTRY
PAN/Token entry via electronic commerce with optional SecureCode-AAV or DSRP cryptogram in UCAF.
MAGNETIC_STRIPE_FULL
PAN auto-entry via magnetic stripe; the full track data has been read from the data encoded on the card and transmitted to Synapse.
MAGNETIC_STRIPE_CONTACTLESS
PAN auto-entry via contactless magnetic stripe; the full track data has been transmitted by the merchant to Synapse.
APPLE_PAY
PAN/Token entry via Apple mobile wallet.
GOOGLE_PAY
PAN/Token entry via Google mobile wallet.
SAMSUNG_PAY
PAN/Token entry via Samsung mobile wallet.
TOKEN
PAN entry via token; this merchant does not store the full card number and instead uses a token when initiating transactions.
pin_entry_mode
ValuesValue
Description
UNSPECIFIED
Terminal PIN entry capability unknown.
PIN_ENTRY_CAPABILITY
Terminal has PIN entry capability.
PIN_ENTRY_NO_CAPABILITY
Terminal does not have PIN entry capability.
PIN_PAD_INOPERATIVE
Terminal has PIN entry capability but PIN pad is not currently operative.
PIN_VERIFIED_BY_TERMINAL
presentment_info.card_presence
ValuesValue
Description
CARD_PRESENT
Card present.
CARD_NOT_PRESENT
Card not present.
PRE_AUTHORIZED_PURCHASE
Card not present; transaction previously authorized.
presentment_info.cardholder_presence
ValuesValue
Description
CUSTOMER_PRESENT
Cardholder present.
CUSTOMER_NOT_PRESENT
Cardholder not present.
MAIL_ORDER
Cardholder not present; mail order.
TELEPHONE_ORDER
Cardholder not present; phone order.
RECURRING_PAYMENT
Standing order or recurring transaction.
PRE_AUTHORIZED_PURCHASE
DEFERRED_BILLING
INSTALLMENT_PAYMENT
presentment_info.security_concern
ValuesValue
Description
NO_SECURITY_CONCERN
SUSPECTED_FRAUD
IDENTIFICATION_VERIFIED
ELECTRONIC_TRANSACTION_WITH_DIGITAL_SIGNATURE
NONSECURE_ELECTRONIC_TRANSACTION
SECURE_ELECTRONIC_TRANSACTION_WITH_CARDHOLDER_CERTIFICATE
SECURE_ELECTRONIC_TRANSACTION_WITHOUT_CARDHOLDER_CERTIFICATE
CHANNEL_ENCRYPTED_ELECTRONIC_TRANSACTION
CVV_VALID
CVV_INVALID
INTERNET_PINNED_DEBIT_TRANSACTION
presentment_info.type
ValuesValue
Description
ORIGINAL_PRESENTMENT
FIRST_REPRESENTMENT
SECOND_REPRESENTMENT
THIRD_REPRESENTMENT
PREVIOUSLY_AUTHORIZED_REQUEST
RESUBMISSION
CARD_VALIDATION
sub_amounts.type
ValuesValue
Description
AMOUNT_CASH
The amount of cash disbursed for a PURCHASE_WITH_CASH_DISBURSEMENT
transaction.
AMOUNT_GOODS_AND_SERVICES
CO_PAYMENT
HEALTHCARE_AMOUNT
TRANSIT_AMOUNT
PRESCRIPTION_AMOUNT
VISION_AMOUNT
CLINIC_AMOUNT
DENTAL_AMOUNT
terminal_info.attendance
ValuesValue
Description
ATTENDED
Attended terminal.
UNATTENDED
Unattended terminal (e.g. home PC, mobile phone)
terminal_info.card_input_capability
ValuesValue
Description
UNKNOWN
Input capability unknown or unspecified.
MANUAL
MAGNETIC_STRIPE
Terminal supports magnetic stripe input only.
BARCODE_OR_QR
OCR
ICC
Terminal supports EMV contact chip input only.
KEY_ENTERED
Terminal supports key entry input only.
FILE
CONTACTLESS_READ_VIA_MAG_STRIPE_RULES
Terminal supports contactless magstripe input but not contactless EMV input. The terminal also may support one or more other card input types, including EMV contact chip input, magnetic stripe input, and key entry input.
CONTACTLESS_READ_VIA_CHIP_RULES
Terminal supports contactless EMV input and contactless magstripe input. The terminal also may support one or more other card input types, including EMV contact chip input, magnetic stripe input and key entry input.
MAG_STRIPE_AND_KEY_ENTRY
Terminal supports magnetic stripe input and key entry input.
MAG_STRIPE_AND_KEY_ENTRY_AND_EMV
Terminal supports EMV contact chip input, magnetic stripe input and key entry input.
MAG_STRIPE_AND_EMV
Terminal supports EMV contact chip input and magnetic stripe input.
SECURE_CARDLESS_ENTRY
terminal_info.card_retention_capability
ValuesValue
Description
DEVICE_CANNOT_RETAIN_CARD
Terminal/operator does not have card capture capability.
DEVICE_CAN_RETAIN_CARD
Terminal/operator has card capture capability.
terminal_info.location
ValuesValue
Description
ON_PREMISE
Terminal is on premises of the merchant.
OFF_PREMISE
Terminal is off premises of the merchant (remote location).
terminal_info.operator
ValuesValue
Description
CUSTOMER_OPERATED
CARD_ACCEPTOR_OPERATED
ADMINISTRATIVE
terminal_info.type
ValuesValue
Description
ADMINISTRATIVE_TERMINAL
POS_TERMINAL
ATM
HOME_TERMINAL
ECR
DIAL_TERMINAL
TRAVELERS_CHECK_MACHINE
FUEL_MACHINE
SCRIP_MACHINE
COUPON_MACHINE
TICKET_MACHINE
POINT_OF_BANKING_TERMINAL
TELLER
FRANCHISE_TELLER
PERSONAL_BANKING
PUBLIC_UTILITY
VENDING
SELF_SERVICE
AUTHORIZATION
PAYMENT
VRU
SMART_PHONE
INTERACTIVE_TELEVISION
PERSONAL_DIGITAL_ASSISTANT
SCREEN_PHONE
ELECTRONIC_COMMERCE
MICR_TERMINAL
OFF_PREMISE
type
ValuesValue
Description
PURCHASE
CASH
DEBIT_ADJUSTMENT
PURCHASE_WITH_CASH_DISBURSEMENT
NON_CASH_FINANCIAL_INSTRUMENT
QUASI_CASH
WITHDRAWAL_TO_ELECTRONIC_ACCOUNT
RETURN
DEPOSIT
CREDIT_ADJUSTMENT
PAYMENT_RETURN
PAYMENT_TO_THIRD_PARTY
PAYMENT_DEBIT
PAYMENT_FROM_THIRD_PARTY
PAYMENT_CREDIT
Key
Type
Required
Description
created_on
Number
N.A. Included in API response.
Unix Timestamp of when the transaction was crated.
asset
String
rate
Number
N.A. Included in API response.
rate_limit
Number
No
supp_id
String
No
This field is usually used to link processor transaction PK with ours. 250 characters.
In case of external transactions, this field stores a unique hash to identify the transaction.
In case of transactions originated by you, it can be a PK from your dB.
group_id
String
No
Used to group transaction together.
note
String
No
Memo associated with the transaction.
encrypted_note
String
No
Any memo supplied here will be encrypted and stored in our system. Used mostly for RPPS transactions where sometimes PII is supplied as a memo.
process_on
Integer
No
Date to process transaction. Supplied as an integer in days, returned by the api in Unix epoch time.
settlement_delay
Integer
No
Amount of time to delay transaction (in days). Generally a positive delay in days. NOTE: A negative value between, and including, -1 to -7 can be provided to speed settling of trusted users ACH-US related transactions specifically.
tracking_number
String
N.A. Included in API response.
Tracking number associated with the transaction. In case of ACH its the trace ID and in case of wires its IMAD.
same_day
Boolean
No
[Same-day ACH must be enabled for your platform]
This field is now deprecated
. Please use speed instead.
Set this to true
if you wish to settle the transaction on the same day.
speed
String
No
[Same-day ACH or RTP must be enabled for your platform and suppored by the receving bank.]
Speed at which you wish to process the ACH payment. Options: RTP
(credit only), SAMEDAY
or NEXTDAY
(default).
other.attachments
Array
No
List of padded base64 attachments.
other.chargeback_disputed
Boolean
No
Set to true
if the transaction has been disputed for chargeback. Only applicable for interchange transactions.
other.dispute_meta
Object
No
other.is_provisional_credit
Boolean
N.A. Included in API response.
Set to true
if the transaction is a provisional credit.
other.parent_transaction_id
String
N.A. Included in API response.
If the transaction is a provisional credit, then this ID will indicate the disputed transaction.
txp_meta
Object
No
interchange_meta
Object
No
Key
Type
Required
Description
dispute_form
String
N.A. Included in API response.
PDF record of the dispute. This is for internal use and does not need to be provided to your user.
dispute_form_id
String
N.A. Included in API response.
dispute_status
String
N.A. Included in API response.
dispute_status_note
String
N.A. Included in API response.
provisional_credit_transaction_id
String
N.A. Included in API response.
Provisional credit granted to the end-user from the Platform’s reserve while the dispute investigation is taking place.
created_date
N.A. Included in API response.
type_of_merchandise_or_service
Required for dispute type CHARGE_BACK
The type of merchandise or service (e.g. GROCERY
).
merchant_contacted
boolean
Required for dispute type CHARGE_BACK
Whether the merchant was contacted.
contact_method
contact_date
attachments
list
Documents related to the dispute case.
network_credit_transaction_id
string
N.A. Included in API response.
A credit from the network for the disputed transaction.
network_representment_transaction_id
string
N.A. Included in API response.
A debit from the network when the Merchant submits a chargeback representment for the dispute
dispute_status
ValuesValue
Description
PENDING
Default status of a new dispute.
CREATED
The dispute has been batched to the network.
PENDING|SUBMITTED
The dispute has been successfully submitted to the network.
PENDING|WON
Received a chargeback credit from the network.
PENDING|LOST
The network rejected the dispute. The dispute may not have met the criteria for the dispute reason or the chargeback window elapsed. In some cases, compliance can/will re-open the case. Dispute will move to CLOSED|LOST
after 45 days of inactivity or PENDING
if re-opened.
CLOSED|WON
Case closed after 45 days of receiving a chargeback credit.
CLOSED|LOST
Received a representment debit from the network or the dispute's status is updated for inactivity (from PENDING|LOST
).
dispute_status_note
ValuesDispute Status Note is supposed to be a free string field, but in some instances disputes can fail instantly due to some network and internal rules we’ve set. This means the dispute case will not be created and submitted. In those cases, the dispute_status_note
filed might have one of the following values:
Value
Description
invalid_amount
Cannot dispute transactions under $25. Cannot dispute PPE transactions under $50.
emv_transaction
Cannot dispute a valid EMV transaction.
afd_transaction
Cannot dispute AFD transactions.
chargeback_limit_exceeded
Cannot submit more than 15 disputes per PAN.
invalid_reason
Cannot use dispute reason (UNAUTHORIZED|CARD_IN_HAND
) for Card Present transactions.
invalid_reason|emv_fallback
Cannot use dispute reason (UNAUTHORIZED|CARD_IN_HAND
) for EMV fallback transactions.
Key
Type
Required
Description
tin
String
Yes
Tax Identification Number
payment_code
String
Yes
Tax Payment Type Code
tax_period_end_date
String
Yes
Tax Period End Date (YYMMDD)
amount_types
Array of Strings
Yes
amounts
Array of Integers
Yes
Tax Amounts (in cents)
taxpayer_verification
String
No
Taxpayer Verification
amount_types
ValuesCurrently the following values are supported for amount type:
TAX
PENALTY
INTEREST
STATE
LOCAL
CITY
FEE
ESCROW
ESTIMATED
ANNUAL
EXTENSION
AUDIT
LOAN
UNDER_PROTEST
RETURN
BILL
PRIOR_OVERPAYMENT
CREDIT_MEMO
DISCOUNT
LEVY
GARNISHMENT
Key
Type
Required
Description
soft_descriptor
String
No
Soft Descriptor functionality enables you to dynamically modify the external bank's statement descriptor on a per-transaction basis
PATCH
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/trans/:tran_id
This endpoint allows you to retry a specific transaction.
Only ACH transactions that returned can be retried for now. If a retry fails, you will receive a 400 Bad Request response with error.code:cannot_retry_transaction_****
.
Information in our system is constantly changing, long after API calls have been made.
To stay updated on the latest details for users, nodes, subnets and transactions, we recommend subscribing to webhooks. This allows you to register a URL to receive updates as they occur.
Example Use Cases:
A previously verified user may be flagged for a sanctions match.
A node’s balance may update after a payment has posted.
A subnet may be locked after the user is locked for fraud.
A transaction may begin processing after it is created.
Synapse will send ~5 retries within a 24 hour period for any failed webhook delivery. A webhook delivery is considered a failure unless your server responds with one of the following HTTP codes: 200
, 204
, 400
, 404
, 405
, 408
.
After the failed attempts, we will log the webhooks. That way, even if we fail to deliver the request, you can still access the original request and the reason as to why the webhook failed.
Currently we send Webhooks from the following IP addresses:
Every webhook is signed with HMAC.
HMAC is a protocol that helps you judge the authenticity of the received message. This comes in handy when you want to quickly find out whether the webhook was sent by Synapse or a malicious/notorious party.
The signature is a SHA-1
and SHA-256
HMAC hash of the object_id
+ your client_id
, with the secret key as your client_secret
.
Please note: Python (FullBody) uses the entire body of a webhook to create a signature, which can be used to rebuild a X-Synapse-Signature-SHA256-FullBody
signature.
You will be able to rebuild the signature the following way:
Please note that raw should look like this (with +):
563db3fb86c27307d925871f+e3f19e4bd4022c86e7f2
Not like this (without +):
563db3fb86c27307d925871fe3f19e4bd4022c86e7f2
.
Since the SHA-1
signature is in hex, it should look like this:5bce964c20b0c36313d8f7cffc2ff4772d0c96750
We then take this signature and add it into the header of the request with name X-Synapse-Signature
and X-Synapse-Signature-Sha256
.
PATCH
https://api.synapsefi.com/v3.1/trans/:tran_id/dispute-chargeback
This endpoint allows you to dispute a chargeback that you received on Interchange Transactions.
Only INTERCHANGE-US
transactions that have been RETURNED
within the last 14 days with return code of IR999
can be disputed.
PATCH
https://api.synapsefi.com/v3.1/users/:user_id/nodes/:node_id/trans/:tran_id/dispute
This endpoint allows you to dispute a card transaction.
Below is the table of legacy dispute reason codes.
Currently Dispute Meta is only required for Card Transaction. Following are the fields allowed in dispute_meta
:
Please note that , , and are transactions that cannot be created by the API as by the very nature of the transaction, the user accounts receive them vs create them via the API.
Go to to see all the required and optional body parameters allowed during transaction creation. Following are a few examples of various types of transactions and how to create them:
Below is an example of how to create a transaction between two nodes that exist in Synapse. If you wish to cover transaction fees, see our .
Unlike , for RDC transactions, both from
and to
nodes are part of the payload, while from
is not really a node, its the RDC data:
To cancel a transaction en route to the recipient, the transaction must not have been batched already. For example, to cancel transactions between native Synapse accounts (ex: Deposit Accounts), they need to have status CREATED
or QUEUED-BY-SYNAPSE.
While a transaction leaving a Deposit Account, to an ACH-US account can be canceled with status CREATED
, QUEUED-BY-SYNAPSE
orPROCESSING-DEBIT
(because outgoing ACH is batched during PROCESSING-CREDIT
).
You cannot cancel an already settled transaction, with the exception of Reversals for Interchange Pull transactions.
If a cancelation fails, you will receive a 400 Bad Request response with error.code:cannot_cancel_transaction
. Go to to learn more.
Type of , RDC
or EXTERNAL-US
.
Go to to learn more.
Current status of the transaction. Go to to learn more.
Current status id of the transaction. Go to to learn more.
Status of the timeline object. Go to to learn more.
Status id of the timeline object. Go to to learn more.
Go to for more details.
Various types of transactions have different types of meta data avaliable. Other than RDC
, all other transactions that have meta info are not created by you, but are more so incoming transactions coming into a node (either as a debit or credit) through a .
URL of back of the check. Supplied as an encoded via the API which then is converted to a URL by us. The file types accepted are JPEG, PNG, WEBP, TIFF, BMP and PDF. Please ensure that the image is clear, with all corners visible in case of a document with legible text. Once the image has gone through our RDC vision stack, the url returned will be the url of a post-processed B/W and cropped check image ready for X9 processing.
URL of front of the check. Supplied as an encoded via the API which then is converted to a URL by us. The file types accepted are JPEG, PNG, WEBP, TIFF, BMP and PDF. Please ensure that the image is clear, with all corners visible in case of a document with legible text. Once the image has gone through our RDC vision stack, the url returned will be the url of a post-processed B/W and cropped check image ready for X9 processing.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Go to to learn more.
Meta object containing all the details associated with a TXP ACH transaction. Go to to learn more.
Meta object containing all the details associated with a Interchange transaction. Go to to learn more.
Go to to learn more.
Go to to learn more.
Tax Information ID Number (Amount Type). to learn more.
If dispute is won, the transaction will go back to SETTLED
status. We recommend to be notified.
If you wish to learn more about Card Disputes, see: .
tran_id
string
ID of the transaction.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
retry_transaction
boolean
True
if the transaction needs to be retried.
Key
Type
Description
_id.$oid
String
Object ID of webhook
client_id
String
Object ID of Client
date
Integer
Date webhook was created (milliseconds since Unix epoch time)
function
String
Resouce | Method
http_response_code
String
Response code from webhook URL
http_response_text
String
Response text from webhook URL
http_responses[]
Array
List of response data from webhook URL. See Webhook Response Object (below) for more information.
http_url
String
URL webhook was sent to
object_id
String
Object ID attached to resource type
safe_obj._id.$oid
String
Object ID of resource
safe_obj._rest
Object
Contains information about the resource (node, transaction, user, subnet objects)
safe_obj.webhook_meta
Object
Contains information about webhook subscription updates (e.g. who the object was updated by, function used to perform the update, etc)
safe_obj.webhook_meta.function
String
The function associated with the webhook (e.g. "NODE|PATCH")
safe_obj.webhook_meta.log_id
String
The ID of the log associated with the webhook
safe_obj.webhook_meta.updated_by
String
Who updated the webhook subscription (e.g. "SELF", "BACKEND, etc)
safe_obj.webhook_meta.date.$date
Integer (milliseconds since Unix epoch time)
The wehbook creation date
safe_obj_hash
String
Hashed object information
updated_by
String
For internal use
Key
Type
Description
date
Integer
Date webhook received a response from webhook URL. Use of this value is recommended for ordering webhook responses when receiving them from Synapse.
http_response_code
String
Response code from webhook URL
http_response_text
String
Response text from webhook URL
http_url
String
URL webhook was sent to
tran_id
string
ID of the transaction.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
docs
array
Array of base64 objects of evidence submitted for disputing chargeback. The file types accepted are JPEG, PNG, WEBP, TIFF, BMP, GIF and PDF.
tran_id
string
ID of the transaction.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of your device.
X-SP-GATEWAY
string
Your Client ID and Secret, separated by a pipe.
dispute_attachments
array of strings
Additional attachments (in base64) with the dispute form when disputing a transaction. The file types accepted are JPEG, PNG, WEBP, TIFF, BMP, GIF and PDF.
dispute_meta
string
Meta data associated with the dispute.
dispute_reason*
string
Reason for filing a dispute.
FRAUD|UNAUTHORIZED|CARD_IN_HAND
FRAUD|UNAUTHORIZED|CARD_LOST
FRAUD|UNAUTHORIZED|CARD_IN_HAND|SHARED
FRAUD|UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED
FRAUD|FRAUDULENT_PROCESSING_OF_TRANSACTIONS
FRAUD|QUESTIONABLE_MERCHANT_ACTIVITY
FRAUD|CARDHOLDER_DOES_NOT_RECOGNIZE_POTENTIAL_FRAUD
FRAUD|CHIP_LIABILITY_SHIFT
FRAUD|CHIP_LIABILITY_SHIFT|LOST|STOLEN|NRI
PROCESSING_ERROR|CORRECTION|TERMINAL_MALFUNCTION
PROCESSING_ERROR|WARNING_BULLETIN_FILE
PROCESSING_ERROR|AUTHORIZATION_RELATED_CHARGEBACK
PROCESSING_ERROR|ACCOUNT_NUMBER_NOT_ON_FILE
PROCESSING_ERROR|INCORRECT_AMOUNT
PROCESSING_ERROR|CHARGED_TWICE
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS
PROCESSING_ERROR|POINT_OF_INTERACTION_ERROR
PROCESSING_ERROR|CANCEL_RECURRING_PMT
PROCESSING_ERROR|LATE_PRESENTMENT
PROCESSING_ERROR|INCORRECT_CURRENCY
PROCESSING_ERROR|INSTALLMENT_BILLING_DISPUTE
PROCESSING_ERROR|CHARGE_BACK
PROCESSING_ERROR|ADDENDUM_NO_SHO_ATM_DISPUTE
PROCESSING_ERROR|INCORRECT_AMOUNT|ATM
PROCESSING_ERROR|CREDIT_NOT_PROCESSED
PROCESSING_ERROR|CHIP_READ_POS_LATE_PRESENTMENT
PROCESSING_ERROR|DOMESTIC_CHARGEBACK_INTRAR_EUROPEAN_USE
SERVICE|MERCHANT|DEFECT_OR_NOT_AS_DESC
SERVICE|MERCHANT|NOT_RECEIVED
SERVICE|MERCHANT|QUALITY
SERVICE|MERCHANT|DAMAGED_MERCH
SERVICE|MERCHANT|RETURNED_MERCH
SERVICE|CARDHOLDER_DISPUTE
SERVICE|CARDHOLDER_DISPUTE|NOT_ELSEWHERE_CLASSIFIED
SERVICE|GOODS_OR_SERVICES_NOT_PROVIDED
FRAUD|UNAUTHORIZED|CARD_IN_HAND
FRAUD|UNAUTHORIZED|CARD_LOST
FRAUD|UNAUTHORIZED|CARD_IN_HAND|SHARED
FRAUD|UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED
FRAUD|CHIP_LIABILITY_SHIFT
FRAUD|NO_CARDHOLDER_AUTHORIZATION
PROCESSING_ERROR|CHARGED_TWICE
PROCESSING_ERROR|CASH_DISPUTE|ATM_ONLY
PROCESSING_ERROR|CARDHOLDER_DISPUTED_AMOUNT
PROCESSING_ERROR|INCORRECT_AMOUNT|ATM
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS
PROCESSING_ERROR|CANCEL_RECURRING_PMT
PROCESSING_ERROR|CREDIT_NOT_PROCESSED
PROCESSING_ERROR|INCORRECT_AMOUNT
PROCESSING_ERROR|DUPLICATE_TRANSACTION
PROCESSING_ERROR|CREDIT_NOT_RECEIVED
PROCESSING_ERROR|LATE_PRESENTMENT
PROCESSING_ERROR|INVALID_ADJUSTMENT_AMOUNT
PROCESSING_ERROR|INVALID_ADJUSTMENT_AMOUNT|INSUFFICIENT_FUNDS
SERVICE|CHARGE_BACK
SERVICE|MERCHANT|QUALITY
SERVICE|MERCHANT|DAMAGED_MERCH
SERVICE|MERCHANT|RETURNED_MERCH
SERVICE|MERCHANT|DEFECT_OR_NOT_AS_DESC
SERVICE|NON_RECEIPT_OF_MERCHANDISE
SERVICE|MERCHANT|NOT_RECEIVED
FRAUD|UNAUTHORIZED|CARD_IN_HAND
FRAUD|UNAUTHORIZED|CARD_LOST
FRAUD|UNAUTHORIZED|CARD_IN_HAND|SHARED
FRAUD|UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED
FRAUD|CARD_PRESENT_TRANSACTION
FRAUD|UNAUTHORIZED_PURCHASE
FRAUD|CHARGE_BACK
FRAUD|CHIP_CARD_COUNTERFEIT_TRANSACTION
FRAUD|CHIP_CARD_AND_PIN_TRANSACTION
FRAUD|CARD_NOT_PRESENT_TRANSACTION
PROCESSING_ERROR|CORRECTION|TERMINAL_MALFUNCTION
PROCESSING_ERROR|INVALID_CARDHOLDER_NUMBER
PROCESSING_ERROR|DUPLICATE_PROCESSING
PROCESSING_ERROR|CANCEL_RECURRING_PMT
PROCESSING_ERROR|AUTHORIZATION|LATE_PRESENTMENT
PROCESSING_ERROR|INCORRECT_TRANSACTION_TYPE
PROCESSING_ERROR|CREDIT_NOT_PROCESSED
PROCESSING_ERROR|ALTERED_AMOUNT
PROCESSING_ERROR|INCORRECT_AMOUNT
PROCESSING_ERROR|NON_RECEIPT_OF_CASH_FROM_ATM
PROCESSING_ERROR|CHARGED_TWICE
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE
PROCESSING_ERROR|CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS
PROCESSING_ERROR|INCORRECT_AMOUNT|ATM
PROCESSING_ERROR|PAID_BY_OTHER_MEANS
SERVICE|QUALITY_OF_GOODS_AND_SERVICES
SERVICE|NON_RECEIPT_OF_GOODS_AND_SERVICE
SERVICE|MERCHANT|NOT_RECEIVED
SERVICE|MERCHANT|QUALITY
SERVICE|MERCHANT|DAMAGED_MERCH
SERVICE|MERCHANT|RETURNED_MERCH
Code
Description
Chargeback_Rights
INCORRECT_AMOUNT
Incorrect Amount was charged on the card.
Yes. No if the transaction is a VALID EMV transaction.
INCORRECT_AMOUNT|ATM
User attempted to withdraw money from ATM and received incorrect amount.
Yes, but only for the amount not dispensed.
UNAUTHORIZED|CARD_LOST
Unauthorized transaction made and user has reported a lost or stolen card.
Yes. No if the transaction is a VALID EMV transaction or online transaction as this defaults to chip-liability shift, which is not applicable to MOTO transactions, or at an ATM.
UNAUTHORIZED|CARD_IN_HAND|SHARED
Unauthorized transaction made while user has card in their possession and card is shared with other users.
Yes. No if the transaction is a VALID EMV transaction, or disputed transactions was authorized by other users of the card, or at an ATM.
UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED
Unauthorized transaction made while user has card in their possession and card is not shared with other users.
Yes. No if the transaction is a VALID EMV transaction, or at an ATM.
CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE
There was a duplicate transaction but the merchant did not process a credit to correct the error. This typically occurs when when a merchant a merchant fails to correct a previously acknowledged error. This can also occur when a cardholder attempts to return a purchased item or cancel services but is not compliant with the merchant's return policy (e.g. expired receipt or warranty issue).
Yes. No if the transaction is a VALID EMV transaction, or no duplicate posts to same account.
CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS
There was a duplicate transaction in which the original debit settled on the card even though the original card transaction was canceled. Occurs when the cardholder chose to use another payment method (e.g. cash or a different card).
Yes. No if the transaction is a VALID EMV transaction, or there is not supporting evidence of a charge elsewhere.
CANCEL_RECURRING_PMT
Canceling recurring payment (i.e. a recurring payment was debited after cancellation).
Yes. No if the transaction is a VALID EMV transaction, or cancellation was within three days of charge authorization.
MERCHANT|DEFECT_OR_NOT_AS_DESC
Merchandise/service not as described or defective merchandise/service.
Yes. No if the transaction is a VALID EMV transaction.
MERCHANT|NOT_RECEIVED
Did not receive merchandise or services (not a quality issue).
Yes. No if the transaction is a VALID EMV transaction, or if merchant hasn't been allowed 15 calendar days for items to arrive or to provide a date of expected arrival.
MERCHANT|QUALITY
Issue with quality of services or merchandise.
Yes. No if the transaction is a VALID EMV transaction, or services were paid for after service was rendered.
MERCHANT|DAMAGED_MERCH
Damaged merchandise.
Yes. No if the transaction is a VALID EMV transaction.
MERCHANT|RETURNED_MERCH
Returned merchandise.
Yes. No if the transaction is a VALID EMV transaction, or there is no supporting evidence of a return.
FRAUD|FRAUDULENT_PROCESSING_OF_TRANSACTIONS
Authorized card-present transaction with a merchant but received additional non-authorized transactions within the following fifteen minutes.
Yes. No if proof can be provided that a refund was issued or provide evidence that additional transactions are authorized.
FRAUD|QUESTIONABLE_MERCHANT_ACTIVITY
Merchant is suspected of fraud by Mastercard, and has been placed under the Global Merchant Audit Program.
Yes. No if merchant is not on Global Merchant Audit Program.
FRAUD|CARDHOLDER_DOES_NOT_RECOGNIZE_POTENTIAL_FRAUD
User claims they do not recognize a transaction and the transaction is a Card-not-Present transaction
Yes. No if merchant can verify the card was present for transaction.
FRAUD|AUTHORIZATION_RELATED_CHARGEBACK
Merchant did not get authorization for a transaction, or authorization was sent after the transaction date.
Yes. No if proof can be provided that authorization was obtained and authorization date request was not after the transaction date.
Key
Type
Required Dispute Reasons
Description
amount_debited
Float
INCORRECT_AMOUNT
Amount debited in Number.
amount_received
Float
INCORRECT_AMOUNT|ATM
Amount received in Number.
lost_date
Int
UNAUTHORIZED|CARD_LOST
Date lost (milliseconds since Unix epoch time).
how_lost
String
UNAUTHORIZED|CARD_LOST
Description of how card was lost or stolen.
last_use
String
UNAUTHORIZED|CARD_IN_HAND|SHARED
UNAUTHORIZED|CARD_IN_HAND|NOT_SHARED
Transaction ID for last use of card (i.e. need transaction ID to know where and when card was last used).
people_allowed_use
String
UNAUTHORIZED|CARD_IN_HAND|SHARED
Person(s) who cardholder shared card with (i.e. allowed to use card) and their relationship(s) with cardholder.
contact_date
Object with $date attribute
CANCEL_RECURRING_PMT
Contact date (milliseconds since Unix epoch time).
contact_method
String
CANCEL_RECURRING_PMT
Contact method (e.g. PHONE
).
trans_on_same_card
Boolean
CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE
CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS
Are both transactions on the same card? true
or false
.
Proof of other transaction required in dispute_attachments
merch_given_attempt_to_resolve
Boolean
CHARGED_TWICE|CREDIT_NOT_PROCESSED|DUPLICATE
CHARGED_TWICE|CREDIT_NOT_PROCESSED|PAID_BY_OTHER_MEANS MERCHANT|RETURNED_MERCH
Was the merchant given the chance to resolve? true
or false
.
contact_name
String
CANCEL_RECURRING_PMT
Name of contact.
contact_response
String
CANCEL_RECURRING_PMT
Response from contact.
merch_item_desc
String
MERCHANT|DEFECT_OR_NOT_AS_DESC MERCHANT|RETURNED_MERCH
Description of the merchandise
date_received
Int
MERCHANT|DEFECT_OR_NOT_AS_DESC
Date merchandise/item was received
matched_verbal_or_written_desc
Boolean
MERCHANT|DEFECT_OR_NOT_AS_DESC
Did the item or service not match the verbal description
matched_receipt_desc
Boolean
MERCHANT|DEFECT_OR_NOT_AS_DESC
Did the item or service differ from as described on the receipt
merchandise_received_as_part_of_transaction
Boolean
MERCHANT|DEFECT_OR_NOT_AS_DESC
Was Merchandise Received as Part of Transaction
order_canceled
Boolean
MERCHANT|NOT_RECEIVED MERCHANT|RETURNED_MERCH
Was the order canceled
expected_arrival_date
Int
MERCHANT|NOT_RECEIVED
Date when it was expected to arrive
was_item_delivered
Boolean
MERCHANT|NOT_RECEIVED
Was item delivered
prepaid_item
Boolean
MERCHANT|NOT_RECEIVED
Was this item a prepaid item
recurring_payment
Boolean
MERCHANT|RETURNED_MERCH
Was this a recurring payment
merch_returned
Boolean
MERCHANT|RETURNED_MERCH
Was the merchandise returned
merch_returned_attempted
Boolean
MERCHANT|RETURNED_MERCH
Was the merchandise attempted to be returned
reason
String
MERCHANT|RETURNED_MERCH
Reason for Return or cancelation
cancel_policy_provided
Boolean
MERCHANT|RETURNED_MERCH
Was a cancelation Policy provided
Code
Description
R07
Authorization Revoked by Customer
R08
Payment Stopped
R10
Customer Advises Not Authorized
R29
Corporate Customer Advises Not Authorized
R23
Credit Refused by Receiver
GET
https://api.synapsefi.com/v3.1/subscriptions/subscription_id
This endpoint allows you to view a specific subscription.
subscription_id
string
Object ID of subscription.
X-SP-GATEWAY
string
Your Client ID & Secret, separated by a pipe.
GET
https://api.synapsefi.com/v3.1/subscriptions
This endpoint allows you to get all subscriptions linked to your client keys.
page
integer
Page number
per_page
integer
Number of subscriptions per page
X-SP-GATEWAY
string
Your Client ID & Secret, separated by a pipe
Key
Type
Required
Description
_id
String
N.A. Included in API response
Object ID of Subscription
client_id
String
N.A. Included in API response
ID of your client object
is_active
Boolean
No
true
if subscription is active else false
.
scope
Array of Strings
Yes
url
Array of Objects
Yes
URL Destination for webhooks
Scope
Effect
USERS|POST
When a user is created with your gateway, you will receive a webhook
USER|PATCH
When a user in your platform is updated, you will receive a webhook
NODES|POST
When a node is created with your gateway credentials, you will receive a webhook
NODE|PATCH
When a node is updated with your gateway credentials, you will receive a webhook
TRANS|POST
When a transaction is created within your gateway credentials, you will receive a webhook
TRANS|POST|JIT
When a transaction is created within your gateway credentials that requires Transaction Decisioning, you will receive a webhook.
TRAN|PATCH
When a transaction is updated with your gateway credentials, you will receive a webhook
SUBNETS|POST
When a subnet is created with your gateway credentials, you will receive a webhook
SUBNET|PATCH
Whenever a subnet is updated with your gateway credentials, you will receive a webhook
POST
https://api.synapsefi.com/v3.1/subscriptions
This endpoint allows you to create a subscription to stay updated on the status of users, nodes, transactions & subnets.
Content-Type
string
This value should be application/json
X-SP-GATEWAY
string
Your Client ID & Secret, separated by a pipe
scope
array
Scope of subscription.
url
string
URL destination for webhooks
PATCH
https://api.synapsefi.com/v3.1/subscriptions/subscription_id
This endpoint allows you to update a subscription.
subscription_id
string
Object ID of subscription
Content-Type
string
This value should be application/json
X-SP-GATEWAY
string
Your Client ID & Secret, separated by a pipe
is_active
boolean
Active status
Table of specific WIRE-INT data attributes as required by individual countries.
Bank accounts should be stored as strings without spaces.
A number of countries require that the bank account number be in IBAN format as noted in the table below.
A number of countries require a tax / government ID (in LATAM often called a Cedula number) this should be stored on the tax_number attribute, as noted in the table below.
Several countries have other required attributes as indicated in the Other Required Fields column in the table below.
In order to ensure delivery of your webhooks, we recommend testing your webhook integration. Tools like are helpful when testing webhooks.
See for more details.
Go to to see all the required and optional body parameters allowed when creating a subscription.
Go to to see all the required and optional body parameters allowed when updating a subscription.
filter
string
MongoDB filter to enable search by biller_name
type of functionality.
per_page
integer
Maximum documents to return per page. Default and max allowed is 20.
page
integer
Page number of the paginated request. Default is 1.
Content-Type
string
This value should be application/json
page
integer
Page number
per_page
integer
Number of logs per page
X-SP-GATEWAY
string
Your Client ID & Secret, separated by a pipe
Content-Type
string
This value should be application/jsonon
address_street
string
Street address associated with the document owner. This can be the home address of a person or business address of a corp. Please include apartment suite or unit numbers.
address_city
string
City associated with the document owner. This can be the home address of a person or business address of a corp.
address_subdivision
string
State abbreviation associated with the document owner. This value needs to be in ISO Alpha-2 (e.g. CA)
address_postal_code
string
Country associated with the document owner. This can be the home address of a person or business address of a corp. This value needs to be in ISO Alpha-2 (e.g. US)
address_country_code
string
Postal code associated with the document owner. This can be the home address of a person or business address of a corp.
Deliverability Result
Description
deliverable
✅
Check normalized_address
object in response for deliverable address to use (e.g. in case "ST" supplied when deliverable address has "AVE")
usps_deliverable
✅
Standard supplied address is a USPS deliverable address
deliverable_incorrect_unit
✅
Base address is deliverable but supplied unit appears incorrect (e.g. actual unit number may be "APT 103" and original input may point to a non-existent unit like "APT 1003")
deliverable_missing_unit
✅
Base address is deliverable but expected unit was not supplied. Check normalized_address
object in response for deliverable address to use
deliverable_unneccessary_unit
✅
Address is deliverable but additional unit supplied when not necessary
Key
Type
Description
deliverability_analysis. partial_valid
Boolean
True if address is partially valid
deliverability_analysis. primary_number_invalid
Boolean
True if primary address number is invalid
deliverability_analysis. primary_number_missing
Boolean
True if primary address number is missing
deliverability_analysis. secondary_invalid
Boolean
True if secondary address line (e.g. unit) is invalid or unnecessary
deliverability_analysis. secondary_missing
Boolean
Secondary address line (e.g. unit) missing
subnet_id
string
ID of the subnet.
node_id
string
ID of the node.
user_id
string
ID of the user.
X-SP-USER
string
User's OAuth key and device fingerprint, separated by a pipe.
X-SP-USER-IP
string
IP address of user's device.
Content-Type
string
This value should be application/jsonon
currency
string
Currency of the transaction. Currently only USD
is supported.
amount
number
Amount of the transaction.
type
string
Type of dummy transaction. Currently ACH
, WIRE
and INTERNAL_TRASFER
are the only allowed values.
direction
string
Direction of the transaction. Can either be DEPOSIT
or WITHDRAWAL
account_num
string
Account number of the external account.
routing_num
string
Routing number of the external account.
addenda
string
Addenda information supplied with the transaction.
tracking_id
string
Trace or IMAD of the incoming transaction.
posting_label
string
Merchant or individual name of the incoming transaction.
company_id
string
Company ID of the sender.
individual_id
string
Individual ID of the sender.
Afghanistan
AF
Algeria
DZ
IBAN
Andorra
AD
IBAN
Angola
AO
IBAN
Argentina
AR
CBU
Required
Armenia
AM
Aruba
AW
Australia
AU
info.bsb_number
Austria
AT
IBAN
Azerbaijan
AZ
IBAN
Required
Bahamas
BS
Bahrain
BH
IBAN
Bangladesh
BD
Barbados
BB
Belgium
BE
IBAN
Belize
BZ
Benin
BJ
IBAN
Bermuda
BM
Bhutan
BT
Bolivia
BO
Botswana
BW
Brazil
BR
IBAN
info.branch_code
Brunei
BN
Bulgaria
BG
IBAN
Burkina Faso
BF
IBAN
Cambodia
KH
Cameroon
CM
IBAN
Canada
CA
info.transit_code,
info.bank_address.address_subdivision
Some examples: for subdivision use
“ON” for Toronto
“QC” for Montreal
“BC” for Vancouver
Also for transit_code it is best to include the full routing number as a string.
Cape Verde
CV
IBAN
Cayman Islands
KY
Chad
TD
IBAN
Chile
CL
Required
info.bank_code
China
CN
info.branch_name
Colombia
CO
Required
info.bank_code
Comoros
KM
Costa Rica
CR
IBAN
Required
Cote d Ivoire
CI
IBAN
Croatia
HR
IBAN
Cyprus
CY
IBAN
Czech Republic
CZ
IBAN
Democratic Republic of the Congo
CD
Denmark
DK
IBAN
Djibouti
DJ
Dominican Republic
DO
IBAN
Egypt
EG
IBAN
Equatorial Guinea
GQ
Eritrea
ER
Estonia
EE
IBAN
Eswatini (previously Swaziland)
SZ
Ethiopia
ET
Falkland Islands (Malvinas)
FK
Faroe Islands
FO
IBAN
Fiji
FJ
Finland
FI
IBAN
France
FR
IBAN
French Guiana
GF
French Polynesia
PF
IBAN
Gabon
GA
IBAN
Gambia
GM
Georgia
GE
Germany
DE
Ghana
GH
Gibraltar
GI
IBAN
Greece
GR
IBAN
Greenland
GL
IBAN
Guadeloupe
GP
Guatemala
GT
IBAN
Required
Guinea
GN
Guinea Bissau
GW
IBAN
Guyana
GY
Haiti
HT
HOLY SEE (Vatican City State)
VA
Honduras
HN
Hong Kong
HK
Hungary
HU
IBAN
Iceland
IS
IBAN
India
IN
info.bank_code
Indonesia
ID
info.branch_code
Ireland
IE
IBAN
Israel
IL
IBAN
Italy
IT
IBAN
Jamaica
JM
Japan
JP
Jordan
JO
IBAN
Kazakhstan
KZ
IBAN
Required
Kenya
KE
Kuwait
KW
IBAN
Kyrgyzstan
KG
Laos
LA
Latvia
LV
IBAN
Lesotho
LS
Liechtenstein
LI
IBAN
Lithuania
LT
IBAN
Luxembourg
LU
IBAN
Macau
MO
Macedonia
MK
IBAN
Madagascar
MG
IBAN
Malawi
MW
Malaysia
MY
Maldives
MV
Malta
MT
IBAN
Martinique
MQ
Mauritania
MR
IBAN
Mauritius
MU
IBAN
Mayotte
YT
Mexico
MX
info.clabe
Moldova
MD
IBAN
Monaco
MC
IBAN
Mongolia
MN
Montenegro, Republic of
ME
IBAN
Morocco
MA
IBAN
Myanmar
MM
Namibia
NA
Nepal
NP
Netherlands
NL
IBAN
Netherlands Antilles
AN
New Caledonia
NC
IBAN
New Zealand
NZ
Niger
NE
IBAN
Norway
NO
IBAN
Oman
OM
Papua New Guinea
PG
Paraguay
PY
Required
Peru
PE
Required
Philippines
PH
info.transit_code
Poland
PL
IBAN
Portugal
PT
IBAN
Qatar
QA
IBAN
Republic of the Congo
CG
IBAN
Reunion
RE
Romania
RO
IBAN
Rwanda
RW
Samoa
WS
San Marino
SM
IBAN
Sao Tome and Principe
ST
IBAN
Saudi Arabia
SA
IBAN
Senegal
SN
IBAN
Seychelles
SC
Sierra Leone
SL
Singapore
SG
info.bank_code
Slovakia
SK
IBAN
Slovenia
SI
IBAN
Solomon Island
SB
South Africa
ZA
South Korea
KR
Spain
ES
IBAN
Sri Lanka
LK
St. Piere et Miquelon
PM
Suriname
SR
Sweden
SE
IBAN
Switzerland
CH
IBAN
Taiwan
TW
Tajikistan
TJ
Thailand
TH
Togo
TG
IBAN
Tonga
TO
Trinidad and Tobago
TT
Tunisia
TN
IBAN
Turkmenistan
TM
Uganda
UG
United Arab Emirates
AE
IBAN
United Kingdom
GB
IBAN
Uruguay
UY
Required
info.branch_code
Uzbekistan
UZ
Vanuatu
VU
Viet Nam
VN
Wallis and Futuna Islands
WF
IBAN
Zambia
ZM
POST
https://api.synapsefi.com/v3.1/routing-number-verification
This endpoint allows you to verify routing numbers.
Content-Type
string
This value should be application/json
type
string
Type of Node (ACH-US
or WIRE-US
)
routing_num
string
Routing number of the bank
Intro
3D Secure (3DS) is a security protocol designed to better authenticate cardholders performing Card Not Present transactions. This feature provides issuers with enhanced data elements that allows for smarter authorization and authentication practices. It also supports additional customer verification flows when needed, such as multi-factor authentication.
All 3DS transactions will follow one of three paths - 1) Green, 2) Yellow or 3) Red.
Green Path - no customer verification required
Yellow Path - customer verification required
Red Path - transaction declined (no customer verification attempted)
API Response
The following fields will be visible in the API response to provide insight into 3DS transactions.
three_ds_auth
This field indicates whether the transaction was processed using 3D Secure (3DS) authentication
True - the transaction was processed using 3DS authentication
False - the transaction was not processed using 3DS authentication
Null - transaction does not qualify for 3DS
three_ds_auth_path
This field specifies the path taken for the 3DS transaction
G - Green path, no customer verification required
Y - Yellow path, customer verification required
R - Red path, transaction declined (no customer verification attempted) Null - transaction does not qualify for 3DS
Pre-Authorizations ("pre-auths") are temporary holds that merchants place on a cardholder's funds instead of immediately debiting the cardholder. They tend to be for a higher amount than the price of the purchased product/service. Pre-auths can be inconvenient for the final user because they will be unable to spend the pre-authed funds until the pre-auth window has passed and the transaction has either settled or returned. This is often confusing for users because the transaction is not yet visible on their statements, since the transaction has not yet (technically) taken place.
For example, a user could have an initial bill of $23 for food delivery. However, the merchant issues a $30 pre-auth to account for anticipated tips. After a couple of days, the merchant settles the transaction and includes the user's $2 tip, making the final transaction amount $25.
Expected Behavior
When a pre-auth is initiated, a transaction is created with "status": "CREATED"
. The pre-auth amount is determined by the merchant (with the exception of Automated Fuel Dispenser Transactions, mentioned below). If the user has the funds, it will move quickly to "status": "PROCESSING-DEBIT"
and then "status": "PROCESSING-CREDIT"
.
If the merchant does complete the transaction, the transaction will be updated with "status": "SETTLED"
and "code": "pre_auth_completion"
.
If the merchant does not complete the transaction after 7 days, the pre-auth will drop, with "status": "RETURNED"
and "code": "pre_auth_expiration"
.
Please keep in mind:
Pre-Auths will count toward a user's limits
We have seen online merchants make heavy use of pre-auths
It is not uncommon for the final settled amount to be higher than the pre-auth amount. This is expected behavior. However, if you suspect a merchant is fraudulently inflating the settlement amount, our only real recourse is filing disputes or requesting to block the merchant altogether.
Additionally, please note that we cannot cancel a pre-auth while it is processing, so if a user creates a transaction and is later locked, you will ultimately be responsible for covering any losses.
Automated Fuel Dispenser (AFD) transactions (aka “gas transactions") are pre-auths associated with fuel purchases at gas stations. Synapse sets the standard pre-auth amount for such transactions at $100. This temporary hold ensures the cardholder is liable for up to $100 when the pre-auth clears. If the value of the fuel dispensed was less than $100, the transaction will settle for the lower amount and the balance of the associated node should update once the pre-auth completes (i.e. with "recent_status.status": "SETTLED"
and "recent_status.note": "pre_auth_completion"
).
Currently the UI Supports Online Shopping like Amazon, ATM usage, POS payments like Whole Foods and In N Out and also P2P payments like Venmo and PayPal.
GET
https://api.synapsefi.com/v3.1/enrich/:merchant_id
This endpoint allows you to view detailed merchant information for entity_id
, facilitator_id
, location_id
or biller_id
.
Content-Type
string
This value should be application/json
Entity, Facilitator or Location IDs are returned as a part of a card transaction stream. These values are located either in from.meta.enriched_info
in case of a push transaction or to.meta.enriched_info
in case of a pull transaction.
For instance, for a transaction description like PAYPAL *NETFLIX.COM 4029357733 CA 950327620
, enriched_info
will look like the following:
For that reason, we enable higher level of control on Subnet withdrawals, to address three needs:
Ability to Pass/Fail a transaction based some custom criteria built on your side.
Ability to fund the transaction through one or more accounts (funding nodes) at the time of transaction decisioning, not before.
Additional ability to fund a pre-auth approved transaction to safe guard against variable final total amounts (example tip on a restaurant bill).
If the network allows, only approve a transaction partially.
We also enable decisioning for incoming card based credits, but with stricter criteria:
The transaction can not be a cash deposit.
You can only Pass/Fail the transaction. You can not pass funding nodes or partial approval amounts.
Must not be a force post transaction.
To be able to decision a transaction, you need to respond in the following format:
Field
Type
Required
Description
decision
String
Yes
Supply PASS
if you intend to let the transaction go through. Otherwise supply FAIL
.
funding_nodes.node_id
String
No
Node ID where the supplied amount should be funded from. Not supported for credits.
funding_nodes.amount
Number
No
The amount that needs to be taken out of the supplied node id. Not supported for credits.
total_amount
Number
No
Total amount approved for the transaction. Can be lower than the amount on transaction if partial approval is allowed. Not supported for credits
additional_funding
String
No
In a pre-auth scenario, if there is a remaining balance, the remainder will be taken from the node(s) defined here. Not supported for credits.
Upon receiving a supported subnet transaction, we will notify you via the TRANS|POST|JIT
webhook url. Your response will indicate to us whether to allow ({"decision": "PASS"}
) or deny ({"decision": "FAIL"}
) the transaction.
If the transaction is approved (PASS), then funds can be pulled directly from the account that the subnet sits on top of.
Example Payloads
or
If you wish to fund the transaction from an account other than the account the subnet sits on top of, then you can pull funds directly from one or more funding nodes (either user or platform accounts) specified in the response.
If funding for the transaction comes from multiple accounts (listed in the funding_nodes
array supplied in the response), then you must both specify the exact amount
to be pulled from each node and ensure that the overall transaction's total_amount
field equals the sum of the amounts pulled from each funding node. If both of these criteria are not met, the transaction will silently fail.
Please also note that providing an invalid node_id
for any of the listed funding nodes will also cause the transaction to silently fail.
Example Payloads
Single Node Funding
Multiple Funding Nodes via JIT
The additional_funding nodes deduction only occurs if the total_amount increased and does nothing if the total_amount decreases.
Following are some things to be mindful of while building with Transaction Decisioning:
Transaction will still settle if there are insufficient funds. However, if there are insufficient funds and another cancel reason it will fail.
Upon being notified of a new transaction request by the TRANS|POST|JIT
webhook you will need to perform your custom transaction logic, provide funding (if using Instant Auth), and provide a response within 1.00 seconds, or else the transaction will follow the default path of decisioning, in other words, as if JIT did not exist.
Funding from other nodes does not perform balance checks on the nodes due to the timely response considerations mentioned above (i.e. response required within 1.00s), meaning that use of this feature with a funding node that has insufficient funds to cover a transaction will make that node's balance go negative.
It is your responsibility to both perform periodic balance checks and to maintain an estimate of funding node balances to avoid this (i.e. to have a reasonable expectation that a funding node can cover a transaction before allowing it).
Consider how to handle transactions with a debit card cashback component (e.g. from a user who took a cash disbursement along with their purchase at a retail register). This information should be provided in the webhook's transaction request notification (e.g. {"type": "PURCHASE_WITH_CASH_DISBURSEMENT"}
with sub_amounts
array containing {"amount_type": "AMOUNT_CASH"}
). You can either approve the full transaction amount, provide Partial Approval only for the purchased goods, or deny the transaction.
We will perform basic account and user KYC checks (e.g. making sure the user has SEND-AND-RECEIVE
permissions and that the user watchlists
flag is not a MATCH
) prior to ever issuing a request from the TRANS|POST|JIT
webhook. This means that you should not receive requests from users who are unable to transact.
When we receive an incoming card based credit transaction (Examples: CashApp or Venmo transfers), we will generate a webhook for these transactions. This allows you to control if and when you allow users to do things like transfer funds from a CashApp account to their Synapse account. Any transaction that involves a CASH deposit will not generate a webhook. Refund transactions and any others that might be force posts also will not generate a webhook as those can not be refused. Not responding to these webhooks at all, or not responding within the expected time frame, will allow the transaction to be deposited like normal.
When thinking about onboarding a user, it’s important to understand the entire user experience. The process described below focuses on the recommended User Experience including KYC, node creation, and any necessary subnets.
Notes:
Nodes and subnets can be created while the user is still "Unverified"
Users must be verified to open a LOAN-US node
Interchange revenue is calculated per card transaction. Summing the amount fields from each revenue object within the revenues array (revenues.{}.amount
) will provide the total/net interchange revenue for the transaction.
Refer to each example response body below for more details:
For ATM transactions, the issuer pays revenues to the ATM owner's bank. This results in interchange fees rather than revenues for transactions at ATMs.
So in this case, Interchange revenue amounts (revenues.{}.amount
) will always be negative and in the case of switch fees, will have type: switch_fee
. Here is an example:
For this transaction the net interchange revenue would be (–$0.50) + (–$0.06) = (–$0.56)
For interchange transactions, the issuer gets revenue. So in this case, Interchange revenue amounts (revenues.{}.amount
) will be positive. Here is an example:
For this transaction the net interchange revenue would be $0.47 + (-$0.03) = $0.44.
Once a month, the interchange revenue amounts (e.g. the $0.44 and -$0.56 figures from the examples above) across all transactions for the previous month are added up (including negative values from fees) to calculate the net interchange revenue generated by your Platform for the month.
Then, the Platform Interchange Revenue is calculated by applying the Interchange Split, a predetermined percentage set in the Platform Master Services Agreement (e.g. 60%), to the total monthly interchange revenue as shown by the formula below:
Once the amount is calculated, we disburse the revenue into your designated interchange revenue account. Your interchange revenue account can be designated on your dashboard (it is typically a DEPOSIT-US
account under your master account). To make things easy for your accounting team, we will also attach a revenue summary in the disbursement transaction's JSON under extra.other.attachments
. That revenue summary will be the total interchange revenue from Mastercard, without the applied split.
There are two ways to connect a card subnet with a mobile wallet of choice:
As with most cards, end users can add cards to their preferred mobile wallet (e.g. directly from Apple Pay, Google Pay, or Samsung Pay) by providing their card details (e.g. PAN, expiration date, CVV, billing address, etc.) to the mobile wallet provider. However this process either requires end users to digitally scan their cards using OCR (Optical Character Recognition) or provide their card details via manual text input.
While protecting payment transactions in flight is a critical part of reducing card-related fraud, with mobile wallets, there is the ability to reduce fraud at the time of provisioning cards into mobile wallets like Apple Pay and Google Pay. To help Platforms reduce fraud during card provisioning with these services, we have extended the data fields that we are consuming during provisioning to trigger additional fraud checks at the time of provisioning.
Through the enablement of multi-factor authentication, Platforms can leverage a verified phone number/email.
In order to assist in the prevention of fraud from suspicious activity, cards will now be locked out of mobile wallet provisioning for 24 hours in certain cases in which the system flags an increased risk of fraud, including a certain level of bad CVV2 attempts in a period of time.
Mobile Wallet Art will be associated with virtual card profiles. Each profile will map to all of the tokens that use its card art. Therefore, to update the card art for multiple tokens that share a particular card profile, you simply need to update the card profile with new art. Conversely, to only update the card art for a single token, you would re-assign that token to a different card profile (i.e. either to another existing card profile or to a new one). When submitting a card art, please provide the following:
A short description of the card (e.g. for lock screen notifications). This short description should include the word "Mastercard" and can be a maximum of 32 characters in length.
SVG (recommended) or PNG image in RGB color format. The image dimensions can be up to 1372 x 283 pixels.
SVG (recommended) or PNG image in RGB color format. The image dimensions must be 1536 x 969 pixels and have square corners.
Card background + platform logo + brand mark (Mastercard).
If Debit, cards must include the "debit" identifier. SVG (recommended) or PNG image in RGB color format. The image must be 1536 x 969 pixels and have square corners. Example: Synapse's combined card art (below).
For push notifications related to the card. PNG or SVG image in RGB color format The image must be exactly 100 x 100 pixels. Example: Synapse's approved app icon (below).
This is used to overlay the background of the card art.
This is used for the masked card PAN digits that are overlaid on the bottom left of the card image.
This is used for the short description text rendered on the card image if the card image (Card Background Combined or Card Background) is not available for some unexpected reason.
Please allot up to 10 business days after the card art has been accepted by us for the new card profile to take effect.
When card art is updated, all the tokens associated with the profile are automatically liked to the new card art.
If you wish not to do that, please request a new profile with new art to avoid changing all tokens.
Provisional Credit is applied against your Reserve Account. So there will be a transaction originating from your reserve account, going into the user's deposit account. Provisional Credits post in the following timeframe for the end users:
Provisional credits are automatically created if the disputed transaction meets the requirements. The disputed transaction must be a debit in order to be eligible for provisional credits. Also, the dispute reason must be either MERCHANT|RETURNED_MERCH
or MERCHANT|DEFECT_OR_NOT_AS_DESC
.
Since filing a dispute costs $25, any disputed transaction that is $25 or less will automatically result in a provisional credit regardless of the aforementioned requirements.
Please Note: This update was added at the end 2020 and only newer disputes will have this information.
The investigation will conclude when we receive a response from the merchant or network involved in the processing of the transaction. Should the chargeback be honored by the merchant, we will receive funds back in response. These will either be credited to the user’s account (merchant dispute) or to the your reserve (all other disputes) as appropriate.
The funds will be returned to your reserve account if a provisional credit was applied. Otherwise the funds will be credited back to the user's account.
Should the chargeback not be honored by the merchant, or it was determined there were no chargeback rights given the type of transaction or the manner in which it was processed, the provisional credit will be considered final and the user will be notified.
Should the chargeback not be honored by the merchant, but they respond with evidence that the user was in fact involved in the transaction or authorized the transaction, the provisional credit will be rescinded from the user’s account and credited back to the Platform’s reserve.
Once the investigation has been completed, we will notify the user within 3 business days with its final decision based on the results of the chargeback.
Here is the lifecycle of the entire dispute process. Throughout the investigation, the dispute’s status is updated as we get information from the network:
Disputes are batched and submitted everyday at 4:00 PM PST. A response file for the batch is received at 4:30 PM PST each day that will tell us whether the cases are successfully added, updated, or if there was an error.
There is an incoming file from the card network at 3:30 PM PST each day that notify us of any updates to open dispute cases.
At 6:10 PM PST we start our reconciliation process for the day. During this time, we may process some dispute-related offline adjustments. This can either be a network chargeback credit or representment debit.
When a representment debit is received, our compliance team will review the dispute case and make a decision on whether or not the provisional credit is returned to the platform’s reserve account. Provisional credit should remain with the user unless there is proof showing the transaction is authorized.
Network chargeback credits and representment debits from the network will be directed to the platform’s reserve, if provisional credit was given to the end user, otherwise it will be directed to the end user’s node.
A dispute enters pre-arbitration once a merchant has represented the transaction with compelling evidence and the Platform decides to contest the re-presentment. Generally speaking, it may be prudent to submit a pre-arb for high value transactions when you believe the compelling evidence is insufficient and therefore does not prove that no error occurred.
Pre-arbs may be submitted for the following types of transactions:
ATM withdrawals
Authorization related chargebacks
Chip liability chargebacks
Lost/Stolen/Never received related chargebacks
Following is the lifecycle of a Pre-Arb:
Submitting a per-arb can become quite costly should you lose the case. It is important to weigh the costs against the potential benefits before submitting a pre-arb. We recommend establishing a de minimis to help prevent undue costs. Here are the costs of Pre-Arbs:
$150 filing fee + $250 administrative fee; the combined $400 fee is paid by the losing party after ruling.
$150 filing fee to withdraw from arbitration before a ruling.
This information is stored in our ever-expanding Knowledge Repository and returned with transactions in Enriched Info (enriched_info
) for Card Transactions.
When a card transaction is received by us, we run it through our Knowledge Repository to appropriately assign:
the Merchant Profile(s) that describe the type of business, physical retail location, or facilitator who provided Synapse with the transaction.
the Transaction Category (enriched_info.category
) for the transaction to place it into easily recognizable "buckets" from which potentially the end user, platform, or Synapse could then take further actions.
One-off locations (e.g. a "mom-and-pop" location that is not part of a chain or other larger corporate entity) may only have a location_id
(i.e. you will find both entity_id: "null"
and facilitator_id: "null"
).
Please also note that you may also find location_id: "null"
(e.g. for an online-only transaction for Netflix facilitated by PayPal)
If the business is not currently confirmed in our Knowledge Repository, then all values associated with the enriched_info
attached to the transaction may be "null"
. Additionally, if a transaction was not matched to a Merchant Profile in the repository, status
will be "PENDING" (it may take up to 48 hours to review and update information in the repository).
Lastly, if you suspect the merchant information is incorrect. Please follow these steps to report these issue to us:
If the enriched_info.status: "SETTLED"
and the name, logo, or official_page is incorrect
OR
If the enriched_info.status: "PENDING"
and the name, logo, or official_page is incorrect for greater than 48 hours
The Knowledge Repository consists of Merchant Profiles that represent the businesses we provide enriched financial data about. A Merchant Profile can represent:
a larger business or corporate entity,
a specific retail location, or
a facilitator.
Please refer to basic details and examples below.
Please note that a retail location that is part of a larger business or corporate entity will have its own Location Profile and will reference the Corporate Entity Profile of its parent company. A singular business location (e.g. a "mom and pop" operation with only one location) will have a Location Profile but will not reference a parent company (i.e. will not reference a Corporate Entity Profile).
We similarly classify transactions from businesses by functionally combining their transactions into the following general categories:
How your platform chooses to pull data from our Knowledge Repository will vary based on the maturity of your platform and the size of your user base. An early-stage startup and a large enterprise operation will have different priorities in terms of optimizing for speed of development vs maximizing efficiencies at scale. Here are three suggestions:
Early-Stage Approach (suitable for early-stage startups or for initial rapid prototyping)
Growth Approach (suitable for growth-stage companies beginning to scale up operations)
Enterprise Approach (suitable for enterprises performing operations at scale)
This approach is by far the easiest to implement, but is an inefficient solution at scale.
This approach means that you will be performing (and therefore repeating) distinct API calls to retrieve Merchant Profiles from the Knowledge Repository each time you process a new transaction.
This approach attempts to strike a balance between development time, ease of implementation, and scalability, but it is a less efficient approach than the Enterprise approach below.
At the user device level, cache knowledge objects (i.e. aggregate unique IDs) and associated Merchant Profiles locally for quick retrieval.
This approach will require you to refresh Knowledge data on user devices regularly (e.g. every 72 hours), and also means that you will be storing more data on user devices than is technically relevant to them and may have periods where locally cached data is temporarily out of sync with the "true" data in the Knowledge Repository.
This approach is the ideal/recommended way to use data gathered from the Knowledge Repository at scale as it is the most efficient for your operations.
At the server level, collect and cache all unique Merchant Profiles (as well as periodically check for new Merchant Profiles) to be able to retrieve up-to-date information from the Knowledge Repository without having to perform additional calls to our API.
Our Feature enables you to test card issued on UAT by trying to emulate production level data.
To test a card, please get the card details from API call, ensure that the node is funded and attempt transactions on the UI.
A Biller ID on the other hand is the _id
returned on API call.
Since all transactions are not originated through your platform, developers like to have higher level of control on transactions settling into user accounts. Especially withdrawals.
Transaction Decisioning is handled via a webhook request response flow. To enable an endpoint to receive a webhook when a Subnet withdrawal transaction is received, with TRANS|POST|JIT
scope. So something like this:
To make the most of Transaction Decisioning (JIT), you will need to build out the appropriate logic on the platform side (e.g. restrict by transaction type, merchant profile, MCC, or other logic). Please review and to find all the information we return.
If using Partial Approval, the response will need to also supply the partially approved transaction's total_amount
. If a transaction can be partially approved, you will see to.meta.partial_approval_allowed
set to True. Go to to learn more.
To be able to test Transaction Decisioning on UAT, you will need to be able to create fake subnet transactions. For card subnets, you can do that with . While for account number subnets, you can do that with API calls.
if required
Card networks charge merchants (e.g. a coffee shop or an online marketplace) an interchange fee for facilitating the transaction. Most of this fee is then given by the card networks to the card-issuer (Synapse). This is referred to as the Interchange Revenue and can be found in the response body of a card transaction under meta.revenues
(see: ). The Interchange Revenue is further totaled, split, and disbursed as explained below.
Mobile Wallets are digital wallets held on mobile devices that transact with merchants by turning Native Card Primary Account Numbers (PANs) into digital tokens (e.g. for use with Apple Pay, Google Pay, Samsung Pay, Fitbit Pay, etc.). Further, you can customize how the will be digitally represented on a mobile device.
can now also be added directly from your app to a user's mobile wallet with the click of a button through a process called "Instant Provisioning" (see ). This new feature allows users to quickly and efficiently integrate their cards with their Apple, Google, and/or Samsung digital wallets, with the added benefit of reducing both failed OCR error and manual text entry errors associated with standard manual card provisioning.
The SVG for the brand mark used on the card image. See for available brand marks. It is recommended to use the Mastercard Symbol.
You can currently submit your card information and mobile wallet assets during implementation to your Implementation Manager or later by .
Card networks give the user the option to dispute a transaction for alleged fraud, damaged merchandise, and similar reasons. To file a transaction dispute please use our API call.
When a transaction is , in most cases (except for Merchant Disputes) the end user is entitled to a Provisional Credit. Provisional Credit is a temporary credit extended to the end user equal to the amount disputed.
Both and require (in most cases) for the card issuer to immediately provide such credit to the card/account of consumer-type users if the investigation is not completed within 5 business days.
We will also send notice of the provisional credit directly to the user, via text message. This needs be sent within 2 business days, as required per Reg E. But we automate notices to the users for all disputes filed via our API call.
Dispute investigations can take up to 90 days to reach resolution once submitted to the card network. We receive status updates from the card network during the investigation period. These statuses can be viewed through the dispute_meta
field on the dashboard or by making a API Call.
Should rescinding provisional credit result in an overdrawn account, you may hold the user liable for this amount. Please keep in mind that you will be ultimately responsible for any outstanding balances and negative balances are reconciled on a regular cadence (see: ).
These are the various statuses a dispute might have throughout the lifecycle of the dispute case. Go to and to learn more.
Since Pre-Arbs are manual, please email to create a Pre-Arb dispute ticket.
Enrichment service is our data repository and intelligence engine that classifies, categorizes, and analyzes user transactions. Examples of data provided include the relevant business entity, location, and the category of the expense. (See: ).
Please open a support ticket to and we will do our best to update it with the correct information as quickly as possible.
Each time you receive the transaction stream (see: and ), you extract the relevant Entity ID, Facilitator ID, and/or Location ID to then perform the subsequent API call(s) necessary to retrieve the relevant Merchant Profiles associated with the ID(s) (See: ).
Age Account
Days
Over 30 days
Three (3) Business Days
30 days or below
Fifteen (15) Days
Key
Type
Description
category
string
General category of the expense (e.g. "cash", "entertainment", "food&drink", "health", "services", "shopping", "transfer", "transportation", "travel"). Simplified / aggregated based on internal logic (similar to Merchant Category Codes / MCCs used by card processors). Please note that category is assigned according to the transaction rather than Merchant Profile (i.e. multiple transactions with different categories can be matched to the same Merchant Profile).
entity_id
string
Entity ID (i.e. the unique identifier that maps to the business entity / Corporate Entity Profile associated with the transaction).
facilitator_id
string
Facilitator ID (i.e. the unique identifier that maps to the facilitator / Facilitator Profile associated with transaction).
location_id
string
Location ID (i.e. the unique identifier that maps to the specific retail location / Location Profile associated with the transaction)
status
string
The status for the merchant information in the Knowledge Repository. The value can either be SETTLED
or PENDING
.
Merchant Profile
Details
Examples
Corporate Entity Profile
Profile for a business or corporate entity (e.g. a restaurant or store chain).
McDonald's Walmart 7-Eleven
Location Profile
Profile for a specific retail location (e.g. a singular business location or a franchise location).
Singular Business Location Example "Sunshine Convenience Market" Franchise Location Example "MCDONALD S F1063 LOS ANGELES CA 90016"
Facilitator Profile
Profile for a payment facilitator, hotel/discount travel facilitator, or other type of facilitator for the transaction. Please note that payment facilitators are in control of transaction formatting and use their own formats that may restrict our Enrichment service's ability to identify a final merchant for a transaction (e.g. by prepending an abbreviated code, followed by an asterisk, followed by a short transaction description that may be truncated such that we are unable to parse a merchant name). We provide facilitator information as part of our effort to transparently provide as much information as possible for each transaction.
Payment Facilitator Examples PayPal Apple Pay Google Pay Venmo Square Cash App Hotel / Discount Travel Facilitator HotelTonight Expedia Other Facilitators Kickstarter Indiegogo ActBlue WinRed
Category
Examples
cash
cash disbursements (e.g. manual and ATMs)
entertainment
movies, amusements parks, shows, exhibits, digital subscriptions
food&drink
restaurants, fast food, grocery, alcohol & bars, delivery service facilitators (e.g. DoorDash, UberEats, GrubHub, etc.)
health
medical care, pharmacies, doctors, health practitioners
services
other services not classified as "entertainment," "health," or "transportation" (e.g. utilities, insurance, education, laundry, beauty shops, repair shops, etc.)
shopping
clothing retailers, electronics retailers, online merchants
transfer
person-to-person (P2P) money transfers (Cash App, Venmo, Paypal, Apple Pay, etc.)
transportation
public transportation, ridesharing (e.g. Uber/Lyft), taxi, parking, service stations, auto supplies, fuel
travel
car rentals, airlines, hotels, travel agencies, cruises, hotel/discount travel facilitators (e.g. HotelTonight, Expedia, etc.)
preview_only=true
Display Account Disclosure
Display the Agreement PDF to User
Collect Affirmative Consent from the user
Display Node Details
Wait for the user to be approved SEND-AND-RECEIVE
preview_only=true
Display Account Disclosure
Display the Agreement PDF to User
Collect Affirmative Consent from the user
Run Credit Decisioning
Display Node Details
Display Cash Advance terms
Create the Repayment Node
Create the Disbursement Node
Display the Promise to Repay Disclosure
Required Language: “The bank services are provided by Synapse's partner banks, Members FDIC. By accepting the terms of this account on <Insert Platform Name>, you agree to <Platform>'s Promise to Pay Agreement.”
Display the agreement PDF
Display the Cash Advance Details:
Amount
Repayment Account
Disbursement Account
Repayment Date
Collect Affirmative Consent from the user
Notes:
Platforms can charge a fee for cash advance
Platforms cannot charge APR for Cash Advance
Cash Advance products are heavily scrutinized by regulators
Notes:
After User creation, all API calls will require an oauth token
Protecting fingerprints, or marking them as “protected”, not only prevents their eventual expiration, it also ensures the fingerprint is not popped off the list in the event that the user has exceeded the overall limit.
If protecting an existing fingerprint, ensure that is inactive (is_active=false)
If the fingerprint is active, deactivate it by performing the OAuth call with is_active=false in the payload
POST /v3.1/oauth/{{user_id}}
POST /v3.1/oauth/{{user_id}} with the following payload parameters
is_active = true
is_protected = true
refresh_token
scope
User onboarding is the culmination of your marketing campaign and the beginning of your relationship with the user. It's important to provide a smooth onboarding experience in order to maximize your conversion rate.
Long onboarding times drastically increase abandonment
Users are more likely to provide additional KYC information in order to activate their account rather than create their account
Consumers are very sensitive to KYC friction
Business users are familiar and tolerant of KYB friction
Display the TOS and Privacy Agreements
Collect basic user information
Phone
Address
Name
Collect the minimum documentation required from users. This is described in your Spec Sheet
US Residents: SSN
International Users: Physical Documents
Display the TOS and Privacy Agreements
Collect Login and Base Business Details
Name
Phone
Incorporation Date
Address
Collect Business Documents
Incorporation Documents
Relevant Licenses
Owners/UBOs/Executives (Same as Consumer Documents)
Collect Executives & UBO Information
Default:
Phone
Role
Ownership Percentage
Address
Name
US Users:
SSN
International Users:
Physical Documents
Video Authorization
Notes:
Onboarding as a business user is a time commitment. In order to minimize dropoff during the onboarding process, we recommend giving users access to the application before they have finished supplying all of the required KYC & KYB.
Users must be aware that their account is not active and that they must be verified before they can start transacting.
Business Onboarding can take time in order to verify all of the required information
(required for Approved and Rejected Loans)
Required Language: "Synapse is our backend software provider, and partners with financial institutions to provide FDIC insurance. Synapse’s API, and their relationship with financial institutions, enables us to offer banking services and products. By agreeing to <insert platform name>’s TOS and Privacy Policy, you also agree to Synapse’s terms and policies below: "
(required for consumer programs for US residents)
Required Language: "Synapse is our backend software provider, and partners with financial institutions to provide FDIC insurance. Synapse’s API, and their relationship with financial institutions, enables us to offer banking services and products. By agreeing to <insert platform name>’s TOS and Privacy Policy, you also agree to Synapse’s terms and policies below: "