NAV Navbar
javascript

Getting Started

Welcome to the Routefusion API docs!

REGISTER FOR AN API KEY

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

REGISTER FOR AN API KEY

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:

  1. local instance configuration
  2. environment variables
  3. 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.

User account create

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
email 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
email 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
email 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

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
email 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
email 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.

Flow of funds

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
javascript