Getting Started
Welcome to the Routefusion API docs!
For Test API access please use the below credentials. Note these are public credentials.
Test API KEYS
Client ID: 0C270CB98CFD4DE4BBD45BA179B67307F263DA92C66572A2A8D043E55FC826B5
Secret Key: 723Ae7657b97722DA2D4a964EB1D137d21B4A81e88AF368F1e990B8b2F5727C0
BASE URL: sandbox.api.routefusion.co
The Routefusion API gives you access to send money from bank to bank in 130+ countries
Routefusion on github: https://github.com/Routefusion/routefusion-node
Routefusion has access to 130+ countries, if you need payouts to a country that is not listed please email engineering@routefusion.co and we can get you up and running asap.
Please note you can also hit our currency coverage endpoint to see our available currencies. currency coverage endpoint
You can also use our Postman collection here https://documenter.getpostman.com/view/4019635/RVtxKsA1
Install
Using npm:
$ npm install routefusion-sdk --save
You can install the routefusion SDK with npm. If you are using node, we recommend you use the SDK for your integration with routefusion.
We will be releasing SDKs in additional languages soon.
Authentication
const rf = require('routefusion-sdk').Instance({
RF_CLIENT_ID: '65B44076F114B95EC6B717720994E813E435B7048E44F1C52898ED852D0D2D07',
RF_SECRET: '108F20D91DDA8446d674CF2E20d5B632FdaF0B605eEc4d2f67484b9E2ED89512',
RF_BASE_URL: "https://sandbox.api.routefusion.co" // will default to sandbox
});
or, set environment variables
export RF_CLIENT_ID=65B44076F114B95EC6B717720994E813E435B7048E44F1C52898ED852D0D2D07
export RF_SECRET_KEY=108F20D91DDA8446d674CF2E20d5B632FdaF0B605eEc4d2f67484b9E2ED89512
export RF_BASE_URL=https://sandbox.api.routefusion.co # not needed for sandbox
then, no need for dragging around that config object
const rf = require('routefusion-sdk').Instance();
or, create a credentials file (our favorite)
create a file at `~/.rf/credentials`
[default]
client_id=65B44076F114B95EC6B717720994E813E435B7048E44F1C52898ED852D0D2D07
secret=108F20D91DDA8446d674CF2E20d5B632FdaF0B605eEc4d2f67484b9E2ED89512
[Rich]
client_id=65B44076F114B95EC6B717720994E813E435B7048E44F1C52898ED852D0D2D07
secret=108F20D91DDA8446d674CF2E20d5B632FdaF0B605eEc4d2f67484b9E2ED89512
[Paul]
client_id=65B44076F114B95EC6B717720994E813E435B7048E44F1C52898ED852D0D2D07
secret=108F20D91DDA8446d674CF2E20d5B632FdaF0B605eEc4d2f67484b9E2ED89512
then export your preferred profile, if no profile is set the SDK will use [default]
export RF_PROFILE=Rich
then it's as easy as:
const rf = require('routefusion-sdk').Instance();
It is recommended that you use the SDK for authentication. If using the SDK you either need to set environment variables, pass in a config, or set a .rf_profile in your home directory.
Routefusion uses HMAC to authenticate API requests.
You must send your client-id
in the headers along with a base64 signature
. Create your request signature
by signing the request body for POST requests, or signing the path for GET requests with your secret key.
If you plan to use the SDK set your API key / secret pair as environment variables, or create a credentials file where you can manage all of your keys in one place. The location of your credentials file should be
~/.rf/credentials
for unix systems and C:\%USERPROFILE%\.rf\credentials
for windows systems.
The credentials priority is:
- local instance configuration
- environment variables
- credentials file
Note: You should NEVER send your secret key in an API request.
Users
There are two types of users. A master user and a normal user.
A master user can create other users, and manage those users.
A normal user only has access to their own attributes.
By default every new user that is signed up is a normal user. If you would like master user capabilities please email us at engineering@routefusion.co.
User Account Creation
This is the flow when a user is created on our system. This will occur for a normal user and a master user. Inadvertently every user a master creates will go through this same process.
Get user
const rf = require('routefusion-sdk').Instance();
rf.getUser()
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"uuid": "c8d73658-9acc-4687-a4a4-cc6d195aae34",
"first_name": "mike",
"last_name": "jones",
"email": "mike@jones.com",
"phone_number": null,
"country": null,
"street_address": "600 Congress Ave."
"city": "Austin",
"state_province": "TX",
"postal_code": "78745",
"status_history": null,
"status": "verified",
"verified": true,
"type": null,
"verification_submitted": false,
"company_name": null,
"created_at": "2018-12-13T12:51:51.107Z",
"updated_at": "2019-05-08T04:40:04.006Z",
"master_user": false,
"master_user_uuid": null,
"currency": null,
"identification_type": null,
"identification_value": null,
"default_funding_method": "push"
}
This endpoint retrieves information about your user profile.
HTTP Request
GET https://api.routefusion.co/v1/users/me
URL Parameters
None
Update user
const rf = require('routefusion-sdk').Instance();
let body = {
"first_name": "sammy slick toe smith"
}
rf.updateUser(body)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"uuid": "c8d73658-9acc-4687-a4a4-cc6d195aae34",
"first_name": "sammy slick toe smith",
"last_name": "jones",
"email": "mike@jones.com",
"phone_number": null,
"country": null,
"street_address": "600 Congress Ave."
"city": "Austin",
"state_province": "TX",
"postal_code": "78745",
"status_history": [
{
"status": "created",
"created_at": "2018-04-04T16:42:23.191Z"
},
{
"status": "verified",
"created_at": "2018-04-10T17:32:50.216Z"
}
],
"status": "verified",
"verified": true,
"type": "business",
"verification_submitted": false,
"company_name": null,
"created_at": "2018-04-04T16:42:23.191Z",
"updated_at": "2018-04-10T17:32:50.216Z"
"master_user": true,
"master_user_uuid": null,
"default_funding_method": "push"
"currency": null,
"identification_type": null,
"identification_value": null
}
This endpoint updates information about your user profile.
HTTP Request
PUT https://api.routefusion.co/v1/users/me
Body
Column | Type |
---|---|
company_name | STRING |
password | STRING |
first_name | STRING |
last_name | STRING |
STRING | |
phone_number | STRING |
country | STRING |
state_province | STRING |
city | STRING |
street_address | STRING |
postal_code | STRING |
default_funding_method | STRING enumerable ['push', 'pull'] |
URL Parameters
None
MASTER Create user
const rf = require('routefusion-sdk').Instance();
let body = {
first_name: 'Rick',
last_name: 'James',
email: 'whoismike@jones.com',
country: 'US',
state_province: 'NY',
city: 'New York',
street_address: '1546 Madison Ave.',
postal_code: '10001',
currency: 'USD',
type: 'personal',
currency: 'USD',
default_funding_method: 'push'
};
rf.createUserByUUid(body)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"uuid": "60642929-9b29-4713-ab23-10da2db8a6a6",
"first_name": "Rick",
"last_name": "James",
"email": "whoismike@jones.com",
"phone_number": null,
"type": "personal",
"verification_submitted": false,
"company_name": null,
"created_at": "2020-04-26T21:54:06.806Z",
"updated_at": null,
"country": "US",
"state_province": "NY",
"street_address": "1546 Madison Ave.",
"city": "New York",
"postal_code": "10001",
"status_history": [
{
"status": "created",
"created_at": "2020-04-26T21:54:06.802Z"
}
],
"status": "created",
"verified": false,
"default_funding_method": 'push',
"currency": "USD",
"identification_type": null,
"identification_value": null
}
This endpoint creates a sub-user.
NOTE: If a currency is not provided, the currency will be assumed by the system as the national currency of the country provided.
NOTE: default_funding_method
will default to push. Push means that YOU or YOUR USER will push funds to a Routefusion escrow account.
If you intend to use Routefusion's ACH pull feature you must set "default_funding_method": "pull"
in your payload, and then create the subsequent account (this will be the routing number and account number) in the Accounts Endpoint.
Transfers initiated by this user will then be funded by automatically initiating an ACH transfer from the User's bank account to the Escrow account.
NOTE: If you do an ACH pull for the funding method, Businesses have a 3 day clawback period where they can claim they did not initiate a transfer, and individuals have a 6+ month clawback period. Lots of fraud can happen here, it is very important that you understand all the risks.
Please make sure you understand the flow of funds for your integration. The Routefusion team is happy to help you with your flow of funds, and find the experience that is right for you customers and product.
HTTP Request
POST https://api.routefusion.co/v1/users/me/users
Body
Column | Type | Required |
---|---|---|
type | STRING | optional, must be 'personal' OR 'business' |
first_name | STRING | required if type is personal |
last_name | STRING | required if type is personal |
company_name | STRING | required if type is company |
STRING | required | |
street_address | STRING | optional |
city | STRING | optional |
state_province | STRING | optional |
country | STRING | required, 2 character country ISO code |
postal_code | STRING | optional |
phone_number | STRING | optional |
currency | STRING | optional, will be populated with user's country origin currency if not provided |
default_funding_method | STRING | optional, must be 'push', or 'pull' and will default to 'push' |
URL Parameters
None
MASTER Get user
const rf = require('routefusion-sdk').Instance();
rf.getUserByUUid(UUID)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"uuid": "07d15675-bc7a-4f5b-805c-04961af401f2",
"first_name": "Mike",
"last_name": "Jones",
"company_name": "Who Mike Jones Co.",
"email": "mikejones@who.com",
"phone_number": "2813308004",
"country": 'US',
"state_province": "TX",
"city": "Austin",
"street_address": "600 Congress Ave.",
"postal_code": "78745",
"status_history": [
{
"status": "created",
"created_at": "2018-04-04T16:42:23.191Z"
},
{
"status": "verified",
"created_at": "2018-04-10T17:32:50.216Z"
}
],
"status": "verified",
"verified": true,
"admin": false,
"type": "personal",
"verification_submitted": true,
"default_funding_method": "push",
"currency": "USD",
"identification_type": null,
"identification_value": null,
"created_at": "2018-04-04T16:42:23.191Z",
"updated_at": "2018-04-10T17:32:50.216Z"
}
This endpoint retrieves information about your users user profile.
HTTP Request
GET https://api.routefusion.co/v1/users/me/users/<SUB_USER_UUID>
URL Parameters
Parameter | Description |
---|---|
SUB_USER_UUID | your sub user's uuid |
MASTER Update user
const rf = require('routefusion-sdk').Instance();
let body = {
"first_name": "sammy slick toe smith"
}
rf.updateUserByUUid(YOUR_USERS_ROUTEFUSION_UUID, body)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"uuid": "07d15675-bc7a-4f5b-805c-04961af401f2",
"first_name": "sammy slick toe smith",
"last_name": "Jones",
"company_name": "Who Mike Jones Co.",
"email": "mikejones@who.com",
"phone_number": "2813308004",
"country": null,
"state_province": "TX",
"city": "Austin",
"street_address": "600 Congress Av",
"postal_code": "78745",
"status_history": [
{
"status": "created",
"created_at": "2018-04-04T16:42:23.191Z"
}
],
"status": "created",
"verified": true,
"admin": false,
"type": "personal",
"verification_submitted": false,
"default_funding_method": "push",
"currency": "USD",
"identification_type": null,
"identification_value": null
"created_at": "2018-04-04T16:42:23.191Z",
"updated_at": "2018-04-10T17:32:50.216Z"
}
This endpoint updates information about your user profile.
HTTP Request
PUT https://api.routefusion.co/v1/users/me/users/<SUB_USER_UUID>
Body
Column | Type |
---|---|
first_name | STRING |
last_name | STRING |
company_name | STRING |
STRING | |
country | STRING |
postal_code | STRING |
phone_number | STRING |
city | STRING |
street_address | STRING |
default_funding_method | STRING |
URL Parameters
Parameter | Description |
---|---|
SUB_USER_UUID | your sub user's uuid |
MASTER Index users
const rf = require('routefusion-sdk').Instance();
rf.getUsers()
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
[
{
"uuid": "07d15675-bc7a-4f5b-805c-04961af401f2",
"first_name": "Mike",
"last_name": "Jones",
"company_name": "Who Mike Jones Co.",
"email": "mikejones@who.com",
"phone_number": "2813308004",
"country": null,
"city": "Austin",
"street_address": "600 Congress Av",
"postal_code": "78745",
"status_history": [
{
"status": "created",
"created_at": "2018-04-04T16:42:23.191Z"
},
{
"status": "verified",
"created_at": "2018-04-10T17:32:50.216Z"
}
],
"status": "verified",
"verified": true,
"admin": false,
"type": "business",
"verification_submitted": true,
"default_funding_method": "push",
"currency": "USD",
"identification_type": null,
"identification_value": null,
"created_at": "2018-04-04T16:42:23.191Z",
"updated_at": "2018-04-10T17:32:50.216Z"
},
{
"uuid": "07d15675-bc7a-4f5b-805c-04961af401f2",,
"first_name": "Mike2",
"last_name": "Jones2",
"company_name": "Mike Who Jones Co.",
"email": "mikejones2@who.com",
"phone_number": "2813308004",
"country": null,
"city": "Austin",
"street_address": "600 Congress Av",
"postal_code": "78745",
"status_history": [
{
"status": "created",
"created_at": "2018-04-04T16:42:23.191Z"
}
],
"status": "created",
"verified": false,
"admin": false,
"type": "business",
"verification_submitted": true,
"default_funding_method": "push",
"currency": "USD",
"identification_type": null,
"identification_value": null,
"created_at": "2018-04-04T16:42:23.191Z",
"updated_at": "2018-04-10T17:32:50.216Z"
}
]
This endpoint retrieves all the info on your users.
HTTP Request
GET https://api.routefusion.co/v1/users/me/users
Accounts
The accounts API is intended for workflows which utilize a 'pull' funding method, see MASTER Create Users for how to set up your user. The account data will allow Routefusion to complete the automated payment workflow.
NOTE: Only the most recent created account will be applicable for a user. i.e. all past accounts will be deactivated when you create a new account.
NOTE: Please store the uuid in the response if you wish to use the account data later on.
Create User account
const rf = require('routefusion-sdk').Instance();
let body = {
name_on_account: 'Bob TheBuilder',
account_number: '123',
routing_number: '1234',
currency: 'USD',
bank_country: 'US',
bank_name: "Citibank",
bank_address: "5252 Madison Ave."
};
rf.createUserAccount(body)
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
json { "uuid": "d48cb8b3-8945-4748-9bed-kd3d9vc15m" }
HTTP Request
POST https://api.routefusion.co/v1/users/<SUB_USER_UUID>/accounts
Body
Column | Description | Required |
---|---|---|
name_on_account | the name on the bank account | required |
account_number | bank account number | required |
routing_number | US bank ABA routing number (e.g. the routing number on your checkbook) | required |
currency | bank account's currency | required |
bank_country | the country of the bank's physical location | required |
bank_address | bank's physical address | optional |
bank_name | bank's name | optional |
Get User accounts byUuid
const rf = require('routefusion-sdk').Instance();
const userUuid = 'yourUsersUuid';
const accountUuid = 'b45b64de-c620-4f18-bfad-5bdefcb522c1';
rf.getUserAccountByUuid(userUuid, accountUuid)
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
{
"id": 6,
"uuid": "b45b64de-c620-4f18-bfad-5bdefcb522c1",
"user_id": 1,
"account_number": "123",
"routing_number": "123",
"bank_name": "Citibank",
"bank_address": "5252 Madison Ave.",
"created_at": "2018-12-14T00:41:38.661Z",
"name_on_account": "bob theBuilder",
"currency": "USD",
"primary_account": true,
"bank_country": "US"
}
HTTP Request
GET https://api.routefusion.co/v1/users/<SUB_USER_UUID>/accounts/<ACCOUNT_UUID>
Query Parameters
Parameter | Description | Example |
---|---|---|
SUB_USER_UUID | uuid of your user | see Users |
ACCOUNT_UUID | uuid of the user's account | see code example |
Beneficiaries
Users can have many beneficiaries.
Beneficiaries are who you plan on sending money to. They could be a supplier, an employee, a contractor, a marketplace seller, etc. Each beneficiary has core fields that are required, but will have additional separate fields required depending on what country the beneficiary is in. If you would like to view the requirements in JSON format you can find beneficiary requirements for each country at https://api.routefusion.co/currencies
This is the typical flow of of a beneficiary creation
Get all beneficiaries
const rf = require('routefusion-sdk').Instance();
rf.getBenefiaries()
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
[
{
"id": 414,
"uuid": "b384af3b-3e61-476a-aee6-1c44cb42a605",
"user_id": 2,
"company_name": "beneficiaryCompany",
"first_name_on_account": "companyOwnerFirstName",
"last_name_on_account": "companyOwnerLastName",
"type": "business",
"bank_name": "Citibank",
"branch_name": null,
"bank_city": "New York City",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "2315345432",
"routing_number": "113193532",
"clabe": null,
"tax_number": null,
"email": "company@email.com",
"phone_number": null,
"country": "US",
"city": "beneficiaryCity",
"bank_state_province": "New York",
"verified": true,
"created_at": "2019-05-08T18:16:30.614Z",
"updated_at": "2019-05-08T18:16:33.0Z",
"currency": "USD",
"cpfcnpj": null,
"swift_bic": "CITIUS33",
"bank_address1": "5252 Madison Ave.",
"bank_address2": null,
"bank_country": "US",
"bank_postal_code": "00000",
"address1": "40 W 23rd St.",
"address2": null,
"state_province": "New York",
"postal_code": "00000",
"bsb_number": null,
"status_history": [{"status": "pending", "created_at": "2019-05-08T18:16:30.614Z"}, {"status": "verified", "created_at": "2019-05-08T18:16:33.0Z"}],
"status": "verified"
},
{
...
]
This endpoint retrieves all of your users beneficiaries.
HTTP Request
GET https://api.routefusion.co/v1/beneficiaries
Query Parameters
Parameter | Description | Example |
---|---|---|
limit | query limit, must be an integer | 100 |
offset | query offset, must be an integer | 50 |
order_by | query order by, defaults to id, must be an object property | first_name_on_account |
order | query order, defaults to 'asc', must be 'asc' or 'desc' | 'desc' |
NOTE: requesting all beneficiaries will be deprecated on May 31st, 2020. After May 31st, 2020, calls without pagination query parameters will have a default limit of 300.
Get beneficiary
const rf = require('routefusion-sdk').Instance();
rf.getBeneficiary(<BENEFICIARY_ID>)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"id": 414,
"uuid": "b384af3b-3e61-476a-aee6-1c44cb42a605",
"user_id": 2,
"company_name": "beneficiaryCompany",
"first_name_on_account": "companyOwnerFirstName",
"last_name_on_account": "companyOwnerLastName",
"type": "business",
"bank_name": "Citibank",
"branch_name": null,
"bank_city": "New York City",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "2315345432",
"routing_number": "113193532",
"clabe": null,
"tax_number": null,
"email": "company@email.com",
"phone_number": null,
"country": "US",
"city": "beneficiaryCity",
"bank_state_province": "New York",
"verified": false,
"created_at": "2019-05-08T18:16:30.614Z",
"updated_at": null,
"currency": "USD",
"cpfcnpj": null,
"swift_bic": "CITIUS33",
"bank_address1": "5252 Madison Ave.",
"bank_address2": null,
"bank_country": "US",
"bank_postal_code": "00000",
"address1": "beneficiaryAddress",
"address2": null,
"state_province": "beneficiaryStateOrProvince",
"postal_code": "00000",
"bsb_number": null
}
This endpoint retrieves information about your beneficiary.
HTTP Request
GET https://api.routefusion.co/v1/beneficiaries/<BENEFICIARY_ID>
URL Parameters
Parameter | Description |
---|---|
BENEFICIARY_ID | your beneficiary_id |
Create beneficiary
const rf = require('routefusion-sdk').Instance();
let beneficiaryData = {
company_name: "beneficiaryCompanyName",
first_name_on_account: "companyOwnerFirstName",
last_name_on_account: "companyOwnerLastName",
type: "business",
currency: "USD",
bank_name: "Citibank",
branch_name: "",
bank_address1: "5252 Madison Ave."
bank_city: "New York City",
bank_state_province: "New York",
bank_postal_code: "00000",
bank_country: "US", // 2 letter code
swift_bic: "CITIUS33", // 8 or 11 character code
account_type: "business",
account_number: "2315345432",
routing_number: "113193532",
email: "company@email.com",
phone_number: "",
address1: "beneficiaryAddress",
city: "beneficiaryCity",
state_province: "beneficiaryStateOrProvince",
postal_code: "00000",
country: "US" // 2 letter code
};
rf.createBenefiary(beneficiaryData)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"id": 414,
"uuid": "b384af3b-3e61-476a-aee6-1c44cb42a605",
"user_id": 2,
"company_name": "beneficiaryCompany",
"first_name_on_account": "companyOwnerFirstName",
"last_name_on_account": "companyOwnerLastName",
"type": "business",
"bank_name": "Citibank",
"branch_name": null,
"bank_city": "New York City",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "2315345432",
"routing_number": "113193532",
"clabe": null,
"tax_number": null,
"email": "company@email.com",
"phone_number": null,
"country": "US",
"city": "beneficiaryCity",
"bank_state_province": "New York",
"verified": false,
"created_at": "2019-05-08T18:16:30.614Z",
"updated_at": null,
"currency": "USD",
"cpfcnpj": null,
"swift_bic": "CITIUS33",
"bank_address1": "5252 Madison Ave.",
"bank_address2": null,
"bank_country": "US",
"bank_postal_code": "00000",
"address1": "beneficiaryAddress",
"address2": null,
"state_province": "beneficiaryStateOrProvince",
"postal_code": "00000",
"bsb_number": null
}
This endpoint creates a beneficiary.
HTTP Request
POST https://api.routefusion.co/v1/beneficiaries
URL Parameters
None
Body
Below is the base that is required for creating a beneficiary. Additional fields for countries will be listed below.
Please view all of our currency coverage and required fields here Routefusion Currency List & Beneficiary Requirements
If you would like to gather all of the bank information based off of a user provided SWIFT code, please use this endpoint Routefusion bank Lookup
Column | Type | Required | Notes |
---|---|---|---|
type | STRING | required | PERSONAL or BUSINESS |
first_name_on_account | STRING | conditionally | required if the type is PERSONAL. Once beneficiary is verified this field cannot be changed. |
last_name_on_account | STRING | conditionally | required if the type is PERSONAL. Once beneficiary is verified this field cannot be changed. |
company_name | STRING | conditionally | required if the type is BUSINESS |
bank_country | STRING | required | |
bank_name | STRING | required | |
account_number | STRING | required | bank account number of the beneficiary (IBAN, Clabe, Account Number). Once beneficiary is verified this field cannot be changed. |
bank_code | STRING | optional | bank routing code (CNAP, IFSC) |
currency | STRING | required | |
address1 | STRING | required | |
country | STRING | required | |
city | STRING | required | |
postal_code | STRING | required | |
STRING | required |
Update beneficiary
const rf = require('routefusion-sdk').Instance();
let beneficiaryId = 1;
let body = {
"first_name": "Johnny Two Step"
};
rf.updateBeneficiary(beneficiaryId, body)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"id": 414,
"uuid": "b384af3b-3e61-476a-aee6-1c44cb42a605",
"user_id": 2,
"company_name": "test beneficiary company",
"first_name_on_account": "Johnny Two Step",
"last_name_on_account": "that",
"type": "business",
"bank_name": "Citibank",
"branch_name": null,
"bank_city": "New York City",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "2315345432",
"routing_number": "113193532",
"clabe": null,
"tax_number": null,
"email": "company@email.com",
"phone_number": null,
"country": "US",
"city": "New York City",
"bank_state_province": "New York",
"verified": false,
"created_at": "2019-05-08T18:16:30.614Z",
"updated_at": null,
"currency": "USD",
"cpfcnpj": null,
"swift_bic": "CITINY73",
"bank_address1": null,
"bank_address2": null,
"bank_country": "US",
"bank_postal_code": "00000",
"address1": "5252 Madison Ave",
"address2": null,
"state_province": "NY",
"postal_code": "00000",
"bsb_number": null
}
This endpoint updates information about one of your beneficiaries.
HTTP Request
PUT https://api.routefusion.co/v1/beneficiaries/<BENEFICIARY_ID>
URL Parameters
Parameter | Description |
---|---|
BENEFICIARY_ID | your beneficiary_id |
Body
Note: Once beneficiary is verified first_name_on_account
, last_name_on_account
, and account_number
cannot be changed.
Column | Type |
---|---|
company_name | STRING |
first_name_on_account | STRING |
last_name_on_account | STRING |
STRING | |
phone_number | STRING |
address1 | STRING |
address2 | STRING |
city | STRING |
state_province | STRING |
country | STRING |
type | STRING |
account_type | STRING |
account_number | STRING |
routing_number | STRING |
clabe | STRING |
tax_number | STRING |
currency | STRING |
cpfcnpj | STRING |
swift_bic | STRING |
bank_name | STRING |
branch_name | STRING |
bank_city | STRING |
bank_code | STRING |
branch_code | STRING |
bank_address1 | STRING |
bank_address2 | STRING |
bank_state_province | STRING |
bank_country | STRING |
bank_postal_code | STRING |
bsb_number | STRING |
MASTER Get sub-user beneficiaries
Response JSON:
[
{
"id": 414,
"uuid": "b384af3b-3e61-476a-aee6-1c44cb42a605",
"user_id": 2,
"company_name": "beneficiaryCompany",
"first_name_on_account": "companyOwnerFirstName",
"last_name_on_account": "companyOwnerLastName",
"type": "business",
"bank_name": "Citibank",
"branch_name": null,
"bank_city": "New York City",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "2315345432",
"routing_number": "113193532",
"clabe": null,
"tax_number": null,
"email": "company@email.com",
"phone_number": null,
"country": "US",
"city": "beneficiaryCity",
"bank_state_province": "New York",
"verified": false,
"created_at": "2019-05-08T18:16:30.614Z",
"updated_at": null,
"currency": "USD",
"cpfcnpj": null,
"swift_bic": "CITIUS33",
"bank_address1": "5252 Madison Ave.",
"bank_address2": null,
"bank_country": "US",
"bank_postal_code": "00000",
"address1": "beneficiaryAddress",
"address2": null,
"state_province": "beneficiaryStateOrProvince",
"postal_code": "00000",
"bsb_number": null
},
{
...
]
This endpoint retrieves all of your sub-user's beneficiaries.
HTTP Request
GET https://api.routefusion.co/v1/users/<SUB_USER_UUID>/beneficiaries
URL Parameters
Parameter | Description |
---|---|
SUB_USER_UUID | your sub-user's uuid |
MASTER Get sub-user beneficiary
Response JSON:
{
"id": 414,
"uuid": "b384af3b-3e61-476a-aee6-1c44cb42a605",
"user_id": 2,
"company_name": "beneficiaryCompany",
"first_name_on_account": "companyOwnerFirstName",
"last_name_on_account": "companyOwnerLastName",
"type": "business",
"bank_name": "Citibank",
"branch_name": null,
"bank_city": "New York City",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "2315345432",
"routing_number": "113193532",
"clabe": null,
"tax_number": null,
"email": "company@email.com",
"phone_number": null,
"country": "US",
"city": "beneficiaryCity",
"bank_state_province": "New York",
"verified": false,
"created_at": "2019-05-08T18:16:30.614Z",
"updated_at": null,
"currency": "USD",
"cpfcnpj": null,
"swift_bic": "CITIUS33",
"bank_address1": "5252 Madison Ave.",
"bank_address2": null,
"bank_country": "US",
"bank_postal_code": "00000",
"address1": "beneficiaryAddress",
"address2": null,
"state_province": "beneficiaryStateOrProvince",
"postal_code": "00000",
"bsb_number": null
}
This endpoint retrieves information about your sub-user's beneficiary.
HTTP Request
GET https://api.routefusion.co/v1/users/<SUB_USER_UUID>/beneficiaries/<BENEFICIARY_ID>
URL Parameters
Parameter | Description |
---|---|
SUB_USER_UUID | your sub-user's uuid |
BENEFICIARY_ID | your beneficiary_id |
MASTER Create sub-user beneficiary
Response JSON:
{
"id": 414,
"uuid": "b384af3b-3e61-476a-aee6-1c44cb42a605",
"user_id": 2,
"company_name": "beneficiaryCompany",
"first_name_on_account": "companyOwnerFirstName",
"last_name_on_account": "companyOwnerLastName",
"type": "business",
"bank_name": "Citibank",
"branch_name": null,
"bank_city": "New York City",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "2315345432",
"routing_number": "113193532",
"clabe": null,
"tax_number": null,
"email": "company@email.com",
"phone_number": null,
"country": "US",
"city": "beneficiaryCity",
"bank_state_province": "New York",
"verified": false,
"created_at": "2019-05-08T18:16:30.614Z",
"updated_at": null,
"currency": "USD",
"cpfcnpj": null,
"swift_bic": "CITIUS33",
"bank_address1": "5252 Madison Ave.",
"bank_address2": null,
"bank_country": "US",
"bank_postal_code": "00000",
"address1": "beneficiaryAddress",
"address2": null,
"state_province": "beneficiaryStateOrProvince",
"postal_code": "00000",
"bsb_number": null
}
This endpoint creates a beneficiary on behalf of your sub-user.
HTTP Request
POST https://api.routefusion.co/v1/users/<SUB_USER_UUID>/beneficiaries
URL Parameters
Parameter | Description |
---|---|
SUB_USER_UUID | your sub-user's uuid |
MASTER Update sub-user beneficiary
Response JSON:
{
"id": 414,
"uuid": "b384af3b-3e61-476a-aee6-1c44cb42a605",
"user_id": 2,
"company_name": "test beneficiary company",
"first_name_on_account": "Johnny Two Step",
"last_name_on_account": "that",
"type": "business",
"bank_name": "Citibank",
"branch_name": null,
"bank_city": "New York City",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "2315345432",
"routing_number": "113193532",
"clabe": null,
"tax_number": null,
"email": "company@email.com",
"phone_number": null,
"country": "US",
"city": "New York City",
"bank_state_province": "New York",
"verified": false,
"created_at": "2019-05-08T18:16:30.614Z",
"updated_at": null,
"currency": "USD",
"cpfcnpj": null,
"swift_bic": "CITINY73",
"bank_address1": null,
"bank_address2": null,
"bank_country": "US",
"bank_postal_code": "00000",
"address1": "5252 Madison Ave",
"address2": null,
"state_province": "NY",
"postal_code": "00000",
"bsb_number": null
}
This endpoint updates information of a beneficiary on behalf of your sub-user.
HTTP Request
PUT https://api.routefusion.co/v1/users/<SUB_USER_UUID>/beneficiaries/<BENEFICIARY_ID>
URL Parameters
Parameter | Description |
---|---|
SUB_USER_UUID | your sub-user's uuid |
BENEFICIARY_ID | your beneficiary_id |
Transfers
Transfer Diagram
This is the typical flow of funds for a transfer or payment.
Transfer states
Name | Description |
---|---|
created | routefusion has successfully received instructions to make a payment |
processing | the liquidity provider has received the instruction and is processing the payment |
completed | the payment has been released to the beneficiary |
failed | the payment has failed to release to the beneficiary |
Note: A completed state does not mean the beneficiary has access to the funds at that moment. Routefusion has no control over when a beneficiary's bank clears funds to their account holders.
Create A Transfer
const rf = require('routefusion-sdk').Instance();
let payloadWithQuote = {
beneficiary_id: 1,
source_amount: 1000,
reference: "my reference", // not required
quote_uuid: "QUca9e8220-eccb-4957-8fd0-ab6623f83ff5"
};
let sourceAmountPayloadWithoutQuote = {
beneficiary_id: 1,
source_amount: 1000,
auto_complete: true
}
// if destination_amount is set, source_amount will be automatically calculated
let destinationAmountPayloadWithoutQuote = {
beneficiary_id: 1,
destination_amount: 25000,
auto_complete: true
}
rf.createTransfer(payloadWithQuote)
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
{
"user_id": 1,
"account_id": null,
"beneficiary_id": 5,
"source_amount": "500",
"exchange_rate": "20.2086715",
"reference": "my reference",
"purpose_of_payment": null,
"fee": "7.500",
"payment_method": "swift",
"currency_pairs": "USDMXN",
"created_at": "2018-12-11T18:27:02.038Z",
"updated_at": null,
"uuid": "37cba64b-1a22-4732-be22-04826da09405",
"state": "created",
"authorizing_ip": "63.65.120.22",
"transfer_states": [
{
"state": "created",
"created_at": "2018-12-11T18:27:01.876Z"
}
],
"source_currency": "USD",
"destination_amount": "9952.77",
"destination_currency": "MXN",
"deposit": false
}
This endpoint creates a payment. There are two ways to create a payment. You may opt to provide a quote or auto complete the payment.
HTTP Request
POST https://api.routefusion.co/v1/transfers
Body
Param | Type | Description | Required |
---|---|---|---|
beneficiary_id | INT | this is the id of the beneficiary you are sending money to | yes |
uuid | UUID v4 | this is the uuid of the transfer. You may provide your own uuid to ensure idempotency, otherwise, one will be generated for you | optional |
source_currency | STRING | used to resolve the desired currency and source of funds. Required if multiple accounts exist on the user | conditional |
source_amount | NUMBER | this is the amount you would like to send in USD. Required if destination_amount is not present | optional |
destination_amount | NUMBER | this is the amount of the beneficiary currency to purchase. Required if source_amount is not present | optional |
reference | STRING | this is the payment reference e.g. an invoice number, etc. | optional |
purpose_of_payment | STRING | this is the reason the payment is sent to the beneficiary | conditional |
quote_uuid | STRING | quote uuid, required if auto_complete is not present | optional |
auto_complete | BOOLEAN | allows for creating a payment without a quote | optional |
payment_method | STRING | method for the relevant transfer. One of "swift" or "local". Must be an available method for beneficiary, and only compatible with auto_complete | optional |
Get Index of Transfers
const rf = require('routefusion-sdk').Instance();
# rf.getTransfer(transferUUID)
# .then(resp => resp)
# .catch(err => err)
The above returns JSON structured like this:
{
"user_id": 1,
"account_id": null,
"beneficiary_id": 5,
"source_amount": "500",
"exchange_rate": "20.2086715",
"reference": "my reference"
"purpose_of_payment": null,
"fee": "7.500",
"payment_method": "swift",
"currency_pairs": "USDMXN",
"created_at": "2018-12-11T18:27:02.038Z",
"updated_at": null,
"uuid": "37cba64b-1a22-4732-be22-04826da09405",
"state": "created",
"authorizing_ip": "63.65.120.22",
"transfer_states": [
{
"state": "created",
"created_at": "2018-12-11T18:27:01.876Z"
}
],
"source_currency": "USD",
"destination_amount": "9952.77",
"destination_currency": "MXN",
"deposit": false
}
HTTP Request
GET https://api.routefusion.co/v1/transfers/<TRANSFER_UUID>
Parameters
Param | Type | Description | Required |
---|---|---|---|
TRANSFER_UUID | UUID | this is the uuid of the transfer | yes |
Get A Transfer
const rf = require('routefusion-sdk').Instance();
let transferUUID = <TRANSFER_UUID>
rf.getTransfer(transferUUID)
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
{
"user_id": 1,
"account_id": null,
"beneficiary_id": 5,
"source_amount": "500",
"exchange_rate": "20.2086715",
"reference": "my reference"
"purpose_of_payment": null,
"fee": "7.500",
"payment_method": "swift",
"currency_pairs": "USDMXN",
"created_at": "2018-12-11T18:27:02.038Z",
"updated_at": null,
"uuid": "37cba64b-1a22-4732-be22-04826da09405",
"state": "created",
"authorizing_ip": "63.65.120.22",
"transfer_states": [
{
"state": "created",
"created_at": "2018-12-11T18:27:01.876Z"
}
],
"source_currency": "USD",
"destination_amount": "9952.77",
"destination_currency": "MXN",
"deposit": false
}
HTTP Request
GET https://api.routefusion.co/v1/transfers/<TRANSFER_UUID>
Parameters
Param | Type | Description | Required |
---|---|---|---|
TRANSFER_UUID | UUID | this is the uuid of the transfer | yes |
Cancel Transfer
The master cancel transfer endpoint can be utilized to initiate a cancellation request. Hitting this endpoint does not automatically cancel the transfer. The Routefusion support team will make the cancellation, if applicable, and confirm with the account’s point of contact that made the request. Payments can be canceled after creation until settlement of the payment at which point the payment is paid out. Once the payment is paid out a cancellation is unable to be initiated. For clients that hold a balance in the applicable settlement currency, payments are paid out upon instruction creation. Cancellation requests can also be made to support@routefusion.co.
Sample JSON response:
{
"message": "transfer 1e5c3676-8d88-4680-85f3-3c109a5dfd1c cancelled"
}
HTTP Request
DELETE https://api.routefusion.co/v1/transfers/<TRANSFER_UUID>/cancel
Parameters
Param | Type | Description | Required |
---|---|---|---|
TRANSFER_UUID | UUID | this is the uuid of the transfer | yes |
Get Transfer Status
const rf = require('routefusion-sdk').Instance();
let transferUUID = <TRANSFER_UUID>
rf.getTransferStatus(transferUUID)
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
{
"state": "processing",
"created_at": "2018-12-03T20:35:31.017Z"
}
HTTP Request
GET https://api.routefusion.co/v1/transfers/<TRANSFER_UUID>/status
Parameters
Param | Type | Description | Required |
---|---|---|---|
TRANSFER_UUID | UUID | this is the uuid of the transfer | yes |
MASTER Create A Transfer
Response JSON:
{
"id": 107,
"user_id": 1,
"account_id": null,
"beneficiary_id": 5,
"source_amount": "500",
"exchange_rate": "20.2086715",
"reference": "my reference",
"purpose_of_payment": null,
"fee": "7.500",
"payment_method": "swift",
"currency_pairs": "USDMXN",
"created_at": "2018-12-11T18:27:02.038Z",
"updated_at": null,
"uuid": "37cba64b-1a22-4732-be22-04826da09405",
"state": "created",
"authorizing_ip": "63.65.120.22",
"transfer_states": [
{
"state": "created",
"created_at": "2018-12-11T18:27:01.876Z"
}
],
"source_currency": "USD",
"destination_amount": "9952.77",
"destination_currency": "MXN",
"deposit": false
}
This endpoint creates a payment on behalf of your sub-user. There are two ways to create a payment. You may opt to provide a quote or auto complete the payment.
HTTP Request
POST https://api.routefusion.co/v1/users/<SUB_USER_UUID>/transfers
URL Parameter
Param | Type | Description | Required |
---|---|---|---|
SUB_USER_UUID | UUID | this is the uuid of your sub-user | yes |
Body
Param | Type | Description | Required |
---|---|---|---|
beneficiary_id | INT | this is the id of the beneficiary you are sending money to | yes |
uuid | UUID v4 | this is the uuid of the transfer. You may provide your own uuid to ensure idempotency, otherwise, one will be generated for you | optional |
source_amount | NUMBER | this is the amount you would like to send in USD. Required if destination_amount is not present | optional |
destination_amount | NUMBER | this is the amount of the beneficiary currency to purchase. Required if source_amount is not present | optional |
reference | STRING | this is the payment reference e.g. an invoice number, etc. | optional |
purpose_of_payment | STRING | this is the reason the payment is sent to the beneficiary | conditional |
quote_uuid | STRING | quote uuid, required if auto_complete is not present | optional |
auto_complete | BOOLEAN | allows for creating a payment without a quote | optional |
payment_method | STRING | method for the relevant transfer. One of "swift" or "local". Must be an available method for beneficiary, and only compatible with auto_complete | optional |
MASTER Get A Transfer
The above returns JSON structured like this:
{
"id": 107,
"user_id": 1,
"account_id": null,
"beneficiary_id": 5,
"source_amount": "500",
"exchange_rate": "20.2086715",
"reference": "my reference",
"purpose_of_payment": null,
"fee": "7.500",
"payment_method": "swift",
"currency_pairs": "USDMXN",
"created_at": "2018-12-11T18:27:02.038Z",
"updated_at": null,
"uuid": "37cba64b-1a22-4732-be22-04826da09405",
"state": "created",
"authorizing_ip": "63.65.120.22",
"transfer_states": [
{
"state": "created",
"created_at": "2018-12-11T18:27:01.876Z"
}
],
"source_currency": "USD",
"destination_amount": "9952.77",
"destination_currency": "MXN",
"deposit": false
}
HTTP Request
GET https://api.routefusion.co/v1/users/<SUB_USER_UUID>/transfers/<TRANSFER_UUID>
URL Parameters
Param | Type | Description | Required |
---|---|---|---|
SUB_USER_UUID | UUID | this is the uuid of your sub-user | yes |
TRANSFER_UUID | UUID | this is the uuid of the transfer | yes |
MASTER Get Transfer Status
Response JSON:
{
"state": "processing",
"created_at": "2018-12-03T20:35:31.017Z"
}
HTTP Request
GET https://api.routefusion.co/v1/users/<SUB_USER_UUID>/transfers/<TRANSFER_UUID>/status
Parameters
Param | Type | Description | Required |
---|---|---|---|
SUB_USER_UUID | UUID | this is the uuid of your sub-user | yes |
TRANSFER_UUID | UUID | this is the uuid of the transfer | yes |
MASTER Cancel Transfer
Sample JSON response:
{
"message": "transfer 1e5c3676-8d88-4680-85f3-3c109a5dfd1c cancelled"
}
HTTP Request
DELETE https://api.routefusion.co/v1/users/<SUB_USER_UUID>/transfers/<TRANSFER_UUID>
URL Parameters
Param | Type | Description | Required |
---|---|---|---|
SUB_USER_UUID | UUID | this is the uuid of your sub-user | yes |
TRANSFER_UUID | UUID | this is the uuid of the transfer | yes |
Rates
Get a rate
const rf = require('routefusion-sdk').Instance();
const ratesPayload = {
destination_currency: 'MXN',
source_currency: 'USD'
};
rf.getRate(ratesPayload)
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
{
"source_currency": "USD",
"destination_currency": "MXN",
"rate": "22.2186",
"inverted_rate": "0.045"
}
You can request a rate for a specified currency pair. This is an indicative rate only and does not secure a rate for a subsequent transfer. Use the quotes API for securing a rate when creating a transfer.
HTTP Request
GET https://api.routefusion.co/v1/rates
Query Parameters
Column | Description | Required |
---|---|---|
source_currency | currency to be sold | yes |
destination_currency | currency to be bought | yes |
Quotes
Create a quote
const rf = require('routefusion-sdk').Instance();
const quotePayloadWithoutValueDate = {
source_amount: 100,
destination_currency: 'MXN',
source_currency: 'USD'
};
// This will respond with payment_method available to the beneficiary and the associated fee amount
const quotePayloadWithBeneficiaryId = {
source_amount: 100,
source_currency: 'USD',
beneficiary_id: 432,
date_of_payment: '2020-01-30'
};
// This will respond with a null fee and a null payment_method. To be determined on transfer creation
const quotePayloadWithPaymentDate = {
source_amount: 100,
destination_currency: 'MXN',
source_currency: 'USD',
date_of_payment: '2020/01/30' // YYYY/MM/DD or YYYY-MM-DD
};
rf.createQuote(quotePayloadWithoutValueDate)
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
{
"uuid": "QUca9e8220-eccb-4957-8fd0-ab6623f83ff5",
"source_currency": "USD",
"destination_currency": "MXN",
"rate": "19.219",
"inverted_rate": "0.052",
"fee": "6.00",
"payment_method": "swift",
"date_of_payment": "2020-01-30T00:00:00.000Z",
"expires_at": "2020-01-20T04:47:19.012Z",
"created_at": "2020-01-20T04:18:54.042Z"
}
This endpoint creates a quote. You may set the date of the quote for scheduled payments using value_date. Otherwise the system will find a quote for the earliest possible payment date.
NOTE: Fee will only be calculated if a verified beneficiary_id
, or a payment_method
is provided. Otherwise, the fee
, and payment_method
will be returned as null
and will be resolved upon transfer creation.
HTTP Request
POST https://api.routefusion.co/v1/quotes
Body
Column | Description | Required |
---|---|---|
source_amount | source currency amount | yes |
source_currency | currency to be sold | yes |
destination_currency | currency to be bought | optional |
beneficiary_id | Routefusion beneficiary ID | optional |
payment_method | method for the relevant transfer. One of "swift" or "local". Must be an available method for beneficiary | optional |
date_of_payment | date to make payment. YYYY/MM/DD or YYYY-MM-DD | optional |
Transfer Batches
To handle a collection of transfers at once, or Transfer Batches, the Routefusion API exposes several endpoints to present a flexible flow. You can create Batches that are auto-completed, which means no quotes are required for the Transfers contained within, or you can create a Quote for each Transfer in the batch using the Batch Quotes API.
Note on Transfer Batch Statuses
Transfer Batches all have a status
value. This status
represents the status of the Transfer Batch itself, and does not include any notion of individual Transfer statuses. That is, if a Transfer within the Transfer Batch is rejected or otherwise fails, the Transfer Batch status will still be processed
once all transfers within the batch have been worked, while the individual Transfer in question will reflect the proper failed
status. To derive individual Transfer statuses, you'll first want to get the Transfer UUIDs from the GET Batch Transfer API. Once you have the UUID, you can either subscribe to webhook events for each of the Transfers in the Transfer Batch, or you can poll the GET Transfer API and check each Transfer's state.
Status definitions: created: the batch has been created and is awaiting processing processing: the batch is being processed by the backend, as through the Process Transfer Batch API processed: the batch's transfers have all been sent to the Routefusion API for processing, and can now be individually tracked
Typical status flow: Created -> Processing -> Processed
Create Transfer Batch
HTTP Request
POST https://api.routefusion.co/v1/batches
This endpoint creates a Transfer Batch, ready to be processed. Attempting to use unverified beneficiaries will return an error.
Sample JSON request payload:
{
"source_currency": "SGD", // required if user has more than one account
"transfers": [
{
"beneficiary_uuid": "1ea03336-5284-42b3-8a74-2f47e391f55c",
"source_amount": 2000
},
{
"beneficiary_uuid": "f9ba10d5-445a-4295-81b6-e8fe9c36f391",
"source_amount": 2500
},
....
....
]
}
The above command returns JSON structured like this:
{
"uuid": "BA-2e54f693-560e-42e3-a938-747a507f1c5b",
"status": "created",
"source_currency": "SGD",
"transfers": [
{
"source_amount": "2000.00",
"beneficiary_uuid": "1ea03336-5284-42b3-8a74-2f47e391f55c"
},
{
"source_amount": "2500.00",
"beneficiary_uuid": "f9ba10d5-445a-4295-81b6-e8fe9c36f391"
}
]
}
Create Quotes Batch
HTTP Request
POST https://api.routefusion.co/v1/batches/quotes
This endpoint creates a Quotes Batch. A Quote Batch is comprised of individual quotes for each Transfer in the Transfer Batch, referenced when the Quote Batch is created. The currencies for the quote are derived automatically from a combination of the Beneficiary's configured currency (destination) and the User Account's configured currency (source). The Quote Batch will expire in 30 seconds, after which time you'll need to create a new Quotes Batch in order to process the Transfer Batch. Note: you can skip calling this API if your Transfer Batch is to be automatically processed by simply calling the Process Transfer Batch
API.
Sample JSON request payload:
{
batch_id: <BATCH_UUID>
}
The above command returns JSON structured like this:
{
"uuid": "d960a37c-8730-4ba8-a6c9-495120bbc856",
"quotes": [
{
"quote_uuid": "QUcc2ae16b-2b28-4aea-90f2-bb30d41c5c3f",
"source_currency": "SGD",
"destination_currency": "HKD",
"rate": "5.7445",
"inverted_rate": "0.17407955435634084",
"fee": "3.00",
"payment_method": "local"
},
{
"quote_uuid": "QU2fb7b894-3569-4a0d-be8b-dd72bbad5065",
"source_currency": "SGD",
"destination_currency": "USD",
"rate": "0.7326",
"inverted_rate": "1.365001365001365",
"fee": "3.00",
"payment_method": "local"
}
],
"expires_at": "2020-09-08T20:27:13.487Z"
}
Process Transfer Batch
HTTP Request
POST https://api.routefusion.co/v1/batches/<BATCH_UUID>/process
URL Parameter
Param | Type | Description | Required |
---|---|---|---|
BATCH_UUID | UUID | this is the uuid of your batch | yes |
This endpoint will queue a Transfer Batch to be processed. If a Transfer Batch had a Quotes Batch associated with it via the Create Quotes Batch
API, those quotes will be used to create the Transfers. If no Quotes Batch is associated, a Quote will automatically be generated and applied to the resulting Transfer. The latter flow allows for quickly processing Transfer Batch when no rate confirmations are required. The former flow allows for presenting the rates for each Transfer in the Batch to a User, so they can choose whether to process the Transfer Batch now or in the future. Note: no body is required for this endpoint
Sample JSON request payload:
{}
The above command returns JSON structured like this:
{
"uuid": "BA-2e54f693-560e-42e3-a938-747a507f1c5b",
"status": "processing",
"transfers": [
{
"source_currency": null,
"source_amount": "100.00",
"destination_amount": null,
"beneficiary_uuid": "1ea03336-5284-42b3-8a74-2f47e391f55c"
},
{
"source_currency": null,
"source_amount": "100.00",
"destination_amount": null,
"beneficiary_uuid": "f9ba10d5-445a-4295-81b6-e8fe9c36f391"
}
]
}
Get Batch of Transfers
HTTP Request
GET https://api.routefusion.co/v1/batches/<BATCH_UUID>
URL Parameter
Param | Type | Description | Required |
---|---|---|---|
BATCH_UUID | UUID | this is the uuid of your batch | yes |
The above command returns JSON structured like this:
{
"uuid": "BA-2e54f693-560e-42e3-a938-747a507f1c5b",
"status": "processed",
"transfers": [
{
"source_currency": null,
"source_amount": "100.00",
"destination_amount": null,
"uuid": "580d4f95-e2ac-4150-94f6-bccbe2ef3ca2",
"beneficiary_uuid": "f9ba10d5-445a-4295-81b6-e8fe9c36f391"
},
{
"source_currency": null,
"source_amount": "100.00",
"destination_amount": null,
"uuid": "310be097-806e-4407-bdcb-23536e9a541b",
"beneficiary_uuid": "1ea03336-5284-42b3-8a74-2f47e391f55c"
}
]
}
Transactions
List all of your users Transactions
const rf = require('routefusion-sdk').Instance();
rf.getAllTransfers()
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
[
{
"uuid": "5d745492-0780-4132-93d6-543e5fa9bb64",
"user_id": 2,
"account_id": null,
"beneficiary_id": 427,
"currency_pairs": "MXNUSD",
"source_currency": "USD",
"source_amount": "1000.00",
"destination_amount": "19103.30",
"destination_currency": "MXN",
"exchange_rate": "19.103304",
"authorizing_ip": "157.131.245.19",
"state": "completed",
"fee": "6.00",
"payment_method": "swift",
"transfer_states": [
{
"state": "created",
"created_at": "2019-05-11T01:19:03.938Z"
},
{
"state": "processing",
"created_at": "2019-05-11T01:19:04.760Z"
},
{
"state": "completed",
"created_at": "2019-05-11T01:19:04.760Z"
}
],
"created_at": "2019-05-11T01:19:03.976Z"
},
{
...
}
]
This endpoint lists out all of your transactions.
HTTP Request
GET https://api.routefusion.co/v1/transfers
Query Parameters
Param | Type | Description |
---|---|---|
limit | integer | Limits the amount of results to the amount specified. i.e. limit=5 will return the first 5 results |
offset | integer | Offset is the position in the dataset of a particular record. see notes for example |
order_by | string | Defaults to id, must be an object property e.g. order_by="created_at" |
order | string | Defaults to 'asc', must be 'asc' or 'desc' |
filter | object | Accepts 'and', 'lt', 'lte', 'gt', 'gte' as filter operators, and 'created_at' as attributes within e.g. filter[lte][created_at]=2020-04-27 |
NOTES:
filter[and]
will require two filter operators of each side of the equation to work. Ex:
https://api.routefusion.co/v1/transfers?filter[and][lt][created_at]="THE_CREATED_AT_DATE"&filter[and][gte][created_at]="THE_CREATED_AT_DATE"
The limit and offset query parameters are typically used to paginate lists. limit
allows you to specify the number of objects to return in one request. offset
allows you to specify the ranking number of the first item on the page.
Usage: If you have 100 records in your result set, and you want to retrieve records 50 to 80, you would use offset=49
and limit=30
.
Requesting all transactions will be deprecated on May 31st, 2020. After May 31st, 2020, calls without pagination query parameters will have a default limit of 300.
Webhooks
Webhooks will allow you to receive "real time" notifications about your Routefusion objects you would like to monitor.
We currently support webhooks for Transfer, and Beneficiary notifications. USERS are coming soon
Get webhook
const rf = require('routefusion-sdk').Instance();
rf.getWebhook(WEBHOOK_UUID)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"uuid": "WH07d15675-bc7a-4f5b-805c-04961af401f2",
"url": "https://www.newco.com/your_custom_url",
"type": "TRANSFER",
"rfuuid": "1fd45635-njda-4f5b-805c-04961jk38r9",
"failed_count": 0,
"retry_count": 0,
"updated_at": "2019-09-03T21:20:07.382Z",
"created_at": "2019-09-03T21:16:56.650Z"
}
This endpoint retrieves information about a webhook.
HTTP Request
GET https://api.routefusion.co/v1/webhooks/<webhook_uuid>
URL Parameters
Parameter | Description |
---|---|
webhook_uuid | your webhook uuid |
Update webhook
const rf = require('routefusion-sdk').Instance();
let webhook_uuid = "WH07d15675-bc7a-4f5b-805c-04961af401f2";
let body = {
"url": "https://www.newco.com/your_new_custom_url",
};
rf.updateWebhook(webhook_uuid, body)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"uuid": "WH07d15675-bc7a-4f5b-805c-04961af401f2",
"url": "https://www.newco.com/your_new_custom_url",
"type": "TRANSFER",
"rfuuid": "1fd45635-njda-4f5b-805c-04961jk38r9",
"failed_count": 0,
"retry_count": 0,
"updated_at": "2019-09-03T21:20:07.382Z",
"created_at": "2019-09-03T21:16:56.650Z"
}
This endpoint updates information about a webhook.
HTTP Request
PUT https://api.routefusion.co/v1/webhooks/<webhook_uuid>
Body
Column | Type | Description |
---|---|---|
url | STRING | Your unique URL that you will receive updates to |
type | STRING | The type of object (TRANSFER, USER, BENEFICIARY) |
rfuuid | UUID | The UUID of Routefusion object you would like to monitor |
URL Parameters
Parameter | Description |
---|---|
webhook_uuid | your webhook uuid |
Index webhooks
const rf = require('routefusion-sdk').Instance();
rf.getWebhooks()
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
[
{
webhook1
},
{
webhook2
}
]
This endpoint retrieves all the info on your users.
HTTP Request
GET https://api.routefusion.co/v1/webhooks/
Create webhook
const rf = require('routefusion-sdk').Instance();
// transfer webhook
const xferWebhook = {
type: “transfer”,
url: “https://www.newco.com/your_custom_url”,
rfuuid: "37cba64b-1a22-4732-be22-04826da09405"
};
// beneficiary webhook
const beneWebhook = {
type: “beneficiary”,
url: “https://www.newco.com/your_custom_url”,
rfuuid: "f72c296d-5228-4ec6-b313-aecb430d3ce3"
}
rf.createWebhook(xferWebhook)
.then(resp => resp)
.catch(err => err)
The above command returns JSON structured like this:
{
"uuid": "WH07d15675-bc7a-4f5b-805c-04961af401f2",
"url": "https://www.newco.com/your_custom_url",
"type": "transfer",
"rfuuid": "37cba64b-1a22-4732-be22-04826da09405",
"failed_count": 0,
"retry_count": 0,
"updated_at": "2019-09-03T21:20:07.382Z",
"created_at": "2019-09-03T21:16:56.650Z"
}
This endpoint updates information about your user profile.
HTTP Request
POST https://api.routefusion.co/v1/webhooks
Body
Column | Type | Description | Required |
---|---|---|---|
url | STRING | Your unique URL that you will receive updates to | yes |
type | STRING | The type of object (TRANSFER, USER, BENEFICIARY) | yes |
rfuuid | UUID | The UUID of Routefusion object you would like to monitor | yes |
URL Parameters
None
Delete webhook
const rf = require('routefusion-sdk').Instance();
const WEBHOOK_UUID = 'WH07d15675-bc7a-4f5b-805c-04961af401f2';
rf.deleteWebhook(WEBHOOK_UUID)
.then(resp => resp)
.catch(err => err)
The above command returns:
{
"message": "Success"
}
This endpoint retrieves information about a webhook.
HTTP Request
DELETE https://api.routefusion.co/v1/webhooks/<webhook_uuid>
URL Parameters
Parameter | Description |
---|---|
webhook_uuid | your webhook uuid |
Transfer event payload
All transfer events will return a payload with these attributes
{
"type": "transfer",
"state": "processing",
"uuid": "f58dc1cd-cc0c-4fd9-ba7e-dd6e6b131ffe",
"user_uuid": "3a10fadb-25ed-4a50-b6a3-ea992929bf21",
"webhook": {
"uuid": "WH67ba6124-5e1e-402e-a646-8a4ca029a294",
"user_id": 22,
"url": "http://5eb192dfc33.ngrok.io/hooks",
"type": "transfer",
"rfuuid": "f58dc1cd-cc0c-4fd9-ba7e-dd6e6b131ffe",
"failed_count": null,
"signature": "TzK+zzmMGBzwPSnDtK0NbCDG6r5XS7QvPNFv64mFMiGajiKu0T2pJllAgrrkWH2zXjX1cOtx5vxIQhrRQS6sYA=="
}
}
Transfer events include all status updates:
Status | Description |
---|---|
processing | payment is being processed by the bank/fx provider |
completed | payment is being sent to beneficiary |
Beneficiary event payload
All beneficiary events will return a payload with these attributes
{
"id": 70726,
"uuid": "f2c11fc4-9ef4-4a1f-9cef-4be19c4fcd53",
"user_id": 22,
"company_name": "Rejection Co",
"first_name_on_account": "",
"last_name_on_account": "",
"type": "business",
"bank_name": "NATIONAL WESTMINSTER BANK PLC",
"branch_name": null,
"bank_city": "London",
"bank_code": null,
"branch_code": null,
"account_type": "business",
"account_number": "GB69NWBK52301841660000",
"routing_number": "003456",
"clabe": null,
"tax_number": null,
"email": "testGB@beneficiary.com",
"phone_number": "447972729230",
"country": "GB",
"city": "HITCHIN",
"bank_state_province": null,
"verified": true,
"created_at": "2020-11-16T18:49:12.759Z",
"updated_at": "2020-11-16T18:49:22.779Z",
"currency": "GBP",
"cpfcnpj": null,
"deleted_at": null,
"third_party_ids": null,
"swift_bic": "NWBKGB2L",
"bank_address1": "PREMIER PLACE, DEVONSHIRE SQUARE",
"bank_address2": null,
"bank_country": "GB",
"bank_postal_code": "EC2M4XB",
"address1": "Suite 1, Test Street",
"address2": null,
"state_province": "HERTFORDSHIRE",
"postal_code": "SG5 2DW",
"bsb_number": null,
"status_history": [ { "status": "created", "created_at": "2020-11-16T18:49:12.759Z" }, { "status": "verified", "created_at": "2020-11-16T18:50:19.739Z" } ],
"status": "verified",
"purpose_of_payment": null,
"identification_type": null,
"identification_value": null,
"provider_references": [],
"request_id": "42877d13-53c9-4f1a-a80f-e98f1d2d26e4",
"webhook": {
"uuid": "WH57a94f32-9ab7-4af1-a97f-ce03617ae710",
"user_id": 22,
"url": "http://5eb192dfdc33.ngrok.io/hooks",
"type": "beneficiary",
"rfuuid": "f2c11fc4-9ef4-4a1f-9cef-4be19c4fcd53",
"failed_count": null,
"signature": "hEmRjLwRglreXxFFXtXGv7hbYqZAIpf7+Bzm85KjV9bn/YWjKPqE24osFdJwKIqEKPIvNJEVz5j0y7pAzmTzGA=="
}
}
Beneficiary event will trigger once the beneficiary is verified by the bank/fx provider(s)
Compliance Verification
Send compliance data
Example JSON request body
{
"legal_name": "Wicky Wacky Inflatable Arm Co.",
"description": "we sell wacky inflatable arm balloons!",
"agreed_to_terms": true,
"allow_account_management": true,
"street_address": "600 Congress Ave.",
"city": "Austin",
"state_province": "TX",
"country": "US",
"postal_code": "75745",
"phone_number": "88881355888",
"website": "www.testCompany.com",
"dba_name": "Wacky Inflatable Arms", // business alias name
"company_structure": "llc",
"date_of_incorporation": "2009-04-07",
"incorporation_number": "29-1234567",
"company_identification_doc": "YXNkZmFkcw==", // base64 image
"owners": [
{
"title": "",
"full_name": "",
"citizenship": "",
"id_type": "",
"id_number": "",
"dob": "",
"street_address": "",
"city": "",
"state_province": "",
"country": "",
"postal_code": "",
"job_title": "",
"percent_ownership": "",
"proof_of_address_doc": "",
"personal_identification_doc": ""
},
{
// more owners
}
],
"payments": {
"countries": [
"IT",
"MX",
"AU"
],
"frequency": "monthly",
"purpose": "Contract Labor",
"count": 100,
"volume": "100000" // we will accept integers or strings for numeric values
}
}
this endpoint will respond with a 201 status and no body
convert image to base64 example
const fs = require('fs');
fs.readFile(pathToImageFile, (err, buffer) => {
const base64String = Buffer.from(buffer, 'base64').toString('base64');
// do something with string
});
This endpoint takes in compliance data for a user. All parameters which end in 'doc' must be a valid base64 string or url reference to an image IN COLOR. All images must be color copies.
Note: these requirements are subject to change as our own compliance requirements change.
HTTP Request
POST https://api.routefusion.co/v1/users/<SUB_USER_UUID>/compliance
URL Parameters
Parameter | Description | Required |
---|---|---|
SUB_USER_UUID | uuid of user to send compliance data on behalf of | yes |
Body
Parameter | Type | Required | Description |
---|---|---|---|
legal_name | STRING | yes | legal entity name |
dba_name | STRING | no | alias name (for businesses only) |
description | STRING | yes | one or two words describing the business e.g. e-commerce, retail distribution, financial services, etc. |
company_structure | STRING | no | structure of business entity e.g. 'llc', 'c-corp', etc. |
agreed_to_terms | BOOLEAN | yes | boolean stating if this user has agreed to terms and conditions |
allow_account_management | BOOLEAN | no | boolean stating you agree to allow Routefusion to manage this account |
street_address | STRING | no | |
city | STRING | no | |
country | STRING | no | |
date_of_incorporation | STRING | no | must be in date format i.e. YYYY-MM-DD |
phone | STRING | no | |
postal_code | STRING | no | |
state_province | STRING | no | |
website | STRING | no | |
incorporation_number | STRING | no | |
company_identification_doc | STRING | no | base64 or url of company registration document or equivalent |
owners | ARRAY | no | array of owner objects described below |
payments | OBJECT | no | object of payment data described below |
Owners Objects
Parameter | Type | Required | Description |
---|---|---|---|
title | STRING | no | e.g. 'Mr.', 'Mrs.', etc. |
full_name | STRING | yes | full name |
citizenship | STRING | no | country of citizenship (2 character ISO code only) |
id_type | STRING | no | e.g. 'drivers license', 'passport', etc. |
id_number | STRING | no | |
dob | STRING | no | must be in date format i.e. YYYY-MM-DD |
street_address | STRING | no | |
city | STRING | no | |
state_province | STRING | no | |
country | STRING | no | 2 character ISO code only |
postal_code | STRING | no | |
job_title | STRING | no | |
personal_identification_doc | STRING | no | base64 or url of passport or equivalent |
proof_of_address_doc | STRING | no | base64 or url of utility bill, bank_statement, or other accepted proof of address |
percent_ownership | NUMBER | no | numeric value, the sum of all owners' percent_ownership must be 100 |
Payments Objects
Parameter | Type | Required | Description |
---|---|---|---|
frequency | STRING | e.g. 'monthly', 'yearly' (will default to monthly) | |
count | NUMBER | estimated number of payments in the given frequency period | |
volume | NUMBER | estimated total currency amount of payments in the given frequency period | |
countries | ARRAY | array of countries which payments will be sent to (2 character ISO code only) |
Submit compliance data
This endpoint submits a users compliance data.
This request returns JSON structured like this:
{ "message": "success" }
HTTP Request
POST https://api.routefusion.co/v1/users/<SUB_USER_UUID>/compliance/submit
URL Parameters
Parameter | Description | Required |
---|---|---|
SUB_USER_UUID | uuid of user to send compliance data on behalf of | yes |
Banks
Find a bank
const rf = require('routefusion-sdk').Instance();
const findBySwiftCode = {
swift_bic: 'BUKBGB22XXX'
};
const findByIBAN = {
iban: 'GB29NWBK60161331926819'
};
rf.findBank(findByIBAN)
.then(resp => resp)
.catch(err => err)
The above returns JSON structured like this:
{
"bank_name": "NATIONAL WESTMINSTER BANK PLC",
"branch_name": "NATIONAL WESTMINSTER BANK PLC",
"bank_address1": "PREMIER PLACE, DEVONSHIRE SQUARE",
"bank_address2": null,
"bank_city": "LONDON",
"bank_state_province": null,
"bank_country": "GB",
"bank_postal_code": "EC2M 4XB",
"swift_bic": "NWBKGB2LXXX",
"bank_code": null,
"branch_code": "601613"
}
This endpoint will find all the details of a bank using either the SWIFT/BIC code or an IBAN number.
Notes: The payload accepts an either 8 or 11 character SWIFT/BIC code. If an 8 character SWIFT/BIC code is provided the api will assume the final 3 characters are 'XXX'.
Notes: Only SWIFT/BIC or IBAN can be provided. If both are provided it will throw a validation error.
HTTP Request
POST https://api.routefusion.co/v1/banks/find
Body
Column | Description | Required |
---|---|---|
swift_bic | SWIFT/BIC (the SWIFT code, also known as the Bank International Code) | optional - only one can be provided |
iban | International Bank Account Number (must be a valid IBAN - reference iban.com) | optional - only one can be provided |
Currency Coverage
Get Currencies
curl https://api.routefusion.co/currencies
This endpoint lists out all of our available currencies in JSON format. The response also includes the beneficiary requirements of each currency / country
HTTP Request
GET https://api.routefusion.co/currencies
Wire Instructions
Get Wire Instructions
The above returns an array of objects containing our currency coverage
[
{
"Currency": "USD",
"PaymentInstructions": "Bank Wire Instructions..."
}
]
Use this endpoint to get the wire instructions to fund a payment. If you are in the US we recommend you setup with ACH pull as this creates a more seamless process for you.
HTTP Request
GET https://api.routefusion.co/v1/instructions?currency_code=<CURRENCY_CODE>
Query Parameters
Parameter | Description |
---|---|
CURRENCY_CODE | 3 character iso currency code |
Errors
The RouteFusion International Payments API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
405 | Method Not Allowed |
406 | Not Acceptable |
410 | Gone |
418 | I'm a teapot. |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service Unavailable |