NAV
curl Ruby Javascript PHP C#

Introduction

API Endpoint

https://api.paymentrails.com/v1/

Payment Rails’ API allows businesses to send payments to their recipients globally. Recipients can be either an individual or a business, such as freelance workers, contractors, affiliates, developers, designers, hosts, drivers, or even business suppliers around the world.

Our philosophy is to give more choice of payout methods to users. What works for someone in San Francisco, London or Melbourne, might not be the best option for someone else in Jakarta, Nairobi or Mumbai. PayPal doesn’t support all countries, in fact, 97.5% of the population don’t have a PayPal account, and over 2 billion people don’t have a bank account. So clearly multiple payment options are needed to support a global business. Thats why we plan to support every major payout method, so your users have choice of what works best for them.

Payment Rails currently supports sending payments direct to recipient bank accounts (in 220+ countries), and PayPal accounts. In the near future, we will also support payments by mobile money, cash pick-up, paper checks, and to existing debit cards or credit cards.

If you have an existing e-wallet service you use to make payouts (like PayPal), you can plug-in your business’ PayPal or other e-wallet account to our platform, and push payments out through your existing account with no additional fees from us. This allows you to have one consolidated payout platform to handle all your payouts, through one API integration. It also means that you can start offering direct-to-bank account payouts to your users and all our other methods, while offering your users a seemless transition from your current payout options.

We will always be looking to add the fastest, least expensive, most popular and most convenient payout methods that people want to use. So your business only ever has to integrate with one partner (us), and we will ensure you and your users always get access to the latest and greatest payout methods available on the market, at the most competitive rates.

Before you start

Here is a quick summary of some common terms we use:

Term ID # Format Description
Recipient R-0A0A0A0A0A0A0A0A A Recipient is the individual or business that you need to send a payment to.
Payment P-0A0A0A0A0A0A0A0A A Payment is an individual payout to a recipient.
Batch B-0A0A0A0A0A0A0A0A A Batch is a group of payments.
Transfer T-0A0A0A0A0A0A0A0A A Transfer is a deposit (or withdrawal) you make to your Payment Rails account from your company bank account, to fund your balance before sending payments.

Interacting with the API

Making requests

The Payment Rails API follows RESTful design principles. We use the following HTTP verbs:

When making requests, arguments can be passed as params or JSON with correct Content-Type header of application/json.

Success Codes

The Payment Rails API uses the following successful response codes:

Success Code Meaning
200 Ok – Request processed successfully

Error Codes

Example API response for object not found

{
  "ok": false,
  "errors": [
    {
      "code": "not_found",
      "message": "Object not found"
    }
  ]
}

Example API Failure for validation

{
  "ok": false,
  "errors": [
    {
      "code": "empty_field",
      "field": "type",
      "message": "Expected to have a non-null or non-empty value"
    },
    {
      "code": "empty_field",
      "field": "name",
      "message": "Expected to have a non-null or non-empty value"
    }
  ]
}

The Payment Rails API uses the following error codes:

Error Code HTTP Code Description
invalid_token 401 Token is invalid
invalid_api_key 403 Invalid API key
not_authorized 403 Authentication not permitted to access resource
not_found 404 If object not found
invalid_status 406 Status of any object is invalid
invalid_field 406 Value is invalid
empty_field 406 Value is required
expired_quote 406 Quote is expired
rate_limit_exceeded 429 Rate limit exceeded
partner_integration_error 500 Sonething goes wrong with our partner
internal_server_error 500 Internal server error

In the event that the API returns an error, the response body will contain the following information:

Response

KEY Meaning
ok boolean false – this api call failed
errors array of descriptions, more detail on the failures, this may be multiple values for validation failures or a single value for other failures.

CORS

Payment Rails API supports cross-origin HTTP requests which is commonly referred as CORS. This means that you can call API resources using Javascript from any browser. While this allows many interesting use cases, it’s important to remember that you should never expose private API keys to 3rd parties. CORS is mainly useful with unauthenticated endpoints and OAuth2 client side applications.

Fields

Type Description
string An arbitrary string value
integer Integer number
float Floating point number
date All dates are represented in in ISO 8601 format in the UTC (Z) timezone (e.g. “2015-07-01T00:55:47Z)
country All country codes are ISO ALPHA-2 country codes (e.g. “US”, “CA”, or “JP”)

Rate limiting

The Payment Rails API is rate limited to prevent abuse that would degrade our ability to maintain consistent API performance for all users. By default, each API key or app is rate limited at 10,000 requests per hour. If your requests are being rate limited, HTTP response code 429 will be returned with an rate_limit_exceeded error.

If your application requires higher rate limits, please email us a request at api@paymentrails.com.

Authentication

All calls to the Payment Rails API require authentication. You will need to get an access key and secret key from the dashboard via the settings page.

Signing requests

API Key authenticaiton requires each request to be signed, this ensures that your secret key is not part of the transmission.

Making a request

All REST requests must containt the following headers:

All request bodies should have a content type of application/json and be valid JSON.

The Authorization header will have the format of Authorization: prsign ACCESS_KEY:REQUEST_SIGNATURE

The REQUEST_SIGNATURE is computed by creating a sha256 HMAC using the ssecret key on the prehash string and timestamp + '\n' + method + '\n' + requestPath + '\n' + body + '\n'.

Your timestamp must be within 30 seconds of the UTC time or your requests will be considered expired and rejected.

Example of creating signature

# Requires python-requests. Install with pip:
#
#   pip install requests
#

import json, hmac, hashlib, time, requests
from requests.auth import AuthBase

# Your key and secret as obtained by the Dashboard UI
API_KEY = 'API_KEY'
API_SECRET = 'API_SECRET'

# Create custom authentication for Coinbase API
class PaymentRailsAuth(AuthBase):
    def __init__(self, api_key, secret_key):
        self.api_key = api_key
        self.secret_key = secret_key

    def __call__(self, request):
        print "PATH", request.path_url
        timestamp = str(int(time.time()))
        message = '\n'.join([timestamp, request.method, request.path_url, (request.body or ''), ''])
        signature = hmac.new(self.secret_key, message, digestmod=hashlib.sha256).hexdigest()

        request.headers.update({
            'Authorization': 'prsign %s:%s' % (self.api_key, signature),
            'X-PR-Timestamp': timestamp,
        })

        print request.headers
        return request

api_url = 'https://api.paymentrails.com/v1/'
auth = PaymentRailsAuth(API_KEY, API_SECRET)

# Get list of recipients
r = requests.get(api_url + 'recipients', auth=auth)
print r.json()

Example API request

curl \
  -H "Content-Type: application/json" \
  -H "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
  -X POST \
  -d '{"type": "individual", "firstName": "Elon", "lastName": "Mask", "email": "elon@mask.com"}' \
  https://api.paymentrails.com/v1/recipients

Additional Security for API Keys

For enhanced API Key security, we recommend that you whitelist IP addresses that are permitted to make requests at Security tab under the Settings section in the merchant dashboard.

Recipients

A recipient is an individual or company that can receive payments, such as freelancers, contract workers, suppliers, marketplace sellers, employees, etc. Basically, anyone your business needs to pay.

Recipients can receive payouts directly to their Bank Account or their PayPal account (with more payout options coming soon, such as Mobile Money, Check, Debit Card, Credit Card, and Cash pick-up).

Recipients must be created prior to sending a payment to them. When you create a recipient, we automatically generate and assign a unique recipient Id. The format of all recipient IDs are “R-0A0A0A0A0A0A0A0A”, with the ‘R-’ prefix indicating Recipient.

Recipient Attributes

Example Recipient

{
   "id": "R-78G3F33W2H2S7G23",
   "referenceId": "U341553728",
   "email": "richard@example.com",
   "name": "",
   "lastName": "Richard",
   "firstName": "Hendricks",
   "status": "active",
   "complianceStatus": "verified",
   "gravatarUrl": "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50",
   "language": "en",
   "dob": "1991-12-23",
   "passport": "HA24123423",
   "ssn": "123-45-6789"
}
Attribute Type Description
id string A system generated ID number assigned to the recipient by Payment Rails.
referenceId string Recipient reference ID as assigned by your business (your internal user reference number)
email string Email address of recipient
name string Full name of the recipient if it is an individual. If the recipient is a company, the name of the company.
lastName string Last name of the recipient if an individual
firstName string First name of the recipient if an individual
status string Status of a recipient in the system
complianceStatus string Compliance status of Recipient
gravatarUrl string The gravatar url of recipient
language string Short code of Language
dob date
optional
Date of Birth YYYY-MM-DD
passport string
optional
Passport number
ssn string
optional
Social Security Number
governmentId string
optional
Government Id or Tax ID. Applicable for some countries.
address object Address details of recipient
payout object Payout method of recipient

Address

Example Address

{
    "street1": "123 Main St",
    "street2": "",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94131",
    "country": "USA",
    "phone" : "18005551212"
}
Method Field Type Description
street1 String Street 1 address
street2 String
optional
Street 2 address. You can pass empty string if you don’t have street2
city String City
postalCode String
optional
A valid Postal code
country String Country code. The code is different for different countries. Details available here
region String Region/State/Province code. The code differs country to country. Example code list here based on country code: CA (Canada). More details here
phone String
optional
A valid phone number. Example: 5143334444 (Phone number in US and Canada format)

Payout Method

For further information read about the Payout Method Attributes

Create a recipient

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X POST \
  -d '{"type": "individual", "firstName": "John", "lastName": "Smith", "email": "jsmith@example.com"}' \
  https://api.paymentrails.com/v1/recipients

Create Recipient with address

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X POST \
  -d '{"type": "individual", "firstName": "John", "lastName": "Smith", "email": "jsmith1@example.com", "address": {"street1": "623 Rue De Catherin", "street2": "Apt 14", "phone": "5144384747",  "city": "Montreal", "country": "CA", "region": "QC", "postalCode": "H3WXXX"}}' \
  https://api.paymentrails.com/v1/recipients
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};
var body = {
  type: "individual",
  firstName: "John",
  lastName: "Smith",
  email: "jsmith@example.com" };

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Recipient.post('R-SBAHDK3DK5SMSUEM', body, callback);
require 'payment_rails'

recipient = {
  type:"individual"
  firstName: 'John',
  lastName: 'Smith',
  email: 'jsmith@example.com',
  payout: {
    method: 'paypal',
    email: 'jsmithpaypal@example.com'
	}
}

client = PaymentRails.connect(api_key: "<YOUR-API-KEY>")

client.recipients.create(recipient)
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$body = array(
  'type' => 'individual',
  'firstName' => 'John',
  'lastName' => 'Smith',
  'email' => 'jsmith@example.com');

$response = \paymentrails\Recipient::post($body);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
           
            Recipient recipient = new Recipient(null, "individual", null, "jsmith@example.com", null, "John", "Smith",  null, null, null, null, null, null, null, null);

            Recipient response = PaymentRails_Recipient.post(recipient);
            
            Console.WriteLine(response);
            Console.Read();
        }
    }

Example response (200 Ok)

{
  "ok": true,
  "recipient": {
    "id": "R-91XNJBKM30F06",
    "referenceId": "jsmith@example.com",
    "email": "jsmith@example.com",
    "name": "John Smith",
    "lastName": "Smith",
    "firstName": "John",
    "type": "individual",
    "status": "incomplete",
    "language": "en",
    "complianceStatus": "pending",
    "dob": null,
    "updatedAt": "2017-03-08T15:23:45.089Z",
    "createdAt": "2017-03-08T15:23:45.089Z",
    "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
    "compliance": {
      "status": "pending",
      "checkedAt": null
    },
    "payout": {
      "method": null
    },
    "address": {
      "street1": "",
      "street2": null,
      "city": "",
      "postalCode": "",
      "phone": "",
      "country": null,
      "region": null
    }
  }
}

Example response of Recipient with address (200 Ok)

{
  "ok": true,
  "recipient": {
    "id": "R-91XNJBKM30F06",
    "referenceId": "jsmith@example.com",
    "email": "jsmith@example.com",
    "name": "John Smith",
    "lastName": "Smith",
    "firstName": "John",
    "type": "individual",
    "status": "incomplete",
    "language": "en",
    "complianceStatus": "pending",
    "dob": null,
    "updatedAt": "2017-03-08T15:23:45.089Z",
    "createdAt": "2017-03-08T15:23:45.089Z",
    "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
    "compliance": {
      "status": "pending",
      "checkedAt": null
    },
    "payout": {
      "method": null
    },
    "address": {
      "street1": "623 Rue De Catherin",
      "street2": "Apt 14",
      "city": "Montreal",
      "postalCode": "H3WXXX",
      "phone": "5144384747",
      "country": "CA",
      "region": "QC"
    }
  }
}

To create a Recipient, send a POST request to the /recipients endpoint and include the user details in JSON format in the request body. Each recipient will be assigned and represented by an auto-generated ID (recipientId) which can be used to retrieve or update recipient details at a later time.

HTTP Request

POST https://api.paymentrails.com/v1/recipients/

Attributes

Fields Type Description
type string Accepted types are: individual or business
name string Required if recipient’s type is business
firstName string First Name of Recipient. Required if recipient’s type is individual
lastName string Last Name of Recipient. Required if recipient’s type is individual
email string Valid Email address
address address Address object. Please read the documentation
referenceId string
optional
Recipient’s internal reference ID on your own system (user/client number or email)
ssn string
optional
Recipient’s social security numbers without space and hyphen (applicable for United States only).
passport string
optional
Recipients valid passport number
dob date
optional
Recipient’s date of birth. The format should be YYYY-MM-DD, ie 1990-04-29
language string
optional
The code of Recipient’s Language. Details about the codes here e.g en
currency string
optional
The code of Recipient’s primary currency e.g. USD.

HTTP Response codes

HTTP Code Description
200 Recipient successfully created
403 Invalid API key
406 One or more fields failed validation, see errors[] in response body
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
empty_field A field is required
invalid_field A field failed a validation check
invalid_api_key Invalid API key
internal_server_error Internal server errors

Errors Example

If there is a validation error creating a recipients, API will respond with an error. For example:

Response (406 Not Acceptable)

{
  "ok": false,
  "errors": [
    {
      "code": "invalid_field",
      "field": "email",
      "message": "Email is already exists"
    },
    {
      "code": "empty_field",
      "field": "name",
      "message": "Expected to have a non-null or non-empty value"
    }
  ]
}

Retrieve a recipient

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X GET \
   https://api.paymentrails.com/v1/recipients/<recipient-id>
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Recipient.get('R-SBAHDK3DK5SMSUEM', callback);
require 'payment_rails'

recipient_id = 3
client = PaymentRails.connect(api_key: "<YOUR-API-KEY>")

recipient = client.recipients.get(recipient_id)
puts recipient
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$recipient_id = 'R-SBAHDK3DK5SMSUEM';

$response = \paymentrails\Recipient::get($recipient_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";

            String recipient_id = "R-SBAHDK3DK5SMSUEM";
            Recipient response = PaymentRails_Recipient.get(recipient_id);
            
            Console.WriteLine(response);
            Console.Read();
        }
    }

You can retrieve details of a recipient account by sending a GET request to the /recipients/:id endpoint.

HTTP Request

GET https://api.paymentrails.com/v1/recipients/:id

Fields Description
id
string
Resource ID

Response (200 Ok)

{
  "ok": true,
  "recipient": {
    "id": "R-91XNRUTFA9D00",
    "referenceId": "jsmith11@example.com",
    "email": "jsmith11@example.com",
    "name": "Eftakahirul Islam",
    "lastName": "Islam",
    "firstName": "Eftakahirul",
    "type": "individual",
    "status": "active",
    "language": "en",
    "complianceStatus": "verified",
    "dob": null,
    "updatedAt": "2017-03-20T19:06:40.937Z",
    "createdAt": "2017-03-17T20:10:45.818Z",
    "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
    "compliance": {
      "status": "verified",
      "checkedAt": "2017-03-20T19:06:23.916Z"
    },
    "payout": {
      "autoswitch": {
        "limit": 1000,
        "active": false
      },
      "holdup": {
        "limit": 1000,
        "active": false
      },
      "primary": {
        "method": "bank",
        "currency": {
          "currency": {
            "code": "CAD",
            "name": "Canadian Dollar"
          }
        }
      },
      "method": "bank",
      "accounts": {
        "bank": {
          "institution": "123",
          "branch": "to remove",
          "currency": "CAD",
          "country": "CA",
          "name": "TD",
          "branchNum": "47261",
          "accountNum": "*****47"
        }
      },
      "methodDisplay": "Bank Transfer"
    },
    "address": {
      "street1": "Apt# 14",
      "street2": null,
      "city": "",
      "postalCode": "H3WXXX",
      "phone": "",
      "country": "CA",
      "region": "QC"
    },
    "primaryCurrency": "CAD"
  }
}
HTTP Code Description
200 Recipient Object
403 Invalid API key
404 Recipient not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Errors Example

If recipient doesn’t exist, API will respond with an error. For example:

Response (404 Not Found)

{
  "ok": false,
  "errors": [
    {
      "code": "not_found",
      "message": "Object not found"
    }
  ]
}

Update a recipient

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X PATCH \
  -d '{"firstName": "Mark"}' \
  https://api.paymentrails.com/v1/recipients/R-SBAHDK3DK5SMSUEM
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};
var body = {
  firstName: 'Mark'
  };

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Recipient.patch('R-SBAHDK3DK5SMSUEM', body, callback);
require 'payment_rails'

recipient_id = "R-SBAHDK3DK5SMSUEM"
recipient = { firstName: 'Mark'}

client = PaymentRails.connect(api_key: "<YOUR-API-KEY>")

client.recipients.update(recipient_id, recipient)
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$recipient_id = 'R-SBAHDK3DK5SMSUEM';
$body = array('firstName' => 'Mark');

$response = \paymentrails\Recipient::patch($recipient_id,$body);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
           
            Recipient recipient = new Recipient("R-SBAHDK3DK5SMSUEM", null, null, null, null, "Mark", null,  null, null, null, null, null, null, null, null);

            String response = PaymentRails_Recipient.patch(recipient);
            
            Console.WriteLine(response);
            Console.Read();
        }
    }

Response (200 Ok)

{
  "ok": true,
  "object": "updated"
}

You can update the information of an existing recipient by sending a PATCH request to the /recipients/:id endpoint.

Examples of this would be: recipient has a new street address, new payout method, or new payout method details such as a different bank account number, etc. You can also change the status of a recipient such as to active or suspended.

HTTP Request

PATCH https://api.paymentrails.com/v1/recipients/:id

Fields Type Description
id string Resource ID

HTTP Response codes

HTTP Code Description
200 Recipient successfully updated
403 Invalid API key
406 One or more fields failed validation, see errors[] in response body
500 Internal error

Errors

This table lists the expected errors that this request could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
empty_field A field is required
invalid_field A field failed a validation check
invalid_api_key Invalid API key
not_found Object doesn’t exist
internal_server_error Internal server errors

Errors Example

If there is a validation error updating a recipient, the API will respond with an error. For example:

Response (406 Not Acceptable)

{
  "ok": false,
  "errors": [
    {
      "code": "invalid_field",
      "field": "type",
      "message": "Expected to have a non-null or non-empty value"
    }
  ]
}

Delete a recipient

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X DELETE \
   https://api.paymentrails.com/v1/recipients/:id
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Recipient.remove('R-GbGnYCbmsSm6xHnYVyGW7J', callback);

```ruby
require 'payment_rails'

recipient_id = "R-SBAHDK3DK5SMSUEM"
client = PaymentRails.connect(api_key: "<YOUR-API-KEY>")

client.recipients.delete(recipient_id)
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');

$response = \paymentrails\Recipient::delete('R-SBAHDK3DK5SMSUEM');
echo $reponse;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";

            String recipient_id = "R-SBAHDK3DK5SMSUEM";
            String response = PaymentRails_Recipient.delete(recipient_id);
            
            Console.WriteLine(response);
            Console.Read();
        }
    }

To delete a Recipient, send a DELETE request to the /recipients endpoint with the recipientID. The recipient will be deleted from the database, and you will not be able to retrieve the recipient again in future.

HTTP Request

DELETE https://api.paymentrails.com/v1/recipients/

Fields Type Description
id string Resource ID

Response (200 Ok)

{
  "ok": true,
  "object": "deleted"
}
HTTP Code Description
200 Recipient successfully deleted
403 Invalid API key
404 Recipient not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Errors Example

If recipient does not exist, the API will respond with an error. For example:

Response (404 Not Found)

{
  "ok": false,
  "errors": [
    {
      "code": "not_found",
      "message": "Object not found"
    }
  ]
}

Delete multiple recipients

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X DELETE \
  -d '{"ids": ["R-SBAHDK3DK5SMSUEM", R-HB23HTKDRT3KSUE1]}' \
  https://api.paymentrails.com/v1/recipients

Response (200 Ok)

{
  "ok": true,
  "object": "deleted"
}

You can delete multiple recipients by sending a DELETE request to the /recipients endpoint.

HTTP Request

DELETE https://api.paymentrails.com/v1/recipients/

Fields Type Description
ids array of strings Recipient IDs to delete
HTTP Code Description
200 All recipients successfully deleted
403 Invalid API key
404 Recipient not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Errors Example

If any of the recipients do not exist, the API will respond with an error.

Response (404 Not Found)

{
  "ok": false,
  "errors": [
    {
      "code": "not_found",
      "message": "Object not found"
    }
  ]
}

List all recipients

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X GET \
  https://api.paymentrails.com/v1/recipients?search=<key-words>&page=<page-number>&pageSize=<page-size-number>
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Recipient.query(callback, 1, 10, 'John');
require 'payment_rails'

client  = PaymentRails.connect(api_key: "<YOUR-API-KEY>")
results = client.recipients.all(search: "John", pageSize: 10)

puts results
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');

$response = \paymentrails\Recipient::query(1,10,'John');
echo $reponse;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";

            List<Recipient> recipients = PaymentRails_Recipient.query("John", 1, 10);
            
            foreach(Recipient recipient in recipients)
            {
                Console.WriteLine(recipient);
            }
            Console.Read();
        }
    }

Response (200 Ok)

{
  "ok": true,
  "recipients": [
    {
      "id": "R-91XNRUTFA9D00",
      "referenceId": "recardjosh@example.com",
      "email": "jsmith11@example.com",
      "name": "Recardo Josh",
      "lastName": "Josh",
      "firstName": "Recardo",
      "type": "individual",
      "status": "active",
      "language": "en",
      "complianceStatus": "verified",
      "dob": null,
      "updatedAt": "2017-03-20T19:06:40.937Z",
      "createdAt": "2017-03-17T20:10:45.818Z",
      "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "payout": {
        "autoswitch": {
          "limit": 1000,
          "active": false
        },
        "holdup": {
          "limit": 1000,
          "active": false
        },
        "primary": {
          "method": "bank",
          "currency": {
            "currency": {
              "code": "CAD",
              "name": "Canadian Dollar"
            }
          }
        },
        "method": "bank",
        "accounts": {
          "bank": {
            "institution": "123",
            "branch": "to remove",
            "currency": "CAD",
            "country": "CA",
            "name": "TD",
            "branchNum": "47261",
            "accountNum": "*****47"
          }
        },
        "methodDisplay": "Bank Transfer"
      },
      "address": {
        "street1": "Apt# 14",
        "street2": null,
        "city": "",
        "postalCode": "H3WXXX",
        "phone": "",
        "country": "CA",
        "region": "QC"
      },
      "primaryCurrency": "CAD"
    },
    {
      "id": "R-91XNMQ1W1MAQE",
      "referenceId": "jsmith_josh_02@example.com",
      "email": "jsmith_josh_02@example.com",
      "name": "John Smith",
      "lastName": "Smith",
      "firstName": "John",
      "type": "individual",
      "status": "active",
      "language": "en",
      "complianceStatus": "blocked",
      "dob": null,
      "updatedAt": "2017-03-17T18:24:30.061Z",
      "createdAt": "2017-03-12T18:34:33.588Z",
      "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
      "compliance": {
        "status": "blocked",
        "checkedAt": "2017-03-17T18:24:30.053Z"
      },
      "payout": {
        "autoswitch": {
          "limit": 1000,
          "active": false
        },
        "holdup": {
          "limit": 1000,
          "active": false
        },
        "primary": {
          "method": "bank",
          "currency": {
            "currency": {
              "code": "CAD",
              "name": "Canadian Dollar"
            }
          }
        },
        "method": "bank",
        "accounts": {
          "bank": {
            "institution": "123",
            "branch": "to remove",
            "currency": "CAD",
            "country": "CA",
            "name": "test bank",
            "branchNum": "12334",
            "accountNum": "********49"
          }
        },
        "methodDisplay": "Bank Transfer"
      },
      "address": {
        "street1": "1eee",
        "street2": null,
        "city": "Montreal",
        "postalCode": "H3W1A1",
        "phone": "",
        "country": "CA",
        "region": "QC"
      },
      "primaryCurrency": "CAD"
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "records": 2
  }
}

You can retrieve details of your recipients by sending a GET request to the /recipients endpoint. Query parameters can be used in the request to sort, filter or paginate the result set as intended.

For example, use this API to retrieve a list of all active recipients who live in New Zealand.

HTTP Request

GET https://api.paymentrails.com/v1/recipients

Query Param Type Description
page int The page number (default: 1)
pageSize int Number of records in a page (default: 10)
search string Prefix search of the name, email (username and domain-name) and referenceId
name string Prefix search of the name, firstName, lastName
email string Prefix search of the email address
referenceId string Prefix search of the referenceId
startDate date Ignore older records (based on update date)
endDate date Ignore newer records (based on update date)
status string Filter by incomplete, active, suspended
complianceStatus string Filter by pending, verified, blocked
country string Filter by ISO2 country code (comma separated list if multiple)
payoutMethod string Filter by paypal, bank-transfer
currency string Filter by ISO3 currency code (comma separated list if multiple)
orderBy string Field name: name, email, referenceId, payoutMethod, createdAt, updatedAt
sortBy string Sorting direction asc or desc (default: desc)
HTTP Code Description
200 List of Recipient
403 Invalid API key
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Retrieve all logs

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X GET \
   https://api.paymentrails.com/v1/recipients/:id/logs
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Recipient.get('R-SBAHDK3DK5SMSUEM', callback, 'logs');
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$recipient_id = 'R-SBAHDK3DK5SMSUEM';

\paymentrails\Recipient::get($recipient_id,'logs');
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";

            String recipient_id = "R-SBAHDK3DK5SMSUEM";
            String response = PaymentRails_Recipient.get(recipient_id, "logs");
            
            Console.WriteLine(response);
            Console.Read();
        }
    }

Response (200 Ok)

{
  "ok": true,
  "activities": [
    {
      "ip": "::ffff:10.0.2.2",
      "url": "/v1/recipients/R-91XNW81D85DMG/log",
      "method": "GET",
      "headers": {
        "host": "api.local.dev:3000",
        "connection": "keep-alive",
        "postman-token": "47cad157-855e-49fe-45d6-d61a02ffa802",
        "cache-control": "no-cache",
        "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
        "x-api-key": "pk_live_950093B81A79BB04F443688BEB80B12E",
        "content-type": "application/json",
        "accept": "*/*",
        "accept-encoding": "gzip, deflate, sdch",
        "accept-language": "en-US,en;q=0.8"
      },
      "request": "",
      "response": "{\"ok\":false,\"errors\":[{\"code\":\"not_found\",\"message\":\"Object not found\"}]}",
      "code": 404,
      "source": "api",
      "testMode": false,
      "createdAt": "2017-03-22T17:57:32.786Z"
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "records": 2
  }
}

You can retrieve a list of all activity related to a recipient by sending a GET request to the /recipients/:id/logs endpoint.

HTTP Request

GET https://api.paymentrails.com/v1/recipients/:id/logs

Fields Type Description
id string Resource ID
HTTP Code Description
200 All recipients
403 Invalid API key
404 Recipient not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Errors Example

If the recipient does not exist, the API will respond with an error. For example:

Response (404 Not Found)

{
  "ok": false,
  "errors": [
    {
      "code": "not_found",
      "message": "Object not found"
    }
  ]
}

Retrieve all payments

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X GET \
   https://api.paymentrails.com/v1/recipients/:id/payments
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Recipient.get('R-SBAHDK3DK5SMSUEM', callback, 'payments');
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$recipient_id = 'R-SBAHDK3DK5SMSUEM';

\paymentrails\Recipient::get($recipient_id,'payments');
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";

            String recipient_id = "R-SBAHDK3DK5SMSUEM";
            String response = PaymentRails_Recipient.get(recipient_id, "payments");
            
            Console.WriteLine(response);
            Console.Read();
        }
    }

Retrieve payments to this recipient

HTTP Request

GET https://api.paymentrails.com/v1/recipients/:id/payments

Fields Description
id
string
Resource ID

Response (200 Ok)

{
  "ok": true,
  "payments": [
    {
      "id": "P-91XNW3G14GG6M",
      "recipient": {
        "id": "R-91XNRUTFA9D00",
        "referenceId": "jsmith11@example.com",
        "email": "jsmith11@example.com",
        "name": "Eftakahirul Islam",
        "lastName": "Islam",
        "firstName": "Eftakahirul",
        "type": "individual",
        "status": "active",
        "language": "en",
        "complianceStatus": "verified",
        "dob": null,
        "updatedAt": "2017-03-20T19:06:40.937Z",
        "createdAt": "2017-03-17T20:10:45.818Z",
        "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
        "compliance": {
          "status": "verified",
          "checkedAt": "2017-03-20T19:06:23.916Z"
        },
        "payout": {
          "autoswitch": {
            "limit": 1000,
            "active": false
          },
          "holdup": {
            "limit": 1000,
            "active": false
          },
          "primary": {
            "method": "bank",
            "currency": {
              "currency": {}
            }
          },
          "method": "bank",
          "accounts": {
            "bank": {
              "institution": "123",
              "branch": "to remove",
              "currency": "CAD",
              "country": "CA",
              "name": "TD"
            }
          },
          "methodDisplay": "Bank Transfer"
        },
        "address": {
          "street1": "Apt# 14",
          "street2": null,
          "city": "",
          "postalCode": "H3WXXX",
          "phone": "",
          "country": "CA",
          "region": "QC"
        },
        "primaryCurrency": "USD"
      },
      "status": "pending",
      "sourceAmount": "100.10",
      "exchangeRate": "1.0000",
      "fees": "1.25",
      "recipientFees": "1.25",
      "targetAmount": "98.85",
      "fxRate": "2.000000",
      "memo": "Rain is for test",
      "processedAt": null,
      "createdAt": "2017-03-21T20:56:43.714Z",
      "updatedAt": "2017-03-21T21:10:05.874Z",
      "merchantFees": "0.00",
      "compliance": {
        "status": "pending",
        "checkedAt": null
      },
      "sourceCurrency": "CAD",
      "sourceCurrencyName": "Canadian Dollar",
      "targetCurrency": "CAD",
      "targetCurrencyName": "Canadian Dollar",
      "batch": {
        "id": "B-912PAFJDDWBM6",
        "createdAt": "2017-03-21T20:56:43.690Z",
        "updatedAt": "2017-03-21T21:10:05.890Z",
        "sentAt": null,
        "completedAt": null
      }
    },
    {
      "id": "P-91XNW38F4NPH8",
      "recipient": {
        "id": "R-91XNRUTFA9D00",
        "referenceId": "jsmith11@example.com",
        "email": "jsmith11@example.com",
        "name": "Eftakahirul Islam",
        "lastName": "Islam",
        "firstName": "Eftakahirul",
        "type": "individual",
        "status": "active",
        "language": "en",
        "complianceStatus": "verified",
        "dob": null,
        "updatedAt": "2017-03-20T19:06:40.937Z",
        "createdAt": "2017-03-17T20:10:45.818Z",
        "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
        "compliance": {
          "status": "verified",
          "checkedAt": "2017-03-20T19:06:23.916Z"
        },
        "payout": {
          "autoswitch": {
            "limit": 1000,
            "active": false
          },
          "holdup": {
            "limit": 1000,
            "active": false
          },
          "primary": {
            "method": "bank",
            "currency": {
              "currency": {}
            }
          },
          "method": "bank",
          "accounts": {
            "bank": {
              "institution": "123",
              "branch": "to remove",
              "currency": "CAD",
              "country": "CA",
              "name": "TD"
            }
          },
          "methodDisplay": "Bank Transfer"
        },
        "address": {
          "street1": "Apt# 14",
          "street2": null,
          "city": "",
          "postalCode": "H3WXXX",
          "phone": "",
          "country": "CA",
          "region": "QC"
        },
        "primaryCurrency": "USD"
      },
      "status": "pending",
      "sourceAmount": "100.10",
      "exchangeRate": "1.0000",
      "fees": "1.25",
      "recipientFees": "1.25",
      "targetAmount": "0.00",
      "fxRate": "2.000000",
      "memo": "Rain is for test",
      "processedAt": null,
      "createdAt": "2017-03-20T15:11:18.517Z",
      "updatedAt": "2017-03-20T15:11:18.517Z",
      "merchantFees": "0.00",
      "compliance": {
        "status": "pending",
        "checkedAt": null
      },
      "sourceCurrency": "CAD",
      "sourceCurrencyName": "Canadian Dollar",
      "targetCurrency": "CAD",
      "targetCurrencyName": "Canadian Dollar",
      "batch": {
        "id": "B-91XNW38F54Z04",
        "createdAt": "2017-03-20T15:11:18.486Z",
        "updatedAt": "2017-03-20T15:11:18.582Z",
        "sentAt": null,
        "completedAt": null
      }
    }
  ],
  "meta": {
    "page": 1,
    "pages": 1,
    "records": 2
  }
}
HTTP Code Description
200 Recipient’s payments
403 Invalid API key
404 Recipient not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Errors Example

If recipient doesn’t exist, API will respond with an error. For example:

Response (404 Not Found)

{
  "ok": false,
  "errors": [
    {
      "code": "not_found",
      "message": "Object not found"
    }
  ]
}

Recipient Account

By POST-ing a account method for a recipient, you are adding a new payment method (such as their bank account, their PayPal account, mobile money account, prepaid card, etc) to the recipient.

A recipient can have multiple accounts with different payout methods assigned, however only one (1) account can be their selected (“primary”) account at any time.

Multiple Account Available

Our philosophy is to give more choice of payout methods to users. What works for someone in San Francisco, London or Melbourne, might not be the best option for someone else in Jakarta, Nairobi or Mumbai. PayPal doesn’t support all countries, in fact, 97.5% of the worldwide population don’t have a PayPal account, and over 2 billion people don’t have a bank account. So clearly multiple payment options are needed to support a global business. Thats why we plan to support every major payout method, so your users have choice of what works best for them.

Account Attributes

Below is a list of currently active (live) payout type, and those that are on our future roadmap.

Payout Method Type Status Description Method
bank-transfer live Bank Transfers (includes local bank transfers to 60+ major countries, and bank wires to all other countries)
paypal live PayPal account
mobile-money coming soon Mobile Money
cash coming soon Cash Pick-up
debit-card coming soon Debit and Credit Cards (VISA and MasterCard branded)
check coming soon Paper Check / Cheque

Attributes

Fields Type Description
recipientAccountId string An unique identifier of account
type string Any of the live payout method type
currency string The code of currency
primary boolean To set account as primary
country string country code
accountHolderName string exact name of account owner/holder
accountNum string account number
bankId string bank information
branchId string Bank’s branch information
iban string IBAN information
swiftBic string swift code of bank
bankName string The name of Bank
bankAddress string A valid bank address
bankCity string A valid city where bank located
bankRegionCode string A valid region code where bank located
bankPostalCode string A valid postal code where bank located
emailAddress string A valid email address associated with recipient’s Paypal account

Create Account

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X POST \
  -d '{"type": "bank-transfer", ""primary": true, "country":"CA", "currency": "CAD", "accountNum": "604622847", "bankId": "123", "branchId": "47261",  "accountHolderName":"John Smith"}'
  https://api.paymentrails.com/v1/recipients/:id/accounts
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};
var body = {
        "type": "bank-transfer",
        "primary": "true",
        "country": "CA",
        "currency": "CAD",
        "accountNum": "012345678",
        "bankId": "004",
        "branchId": "47261",
        "accountHolderName": "John Smith"
}
PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails_RecipientAccounts.post('R-PuzPJLVYQXBbPSMQKwmJ5G', body, callback);

Example response (200 Ok)

{
  "ok": true
  "account": {
       "recipientAccountId": "A-UnukXDTbLtxtDLXVZGE9re",
       "primary": true,
       "currency": "CAD",
       "country": "CA",
       "type": "bank-transfer",
       "accountNum": "*****2847",
       "accountHolderName": "John Smith",
       "bankId": "123",
       "branchId": "47261",
       "bankName": "TD bank"
   }
}

POST-ing a account method to a recipient will add a new account method (such as their bank account, their PayPal account, mobile money account, prepaid card, etc) to the recipient.

A recipient can have multiple accounts with different payment methods assigned, however, only one (1) payment method can be their selected (“primary”) account at any time. If you add the account when creating the recipient, you don’t need to add it now.

HTTP Request

POST https://api.paymentrails.com/v1/recipients/:id/accounts

Right now, Payment Rails supports two types of payout methods: paypal (PayPal) & bank-transfer (Bank Transfers).

Fields Type Validation Description
id string required recipient Id
type string required payout method either paypal or bank-transfer
currency string required The code of currency
primary boolean required To set account as primary

Based on type, following field are required. Here, we are explaining both method types: paypal and bank-transfer

Bank Transfer

Fields Type Validation Description
country string required country code
accountHolderName string required exact name of account owner/holder
accountNum string required account number
bankId string required based on country bank information
branchId string required based on country Bank’s branch information
iban string required based on country IBAN information
swiftBic string required based on country swift code of bank

Paypal

You have add a valid paypal email address

Fields Type Validation Description
emailAddress string required A valid email address associated with recipient’s Paypal account

Example of code for paypal type account

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X POST \
  -d '{"type":"paypal", "primary": true, "currency": "CAD",  "emailAddress": "jsmithpaypal@example.com"}' https://api.paymentrails.com/v1/recipients/:id/accounts

Response (200 Ok)

{
  "ok": true,
  "account": {
    "type": "paypal",
    "emailAddress": "jsmithpaypal@example.com",
    "recipientAccountId": "A-7ccjKkGNyQRXRnEAfqTd7d",
    "primary": true,
    "currency": "CAD"
  }
}

Example of code for bank-transfer type account

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X POST \
  -d '{"type": "bank-transfer", ""primary": true, "country":"CA", "currency": "CAD", "accountNum": "604622847", "bankId": "123", "branchId": "47261",  "accountHolderName":"John Smith"}'
    https://api.paymentrails.com/v1/recipients/:id/accounts

Response (200 Ok)

{
  "ok": true
  "account": {
       "recipientAccountId": "A-UnukXDTbLtxtDLXVZGE9re",
       "primary": true,
       "currency": "CAD",
       "country": "CA",
       "type": "bank-transfer",
       "accountNum": "*****2847",
       "accountHolderName": "John Smith",
       "bankId": "123",
       "branchId": "47261",
       "bankName": "TD bank"
   }
}
HTTP Code Description
200 Payment successfully updated
403 Invalid API key
404 Object not found
406 One or more fields failed validation, see errors[] in response body
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
empty_field A field is required
invalid_field A field failed a validation check
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Delete Account

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X DELETE \
   https://api.paymentrails.com/v1/recipients/:id/accounts/:recipientAccountId
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails_RecipientAccounts.remove('R-PuzPJLVYQXBbPSMQKwmJ5G', 'A-KKHb8MpFvju6vDMBLPmtej', callback);

Example response (200 Ok)

{
    "ok": true,
    "object": "deleted"
}

Delete a recipient’s payout method

HTTP Request

DELETE https://api.paymentrails.com/v1/recipients/:id/accounts/:recipientAccountId

Fields Type Description
id string recipientId
recipientAccountId string recipientAccountId
HTTP Code Description
200 Payment successfully updated
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Retrieve Account

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X GET \
   https://api.paymentrails.com/v1/recipients/:id/accounts/:recipientAccountId
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails_RecipientAccounts.get('R-PuzPJLVYQXBbPSMQKwmJ5G', 'A-KKHb8MpFvju6vDMBLPmtej', callback);

Example response (200 Ok)

{
    "ok": true,
    "account": {
        "type": "paypal",
        "emailAddress": "rain123@gmail.com",
        "recipientAccountId": "A-7ccjKkGNyQRXRnEAfqTd7d",
        "primary": false,
        "currency": "CAD"
    }
}

Retrieve a recipient’s payout method

HTTP Request

GET https://api.paymentrails.com/v1/recipients/:id/accounts/:recipientAccountId

Fields Type Description
id string recipientId
recipientAccountId string recipientAccountId
HTTP Code Description
200 Payment successfully updated
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Update Account

Update existing PayPal address

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X PATCH \
  -d '{"emailAddress": "testpaypal@example.com"}}}'
  https://api.paymentrails.com/v1/recipients/R-SBAHDK3DK5SMSUEM/accounts/A-7ccjKkGNyQRXRnEAfqTd7d
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
var body = {
     "primary": "false",
}
PaymentRails_RecipientAccounts.patch('R-PuzPJLVYQXBbPSMQKwmJ5G', 'A-KKHb8MpFvju6vDMBLPmtej', body,callback);

Example response (200 Ok)

{
  "ok": true,
  "object": "updated"
}

Update existing Bank Transfer method

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X PATCH \
  -d '{"accountNum": "60567"}'
  https://api.paymentrails.com/v1/recipients/R-SBAHDK3DK5SMSUEM/accounts/A-10ccjKrtufcnjgXRnEAfqTd7d

Set primary for an account

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X PATCH \
  -d '{"primary": true}'
  https://api.paymentrails.com/v1/recipients/R-SBAHDK3DK5SMSUEM/accounts/A-10ccjKrtufcnjgXRnEAfqTd7d

Example response (200 Ok)

{
  "ok": true,
  "object": "updated"
}

Update a payout method for a recipient. You can update existing primary method.

HTTP Request

PATCH https://api.paymentrails.com/v1/recipients/:id/accounts/:recipientAccountId

Fields Type Description
id string recipientId
recipientAccountId string recipientAccountId
HTTP Code Description
200 Payment successfully updated
403 Invalid API key
404 Object not found
406 One or more fields failed validation, see errors[] in response body
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
empty_field A field is required
invalid_field A field failed a validation check
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Payments

The payment object describes a payment. Payments are sent to a recipient via the recipient’s chosen payout method, such as: bank account, PayPal, check, mobile money, cash pick-up, credit card, or debit card. If no payment method is setup, the payment will not be processed.

A Batch is a group of Payments. Payments are added to a batch prior to being processed. If your business does regularly scheduled payouts, such as once per day, once per week, every 2 weeks, or even monthly, then using batches will be great for you.

A batch can be made up of just 1 payment, or 100 payments, or hundreds of thousands of payments (there are no upper limits).

Batches also allow you to manually review and approve your payments before processing, if you prefer. This is handy if you conduct some additional fraud reviews on your payouts before processing, or if your company CFO or a senior manager is responsible for approving payouts before they go out.

There are 4 main steps for handling a batch:

Step 1: Create a batch

Firstly, when you Create a batch, the system will automatically open a new batch and assign a unique batchId which is generated by our system. The format of all Batch IDs are “B-0A0A0A0A0A0A0A0A”, with the ‘B-’ prefix indicating Batch, followed by 16 alphanumeric digits.

When you create a batch, you will also send us the details for your payments. This includes at a minimum the recipientId, amount and currency for all the payments for that batch.

Note: You can also use our online Dashboard portal to manually create a batch of payments by uploading a file of payments in .csv, .xlx, or .xlsx file format, or manually adding payments into a batch.

Step 2: Generate Quote of FX rates

After creating the batch, you will need to send a POST request to the /batches/:id/generate-quote API to get the live exchange rates for payments that involve a currency conversion.

The system will update the exchange rate for all payments with bank-transfer type payout method. (Note that PayPal payments will not be updated, as PayPal handles the FX rates). You can generate a quote multiple times to get the latest live exchange rates, up until the batch has started processing.

Step 3: Check account balance

When the batch is created, the system will automatically check the balance of your account to see if it is sufficient to cover the costs of the payouts plus any transaction fees. If your account balance is not sufficient, the batch will remain pending until your account is funded. You can see your account balance in the Dashboard under the ‘Balance’ tab, which is updated in real time. You can also get your account balance by sending a GET request to the /balance endpoint. We will send an automatic notification to you by your chosen method (email, text message, or Slack) to inform you if you need to add funds to your account to process the batch.

Step 4: Process the batch

Once the batch is created, and there is ample funds in your account balance to cover the batch, then the batch can be processed. You will need to send a POST request to the /batches/:id/start-processing API to commence processing of the batch of payments.

Step 5: Summary of the batch

You can retrieve a summary of the batch, including the status and details of all the payments in the batch, by sending a GET request to the /batch/:id/summary endpoint.

If you wish to get the details of a specific payment within the batch, you can send a GET request to the /payments/:id endpoint.

Create a batch

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X POST \
  -d '{"payments":[{"recipient":{"id":"R-SBAHDK3DK6M7SUEM"},"sourceAmount":"65","memo":"","sourceCurrency":"CAD"}]}' \
  https://api.paymentrails.com/v1/batches
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};
var body = {
        "payments": [{
            "recipient": {
                "id": "R-SBAHDK3DK6M7SUEM"
            },
            "sourceAmount": "65",
            "sourceCurrency": "CAD"
        }]
    };
PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Batch.post(callback, body);
require 'payment_rails'

payments = [
  {recipient: 1, amount: 100, currency: "USD"},
  {recipient: 2, amount: 200, currency: "CAD"}
]

client = PaymentRails.connect(api_key: "<YOUR-API-KEY>")

client.batches.create(recipient)
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$body = array(
      'sourceCurrency' => 'CAD',
      'payments' => [array(
        'recipient' => array(
            'id' => 'R-SBAHDK3DK6M7SUEM'),
        'sourceAmount' => "65",
        'memo'=>'')]
      );

$response = \paymentrails\Batch::post($body);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";

            Recipient recipient = new Recipient("R-SBAHDK3DK6M7SUEM", null, null, null, null, null, null, null, null, null, null, null, null, null, null);

            Payment payment = new Payment(recipient, 65, null, 0, null, 0, 0, 0, 0, null, null, null, 0, null, null, null,null,null);
            
            List<Payment> payments = new List<Payment>();
            payments.add(payment);

            Batch batch = new Batch(null, payments, CAD, 0, 0, null, null, null, null, null, null);
            
            Batch response = PaymentRails_Batch.post(batch);

            Console.WriteLine(response);
            Console.Read();
        }
    }

Example response (200 Ok)

{
  "ok": true,
  "batch": {
    "id": "B-91XP0YUQ2X462",
    "status": "open",
    "amount": "8.75",
    "totalPayments": "2",
    "currency": "CAD",
    "description": "Weekly Payouts on 2017-2-27",
    "sentAt": null,
    "completedAt": null,
    "createdAt": "2017-03-27T20:19:47.378Z",
    "updatedAt": "2017-03-27T20:19:47.518Z"
  }
}

To create a Batch send a POST request to the /batches endpoint and include the payments details in the request body. The Batch and each Payment within the batch will be assigned and represented by an auto-generated ID (batchId and paymentId) which can be used to retrieve or update payment or batch details at a later time.

HTTP Request

POST https://api.paymentrails.com/v1/batches

Fields Type Description
sourceCurrency string You have to add sourceCurrency. The code of currency. If you don’t add here, then you must have to mention in each payments
description string
optional
Any description for the batch
payments array Array of payments
payments[].recipient object
payments[].recipient.id string Recipient ID
payments[].recipient.email string You need to add id or email. But if you add id, it has to be valid email address that associated to recipients
payments[].sourceAmount string You need either sourceAmount or targetAmount
payments[].targetAmount string You need either sourceAmount or targetAmount
payments[].memo string
optional
Description of payment
HTTP Code Description
200 Batch successfully updated
403 Invalid API key
406 One or more fields failed validation, see errors[] in response body
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
empty_field A field is required
invalid_field A field failed a validation check
invalid_status Invalid Status
invalid_api_key Invalid API key
internal_server_error Internal server errors

Retrieve a batch

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X GET \
   https://api.paymentrails.com/v1/batches/B-91XNYHJJAWY50
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Batch.get('B-91XNYHJJAWY50', callback);
require 'payment_rails'

batch_id = "B-91XNYHJJAWY50"
client = PaymentRails.connect(api_key: "<YOUR-API-KEY>")

batch = client.batches.find(batch_id)

puts batch
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

$batch_id = 'B-91XNYHJJAWY50';
\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');

$response = \paymentrails\Batch::get($batch_id);

echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            String batch_id = "B-91XNYHJJAWY50";
            Batch response = PaymentRails_Batch.get(batch_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }

Example response (200 Ok)

{
  "ok": true,
  "batch": {
    "id": "B-91XNYHJJAWY50",
    "status": "open",
    "amount": "98.75",
    "totalPayments": 2,
    "currency": "CAD",
    "description": "Weekly Payouts on 2017-2-23",
    "sentAt": null,
    "completedAt": null,
    "createdAt": "2017-03-23T15:21:51.171Z",
    "updatedAt": "2017-03-23T15:21:51.254Z",
    "payments": {
      "payments": [
        {
          "id": "P-91XNYHJJD5F26",
          "recipient": {
            "id": "R-91XNRUTFA9D00",
            "referenceId": "jsmith11@example.com",
            "email": "jsmith11@example.com",
            "name": "John Smith",
            "status": "active",
            "country": "Canada"
          },
          "method": "bank",
          "methodDisplay": "Bank Transfer",
          "status": "pending",
          "sourceAmount": "0.00",
          "targetAmount": "100.00",
          "isSupplyPayment": true,
          "memo": "Rain is for test 2",
          "fees": "1.25",
          "recipientFees": "0.00",
          "exchangeRate": "1.0000",
          "processedAt": null,
          "merchantFees": "1.25",
          "sourceCurrency": "CAD",
          "sourceCurrencyName": "Canadian Dollar",
          "targetCurrency": "CAD",
          "targetCurrencyName": "Canadian Dollar",
          "compliance": {
            "status": "pending",
            "checkedAt": null
          }
        },
        {
          "id": "P-91XNYHJJB9NKU",
          "recipient": {
            "id": "R-91XNRUTFA9D00",
            "referenceId": "jsmith11@example.com",
            "email": "jsmith11@example.com",
            "name": "Eftakahirul Islam",
            "status": "active",
            "country": "Canada"
          },
          "method": "bank",
          "methodDisplay": "Bank Transfer",
          "status": "pending",
          "sourceAmount": "100.00",
          "targetAmount": "0.00",
          "isSupplyPayment": false,
          "memo": "Rain is for test 1",
          "fees": "1.25",
          "recipientFees": "1.25",
          "exchangeRate": "1.0000",
          "processedAt": null,
          "merchantFees": "0.00",
          "sourceCurrency": "CAD",
          "sourceCurrencyName": "Canadian Dollar",
          "targetCurrency": "CAD",
          "targetCurrencyName": "Canadian Dollar",
          "compliance": {
            "status": "pending",
            "checkedAt": null
          }
        }
      ],
      "meta": {
        "page": 1,
        "pages": 1,
        "records": 2
      }
    }
  }
}

You can retrieve details of a Batch of payments by sending a GET request to the /batches/:id endpoint.

HTTP Request

GET https://api.paymentrails.com/v1/batches/:id

Fields Type Description
id string Resource ID
HTTP Code Description
200 Batch object
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Update a batch

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X PATCH \
  -d '{"payments":[{"recipient":{"id":"R-3DF7FAF680739541","email":"jsmith@example.com"},"sourceAmount":65,"memo":"Salaey","sourceCurrency":"CAD"}], "update_payments":[{"id":"P-1F7FCC8778A8","sourceAmount":999}], "remove_payments":[{"id":"P-6FBAB273B628"}]}' \
  https://api.paymentrails.com/v1/batches/:batch-id
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};
var body = {
        "update_payments": [{
            "id": "P-L51umK3ieSpBty3uCsFtzK",
            "sourceAmount": 999
        }]
    };
PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Batch.patch('B-91XNYHJJAWY50', body, callback);
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
  $body = array(
        'update_payments' => [array(
        'id' => 'P-1F7FCC8778A8',
        'sourceAmount' => 999)]
    );
    $batch_id = "B-91XNYHJJAWY50";

$response = \paymentrails\Batch::patch($batch_id, $body);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            Payment payment = new Payment(null, 999, null, 0, null, 0, 0, 0, 0, null, null, null, 0, null, null, "P-1F7FCC8778A8",null,null);
            
            List<Payment> payments = new List<Payment>();
            payments.add(payment);

            Batch batch = new Batch(null, payments, null, 0, 0, null, null, null, null, null, "B-91XNYHJJAWY50");

            String response = PaymentRails_Batch.patch(batch);

            Console.WriteLine(response);
            Console.Read();
        }
    }

You are able to edit / update a batch if it has not yet been processed, i.e. the batch status is ‘open’. We like to call this endpoint ‘Patch the Batch’. :)

With this API call you can:

HTTP Request

PATCH https://api.paymentrails.com/v1/batches/:batch-id

Example response (200 Ok)

{
  "ok": true,
  "object": "updated"
}
Fields Type Description
batch-id string Resource ID
HTTP Code Description
200 Batch successfully updated
403 Invalid API key
404 Object not found
406 One or more fields failed validation, see errors[] in response body
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object not found
empty_field A field is required
invalid_field A field failed a validation check
invalid_status Invalid Status
invalid_api_key Invalid API key
internal_server_error Internal server errors

Delete a batch

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X DELETE \
   https://api.paymentrails.com/v1/batches/:batch-id
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Batch.remove('B-91XNYHJJAWY50', callback);
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$batch_id = 'B-91XNYHJJAWY50';

$response = \paymentrails\Batch::delete($batch_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            String batch_id = "B-91XPJPHF4T3P8";
            String response = PaymentRails_Payment.delete(batch_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }

Expected Response (204 No Content)

You can delete an existing batch by sending a DELETE request to the /batches/:id endpoint.

Note that you can only delete a batch that is in a pending status and has not yet been processed. Once a batch is processed, you are unable to delete the batch. If you processed a batch in error and wish to stop it, please contact support immediately and we will assist as best we can.

HTTP Request

DELETE https://api.paymentrails.com/v1/batches/:id

{
  "ok": true,
  "object": "updated"
}
Fields Type Description
id string Resource ID
HTTP Code Description
200 Batch successfully deleted
403 Invalid API key
404 Object not found
406 Invalid status
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_status Invalid Status
invalid_api_key Invalid API key
internal_server_error Internal server errors

Delete multiple batches

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X DELETE \
   -d '{"ids": [:batch-id, :batch-id]}' \
   https://api.paymentrails.com/v1/batches

Expected Response (204 No Content)

You can delete multiple batches by sending a DELETE request to the /batches endpoint.

Note that you can only delete batches those are in pending status and has not yet been processed. Once a batch is processed, you are unable to delete the batch. If you processed a batch in error and wish to stop it, please contact support immediately and we will assist as best we can.

HTTP Request

DELETE https://api.paymentrails.com/v1/batches

{
  "ok": true,
  "object": "deleted"
}
Fields Type Description
id string Resource ID
HTTP Code Description
200 Batch successfully deleted
403 Invalid API key
404 Object not found
406 Invalid status
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_status Invalid Status
invalid_api_key Invalid API key
internal_server_error Internal server errors

List all batches

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X GET \
  https://api.paymentrails.com/v1/batches?page=1&pageSize=10
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Batch.query(callback, 1, 10,"John");
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');

$response = \paymentrails\Batch::query(1,10);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            List<Batch> batches = PaymentRails_Batch.query("John",1,10);

            foreach(Batch batch in batches){
                Console.WriteLine(batches);
            }
            Console.Read();
        }
    }

Expected response (200 Ok)

{
  "ok": true,
  "batches": [
    {
      "id": "B-10FBF1BFHF01E931",
      "dealId": "2282",
      "status": "accepted",
      "amount": "109.75",
      "totalPayments": 1,
      "currency": "CAD",
      "description": "Weekly Payouts on 2017-0-11",
      "sentAt": null,
      "completedAt": null,
      "createdAt": "2017-01-11T23:30:52.974Z",
      "updatedAt": "2017-01-11T23:31:38.954Z"
    },
    {
      "id": "B-F4DBEEFE896842F3",
      "dealId": "2281",
      "status": "complete",
      "amount": "109.75",
      "totalPayments": 1,
      "currency": "CAD",
      "description": "Weekly Payouts on 2017-0-11",
      "sentAt": "2017-01-11T23:18:48.091Z",
      "completedAt": "2017-01-11T23:18:49.222Z",
      "createdAt": "2017-01-11T23:18:37.976Z",
      "updatedAt": "2017-01-11T23:18:49.222Z"
    }
  ]
}

You can retrieve all batches by sending a GET request to the /batches endpoint.

HTTP Request

GET https://api.paymentrails.com/v1/batches?page=1&pageSize=10

Query Param Type Description
page int The page number (default: 1)
pageSize int Number of records in a page (default: 10)
search string Wildcard search of the batch-id
HTTP Code Description
200 List of batches
403 Invalid API key
500 Internal error
Error Code Description
invalid_api_key Invalid API key
internal_server_error Internal server errors

Create a payment

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X POST \
   -d '{"recipient":{"id":"R-91XNJBKM30F06"},"sourceAmount":"100.10","memo":"Freelance payment"}' \
   https://api.paymentrails.com/v1/batches/B-91XP0YUQ2X462/payments
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};
var body = {
        "recipient": {
            "id": "R-PuzPJLVYQXBbPSMQKwmJ5G"
        },
        "sourceAmount": "100.10",
        "sourceCurrency": "CAD",
        "memo": "Freelance payment"
    };
PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');

PaymentRails.Payment.post('B-LfoeSofUYdPpZBULbezULe', body, callback);
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$body = array(
        'recipient' => array(
            'id' => 'R-91XNJBKM30F06'),
        'sourceAmount' => '100.10',
        'memo' => 'Freelance payment',
    );
$batch_id = 'B-91XP0YUQ2X462';

$response = \paymentrails\Payment::post($body, $batch_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            Recipient recipient = new Recipient("R-91XNJBKM30F06", null, null, null, null, null, null, null, null, null, null, null, null, null, null);
            
            Payment payment = new Payment(recipient, 100.10, "Freelance payment", 0, null, 0,0,0,0,null,null,null,0,null,"B-91XP0YUQ2X462" ,null,null,null);

            Payment response = PaymentRails_Payment.post(payment);

            Console.WriteLine(response);
            Console.Read();
        }
    }

To create a payment under a batch send a POST request to the /batches/:id/payments endpoint and include the payments details in the request body. A payment will be created and added to the batch. An auto-generated ID (paymentId) will be generated which can be used to retrieve or update payment or batch details at a later time.

HTTP Request

POST https://api.paymentrails.com/v1/batches/:id/payments

Fields Type Description
id string Resource ID
recipient object
recipient.id string Recipient ID
recipient.email string You need to add id or email. But if you add id, it has to be valid email address that associated to recipients
sourceAmount string You need either sourceAmount or targetAmount
targetAmount string You need either sourceAmount or targetAmount
memo string
optional
Description of payment

Example response (200 Ok)

{
  "ok": true,
  "payment": {
    "id": "P-91XP0ZH444G0C",
    "recipient": {
      "id": "R-91XNJBKM30F06",
      "referenceId": "jsmith@example.com",
      "email": "jsmith@example.com",
      "name": "John Smith",
      "lastName": "Smith",
      "firstName": "John",
      "type": "individual",
      "status": "active",
      "language": "en",
      "complianceStatus": "verified",
      "dob": null,
      "updatedAt": "2017-03-20T19:06:40.937Z",
      "createdAt": "2017-03-17T20:10:45.818Z",
      "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "payout": {
        "autoswitch": {
          "limit": 1000,
          "active": false
        },
        "holdup": {
          "limit": 1000,
          "active": false
        },
        "primary": {
          "method": "bank",
          "currency": {
            "currency": {
              "code": "CAD",
              "name": "Canadian Dollar"
            }
          }
        },
        "method": "bank",
        "accounts": {
          "bank": {
            "institution": "123",
            "branch": "to remove",
            "currency": "CAD",
            "country": "CA",
            "name": "TD"
          }
        },
        "methodDisplay": "Bank Transfer"
      },
      "primaryCurrency": "CAD"
    },
    "status": "pending",
    "sourceAmount": "100.10",
    "exchangeRate": "1.0000",
    "fees": "1.25",
    "recipientFees": "1.25",
    "targetAmount": "0.00",
    "fxRate": "2.000000",
    "memo": "Rain is for test",
    "processedAt": null,
    "createdAt": "2017-03-27T20:51:39.567Z",
    "updatedAt": "2017-03-27T20:51:39.567Z",
    "merchantFees": "0.00",
    "compliance": {
      "status": "pending",
      "checkedAt": null
    },
    "sourceCurrency": "CAD",
    "sourceCurrencyName": "Canadian Dollar",
    "targetCurrency": "CAD",
    "targetCurrencyName": "Canadian Dollar"
  }
}
HTTP Code Description
200 Batch successfully deleted
403 Invalid API key
404 Object not found
406 Validation error
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Retrieve a payment

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X GET \
  https://api.paymentrails.com/v1/batches/:batch-id/payments/:payment-id
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');

PaymentRails_Payment.get('P-91XPJPHF5CK3Y', callback);
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
\paymentrails\Payment::setBatchId('B-91XPJPHF4T3P8');
$payment_id = 'P-91XPJPHF5CK3Y';

$response = \paymentrails\Payment::get($payment_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            String payment_id = "P-91XPJPHF5CK3Y";
            Payment response = PaymentRails_Payment.get(payment_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }

Expected response (200 Ok)

{
  "ok": true,
  "payment": {
    "id": "P-91XNW3G14GG6M",
    "recipient": {
      "id": "R-91XNRUTFA9D00",
      "referenceId": "jsmith11@example.com",
      "email": "jsmith11@example.com",
      "name": "John Smith",
      "lastName": "Smith",
      "firstName": "John",
      "type": "individual",
      "status": "active",
      "language": "en",
      "complianceStatus": "verified",
      "dob": null,
      "updatedAt": "2017-03-20T19:06:40.937Z",
      "createdAt": "2017-03-17T20:10:45.818Z",
      "gravatarUrl": "https://s3.amazonaws.com/static.api.paymentrails.com/icon_user.svg",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "payout": {
        "autoswitch": {
          "limit": 1000,
          "active": false
        },
        "holdup": {
          "limit": 1000,
          "active": false
        },
        "primary": {
          "method": "bank",
          "currency": {
            "currency": {}
          }
        },
        "method": "bank",
        "accounts": {
          "bank": {
            "institution": "123",
            "branch": "to remove",
            "currency": "CAD",
            "country": "CA",
            "name": "TD"
          }
        },
        "methodDisplay": "Bank Transfer"
      },
      "address": {
        "street1": "Apt# 14",
        "street2": null,
        "city": "",
        "postalCode": "H3WXXX",
        "phone": "",
        "country": "CA",
        "region": "QC"
      },
      "primaryCurrency": "USD"
    },
    "status": "processed",
    "sourceAmount": "100.10",
    "exchangeRate": "1.0000",
    "fees": "1.25",
    "recipientFees": "1.25",
    "targetAmount": "98.85",
    "fxRate": "2.000000",
    "memo": "Rain is for test",
    "processedAt": "2017-03-28T04:09:02.955Z",
    "createdAt": "2017-03-21T20:56:43.714Z",
    "updatedAt": "2017-03-28T04:09:02.955Z",
    "merchantFees": "0.00",
    "compliance": {
      "status": "verified",
      "checkedAt": "2017-03-28T04:08:53.297Z"
    },
    "sourceCurrency": "CAD",
    "sourceCurrencyName": "Canadian Dollar",
    "targetCurrency": "CAD",
    "targetCurrencyName": "Canadian Dollar",
    "batch": {
      "id": "B-912PAFJDDWBM6",
      "createdAt": "2017-03-21T20:56:43.690Z",
      "updatedAt": "2017-03-28T04:09:02.966Z",
      "sentAt": "2017-03-28T04:08:52.634Z",
      "completedAt": "2017-03-28T04:08:54.353Z"
    }
  }
}

You can retrieve a single payment by sending a GET request to the batches/:batch-id/payments/:payment-id endpoint. It will return the details of that payment under a batch.

HTTP Request

GET https://api.paymentrails.com/v1/batches/:batch-id/payments/:payment-id

Fields Type Description
batch-id string Resource ID
payment-id string Resource ID
HTTP Code Description
200 Payment object
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Update a payment

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X PATCH \
   -d '{"sourceAmount":"900.90"}' \
   https://api.paymentrails.com/v1/batches/:batch-id/payments/:payment-id
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');

var body = { "sourceAmount": "900.90" };
PaymentRails_Payment.setBatchId('B-LfoeSofUYdPpZBULbezULe');
PaymentRails_Payment.patch('P-RNNZME2kkuAKqiiz6iTFrX', body, callback);
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
\paymentrails\Payment::setBatchId('B-91XPJPHF4T3P8');
$body = array("sourceAmount" => "900.90");
$payment_id = 'P-912PWKHZ312JW';

$response = \paymentrails\Payment::patch($payment_id, $body);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            Payment payment = new Payment(null, 900.90, null, 0, null, 0,0,0,0,null,null,null,0,null,"B-91XPJPHF4T3P8","P-912PWKHZ312JW",null,null);

            String response = PaymentRails_Payment.patch(payment);

            Console.WriteLine(response);
            Console.Read();
        }
    }

To update a payment under a batch send a PATCH request to the /batches/:id/payments/:payment-id endpoint and include the payments details in the request body.

HTTP Request

PATCH https://api.paymentrails.com/v1/batches/:batch-id/payments/:payment-id

Fields Type Description
batch-id string Resource ID
payment-id string Resource ID
sourceAmount string A valid sourceAmount
targetAmount string A valid target
memo string Description of payment

Response (200 Ok)

{
  "ok": true,
  "object": "updated"
}
HTTP Code Description
200 Payment successfully updated
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_status Invalid Status
invalid_api_key Invalid API key
internal_server_error Internal server errors

Delete a payment

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X DELETE \
   https://api.paymentrails.com/v1/batches/:batch-id/payments/:payment-id
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');

PaymentRails_Payment.setBatchId('B-LfoeSofUYdPpZBULbezULe');
PaymentRails_Payment.remove('P-RNNZME2kkuAKqiiz6iTFrX', callback);
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');

\paymentrails\Payment::setBatchId('B-91XPJPHF4T3P8');
$payment_id = 'P-912PWKHZ312JW';

$response = \paymentrails\Payment::delete($payment_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            String payment_id = "P-912PWKHZ312JW";
            String batch_id = "B-91XPJPHF4T3P8";
            String response = PaymentRails_Payment.delete(payment_id, batch_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }

To delete a payment under a batch send a DELETE request to the /batches/:batch-id/payments/:payment-id endpoint.

HTTP Request

DELETE https://api.paymentrails.com/v1/batches/:id/payments/:payment-id

Fields Type Description
batch-id string Resource ID
payment-id string Resource ID

Response (200 Ok)

{
  "ok": true,
  "object": "deleted"
}
HTTP Code Description
200 Payment successfully deleted
403 Invalid API key
404 Object not found
406 invalid status
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_status Invalid Status
invalid_api_key Invalid API key
internal_server_error Internal server errors

List all payments

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X GET \
   https://api.paymentrails.com/v1/batches/:batch-id/payments
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');

PaymentRails_Payment.setBatchId('B-LfoeSofUYdPpZBULbezULe');
PaymentRails_Payment.query(callback, 1, 10, 'John');
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
\paymentrails\Payment::setBatchId('B-912PWJGD8RZ7J');

$response = \paymentrails\Payment::query(1,10);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            String batch_id = "B-91XPJPHF4T3P8";
            List<Payment> payments = PaymentRails_Payment.query("John",1,10 batch_id);

            foreach(Payment payment in payments){
                Console.WriteLine(payment);
            }
            Console.Read();
        }
    }

Expected response (200 Ok)

You can retrieve all payments from an existing batch by sending a GET request to the /batches/:batch-id/payments endpoint.

HTTP Request

GET https://api.paymentrails.com/v1/batches/:batch-id/payments?page=1&pageSize=10

{
   "ok":true,
   "payments":[
      {
         "id":"P-91XNYHJJD5F26",
         "recipient":{
            "id":"R-91XNRUTFA9D00",
            "referenceId":"jsmith11@example.com",
            "email":"jsmith11@example.com",
            "name":"John Smith",
            "status":"active",
            "country":"Canada"
         },
         "method":"bank",
         "methodDisplay":"Bank Transfer",
         "status":"pending",
         "sourceAmount":"0.00",
         "targetAmount":"100.00",
         "isSupplyPayment":true,
         "memo":"Rain is for test 2",
         "fees":"1.25",
         "recipientFees":"0.00",
         "exchangeRate":"1.0000",
         "processedAt":null,
         "merchantFees":"1.25",
         "sourceCurrency":"CAD",
         "sourceCurrencyName":"Canadian Dollar",
         "targetCurrency":"CAD",
         "targetCurrencyName":"Canadian Dollar",
         "compliance":{
            "status":"pending",
            "checkedAt":null
         }
      },
      {
         "id":"P-91XNYHJJB9NKU",
         "recipient":{
            "id":"R-91XNRUTFA9D00",
            "referenceId":"jsmith11@example.com",
            "email":"jsmith11@example.com",
            "name":"Eftakahirul Islam",
            "status":"active",
            "country":"Canada"
         },
         "method":"bank",
         "methodDisplay":"Bank Transfer",
         "status":"pending",
         "sourceAmount":"100.00",
         "targetAmount":"0.00",
         "isSupplyPayment":false,
         "memo":"Rain is for test 1",
         "fees":"1.25",
         "recipientFees":"1.25",
         "exchangeRate":"1.0000",
         "processedAt":null,
         "merchantFees":"0.00",
         "sourceCurrency":"CAD",
         "sourceCurrencyName":"Canadian Dollar",
         "targetCurrency":"CAD",
         "targetCurrencyName":"Canadian Dollar",
         "compliance":{
            "status":"pending",
            "checkedAt":null
         }
      }
   ],
   "meta":{
      "page":1,
      "pages":1,
      "records":2
   }
}
Fields Type Description
batch-id string Resource ID
Query Param Type Description
page int The page number (default: 1)
pageSize int Number of records in a page (default: 10)
search string Wildcard search of the batch-id
HTTP Code Description
200 List of payments
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object doesn’t exist
invalid_api_key Invalid API key
internal_server_error Internal server errors

Generate quote

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X POST \
  https://api.paymentrails.com/v1/batches/:id/generate-quote
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Batch.generateQuote(callback, 'B-91XNYHJJAWY50');
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$batch_id = 'B-91XNYHJJAWY50';

$response = \paymentrails\Batch::generateQuote($batch_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            String batch_id = "B-91XNYHJJAWY50";
            String response = PaymentRails_Batch.generateQuote(batch_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }

Example response (200 Ok)

{
  "ok": true,
  "batch": {
    "id": "B-91XP0YUQ2X462",
    "status": "open",
    "amount": "8.75",
    "totalPayments": 2,
    "currency": "CAD",
    "description": "Weekly Payouts on 2017-2-27",
    "sentAt": null,
    "completedAt": null,
    "createdAt": "2017-03-27T20:19:47.378Z",
    "updatedAt": "2017-03-27T20:19:47.518Z"
  }
}

To generate a quote of a Batch send a POST request to the /batches/:id/generate-quote endpoint. It will update all the exchangeRate and amounts in all the payments which incur a currency conversion, i.e. you are sending to a different currency.

HTTP Request

POST https://api.paymentrails.com/v1/batches/:id/generate-quote

Fields Type Description
id string Resource ID
HTTP Code Description
200 Batch successfully updated
403 Invalid API key
404 Object not found
406 Quote is expired or batch’s status is incorrect, see errors[] in response body
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object not found
expired_quote Quote is expired
invalid_status Invalid Status
invalid_api_key Invalid API key
internal_server_error Internal server errors

Batch summary

curl \
   -H "Content-Type: application/json" \
   -H "X-API-Key: <YOUR-API-KEY>" \
   -X GET \
   https://api.paymentrails.com/v1/batches/:batch-id/summary
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$batch_id = 'B-91XPJPHF4T3P8';

$response = \paymentrails\Batch::summary($batch_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            String batch_id = "B-91XPJPHF4T3P8";
            String response = PaymentRails_Payment.summary(batch_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }

Example response (200 Ok)

{
  "ok": true,
  "batchSummary": {
    "id": "B-924AD89DGH9E929F1",
    "processed_by": "API",
    "errors": [],
    "serverTime": "2017-01-13T19:09:28.331Z",
    "status": "open",
    "currency": "CAD",
    "description": "Weekly Payouts on 2017-0-4",
    "sentAt": null,
    "completedAt": null,
    "createdAt": "2017-01-04T17:32:40.658Z",
    "updatedAt": "2017-01-04T17:32:55.468Z",
    "quoteExpiredAt": "2017-01-04T19:22:55.456Z",
    "methods": {
      "paypal": {
        "count": 0,
        "value": 0,
        "fees": 0,
        "recipientFees": 0,
        "merchantFees": 0,
        "net": 0,
        "accountType": "Gateway",
        "displayName": "PayPal"
      },
      "bank-transfer": {
        "count": 1,
        "value": 15,
        "fees": 1.25,
        "recipientFees": 1.25,
        "merchantFees": 0,
        "net": 15,
        "accountType": "PaymentRails",
        "displayName": "Bank Transfer"
      }
    },
    "PaymentRailsTotal": {
      "count": 1,
      "value": 15,
      "fees": 1.25,
      "recipientFees": 1.25,
      "merchantFees": 0,
      "net": 15
    },
    "GatewayTotal": {
      "count": 0,
      "value": 0,
      "fees": 0,
      "recipientFees": 0,
      "merchantFees": 0,
      "net": 0
    },
    "total": {
      "count": 1,
      "value": 15,
      "fees": 1.25,
      "recipientFees": 1.25,
      "merchantFees": 0,
      "net": 15
    },
    "merchantBalances": {
      "GatewayTotal": 0,
      "PaymentRailsTotal": 0
    },
    "enoughFunds": false
  }
}

You can retrieve a summary of a batch, including the details of all the payments in the batch, by sending a GET request to the /batch/:batch-id/summary endpoint.

HTTP Request

GET https://api.paymentrails.com/v1/batches/:batch-id/summary

Fields Type Description
batch-id string Resource ID
HTTP Code Description
200 Batch successfully updated
403 Invalid API key
404 Object not found
406 One or more fields failed validation, see errors[] in response body
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object not found
expired_quote Quote is expired
invalid_status Invalid Status

Process a batch

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X POST \
  https://api.paymentrails.com/v1/batches/:batch-id/start-processing
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Batch.processBatch(callback, 'B-91XNYHJJAWY50');
require 'payment_rails'

batch_id = "a123"
client = PaymentRails.connect(api_key: "<YOUR-API-KEY>")

client.batches.start_processing!(batch_id)
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');
$batch_id = 'B-91XNYHJJAWY50';

$response = \paymentrails\Batch::startProcessing($batch_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    { 
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            
            String batch_id = "B-91XNYHJJAWY50";
            String response = PaymentRails_Batch.processBatch(batch_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }
{
  "ok": true,
  "batch": {
    "id": "B-91XP0YUQ2X462",
    "status": "processing",
    "amount": "8.75",
    "totalPayments": 2,
    "currency": "CAD",
    "description": "Weekly Payouts on 2017-2-27",
    "sentAt": "2017-03-28T04:08:52.634Z",
    "completedAt": null,
   "createdAt": "2017-03-27T20:19:47.378Z",
    "updatedAt": "2017-03-28T04:08:52.634Z"
  }
}

To start processing a specific batch, send a POST request to the /batches/:batch-id/start-processing endpoint.

HTTP Request

POST https://api.paymentrails.com/v1/batches/:id/start-processing

Fields Type Description
batch-id string Resource ID
HTTP Code Description
200 Batch successfully porcessed
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object not found
invalid_status Invalid Status
invalid_api_key Invalid API key
internal_server_error Internal server errors

Balances

Balances relate to your business (merchant) account balances. You can retrieve the current balances of your (merchant) Payment Rails accounts, as well as your business PayPal account, if it has been added. Balances are displayed with their associated currency.

Note that Payment Rails does not hold balances for individual recipients. Balances always refers to the merchant’s funding account balance. In the situation where a payment that was sent to a recipient is returned as an error, such as a mis-match of the name on the recipient’s bank account, then the returned funds will be added back to your merchant account balance. It would not be added to a recipient account balance/wallet balance. (We would also flag that payment as a returned payment so you can resolve it).

Retrieve all account balances

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X GET \
  https://api.paymentrails.com/v1/profile/balances
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Balances.get(callback);
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');

$response = \paymentrails\Balances::get();
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            Dictionary<String, Balance> balances = PaymentRails_Balances.get();
            foreach(KeyValuePair<String, Balance> balance in balances)
            {
                Console.WriteLine(String.Format("My {0} balance is {1}", balance.Key, balance.Value.Amount));
            }
            Console.Read();
        }
    }

Example response (200 Ok)

{
  "ok": true,
  "balances": {
    "paypal": {
      "primary": false,
      "amount": "1000.00",
      "currency": "USD",
      "type": "paypal",
      "accountNumber": null
    },
    "GBP": {
      "primary": false,
      "amount": "761316.01",
      "currency": "GBP",
      "type": "paymentrails",
      "accountNumber": "0000846"
    },
    "EUR": {
      "primary": false,
      "amount": "790473.12",
      "currency": "EUR",
      "type": "paymentrails",
      "accountNumber": "0000847"
    },
    "USD": {
      "primary": true,
      "amount": "1463430.27",
      "currency": "USD",
      "type": "paymentrails",
      "accountNumber": "0000848"
    },
    "CAD": {
      "primary": false,
      "amount": "10000.8900000155",
      "currency": "CAD",
      "type": "paymentrails",
      "accountNumber": "0000867"
    }
  }
}

Retrieves the balances of your (merchant) Payment Rails account as well as your PayPal account, if setup.

HTTP Request

GET https://api.paymentrails.com/v1/profile/balances

HTTP Code Description
200 Batch successfully updated
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object not found
internal_server_error Internal server errors

Retrieve Payment Rails account balance

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X GET \
  https://api.paymentrails.com/v1/profile/balances/paymentrails
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Balances.get(callback, 'paymentrails');
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');

$response = \paymentrails\Balances::get('paymentrails');
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            Dictionary<String, Balance> balances = PaymentRails_Balances.get("paymentrails");
            foreach(KeyValuePair<String, Balance> balance in balances)
            {
                Console.WriteLine(String.Format("My {0} balance is {1}", balance.Key, balance.Value.Amount));
            }
            Console.Read();
        }
    }

Example response (200 Ok)

{
  "ok": true,
  "balances": {
    "GBP": {
      "primary": false,
      "amount": "761316.01",
      "currency": "GBP",
      "type": "paymentrails",
      "accountNumber": "0000846"
    },
    "EUR": {
      "primary": false,
      "amount": "790473.12",
      "currency": "EUR",
      "type": "paymentrails",
      "accountNumber": "0000847"
    },
    "USD": {
      "primary": true,
      "amount": "1463430.27",
      "currency": "USD",
      "type": "paymentrails",
      "accountNumber": "0000848"
    },
    "CAD": {
      "primary": false,
      "amount": "10000.8900000155",
      "currency": "CAD",
      "type": "paymentrails",
      "accountNumber": "0000867"
    }
  }
}

Retrieves the balances of your (merchant) Payment Rails accounts.

HTTP Request

GET https://api.paymentrails.com/v1/profile/balances/paymentrails

HTTP Code Description
200 Batch successfully updated
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object not found
internal_server_error Internal server errors

Retrieve PayPal account balance

curl \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <YOUR-API-KEY>" \
  -X GET \
  https://api.paymentrails.com/v1/profile/balances/paypal
var PaymentRails = require('paymentrails');
var callback = function (error, data, response) {
    if (error) {
        console.error(error);
    } else {
        console.log('API called successfully. Returned data: ' + data);
    }
};

PaymentRails.Configuration.prototype.setApiKey('access-code');
PaymentRails.Configuration.prototype.setApiSecret('secret-code');
PaymentRails.Balances.get(callback, 'paypal');
<?php
include(__DIR__ . '/paymentrails/lib/paymentrails.php');

\paymentrails\Configuration::setApiKey('<YOUR-API-KEY>');

$response = \paymentrails\Balances::get('paypal');
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            PaymentRails_Configuration.ApiKey = "<YOUR-API-KEY>";
            Dictionary<String, Balance> balances = PaymentRails_Balances.get("paypal");
            foreach(KeyValuePair<String, Balance> balance in balances)
            {
                Console.WriteLine(String.Format("My {0} balance is {1}", balance.Key, balance.Value.Amount));
            }
            Console.Read();
        }
    }

Example response (200 Ok)

{ 
  "ok": true,
  "balances": {
    "paypal": {
      "primary": false,
      "amount": "1000.00",
      "currency": "USD",
      "type": "paypal",
      "accountNumber": null
    }
  }
}

Retrieves the balances of your (merchant) PayPal accounts. You must first setup PayPal as a payout method.

HTTP Request

GET https://api.paymentrails.com/v1/profile/balances/paypal

HTTP Code Description
200 Batch successfully updated
403 Invalid API key
404 Object not found
500 Internal error

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok params in the response.

Error Code Description
not_found Object not found
internal_server_error Internal server errors

References

List of Countries

Payment Rails uses ISO standard ALPHA-2 codes to represent countries. The following is the list of supported countries.

Country Name Country ISO ALPHA-2
Afghanistan AF
Albania AL
Algeria DZ
American Samoa AS
Andorra AD
Angola AO
Anguilla AI
Antigua & Barbuda AG
Argentina AR
Armenia AM
Aruba AW
Australia AU
Austria AT
Azerbaijan AZ
Bahamas BS
Bahrain BH
Bangladesh BD
Barbados BB
Belarus BY
Belgium BE
Belize BZ
Benin BJ
Bermuda BM
Bhutan BT
Bolivia BO
Bonaire, Sint Eustatius & Saba BQ
Bosnia & Herzegovina BA
Botswana BW
Brazil BR
Brunei BN
Bulgaria BG
Burkina Faso BF
Burundi BI
Cambodia KH
Cameroon CM
Canada CA
Cayman Islands KY
Central African Republic CF
Chad TD
Chile CL
China CN
Christmas Island CX
Colombia CO
Comoros KM
Congo (Brazzaville) CG
Cook Islands CK
Costa Rica CR
Croatia HR
Curacao CW
Cyprus CY
Czech Republic CZ
Denmark DK
Djibouti DJ
Dominica DM
Dominican Republic DO
Ecuador EC
Egypt EG
El Salvador SV
Equatorial Guinea GQ
Eritrea ER
Estonia EE
Ethiopia ET
Falkland Islands (Malvinas) FK
Faroe Islands FO
Fiji FJ
Finland FI
France FR
French Guiana GF
French Polynesia PF
French Southern Territories TF
Gabon GA
Gambia GM
Georgia GE
Germany DE
Ghana GH
Gibraltar GI
Greece GR
Greenland GL
Grenada GD
Guadeloupe GP
Guam GU
Guatemala GT
Guernsey GG
Guinea GN
Guinea-Bissau GW
Guyana GY
Haiti HT
Honduras HN
Hong Kong HK
Hungary HU
Iceland IS
India IN
Indonesia ID
Ireland IE
Isle of Man IM
Israel IL
Italy IT
Jamaica JM
Japan JP
Jersey JE
Jordan JO
Kazakhstan KZ
Kenya KE
Kiribati KI
Korea (South) KR
Kuwait KW
Kyrgyzstan KG
Laos LA
Latvia LV
Lesotho LS
Liechtenstein LI
Lithuania LT
Luxembourg LU
Macau MO
Macedonia MK
Madagascar MG
Malawi MW
Malaysia MY
Maldives MV
Mali ML
Malta MT
Marshall Islands MH
Martinique MQ
Mauritania MR
Mauritius MU
Mayotte YT
Mexico MX
Micronesia (Federated States of) FM
Moldova MD
Monaco MC
Mongolia MN
Montenegro ME
Montserrat MS
Morocco MA
Mozambique MZ
Namibia NA
Nepal NP
Netherlands NL
New Caledonia NC
New Zealand NZ
Nicaragua NI
Niger NE
Nigeria NG
Niue NU
Norfolk Island NF
Northern Mariana Islands MP
Norway NO
Oman OM
Pakistan PK
Palau PW
Panama PA
Papua New Guinea PG
Paraguay PY
Peru PE
Philippines PH
Pitcairn PN
Poland PL
Portugal PT
Puerto Rico PR
Qatar QA
Reunion RE
Romania RO
Russia RU
Rwanda RW
Saint Martin (French part) MF
Sint Maarten (Dutch part) SX
Samoa WS
San Marino SM
Sao Tome & Principe ST
Saudi Arabia SA
Senegal SN
Serbia RS
Seychelles SC
Sierra Leone SL
Singapore SG
Slovakia SK
Slovenia SI
Solomon Islands SB
South Africa ZA
South Georgia & the South Sandwich Islands GS
South Sudan SS
Spain ES
Sri Lanka LK
St Barthelemy BL
St Helena SH
St Kitts & Nevis KN
St Lucia LC
St Pierre & Miquelon PM
St Vincent & the Grenadines VC
Suriname SR
Svalbard & Jan Mayen SJ
Swaziland SZ
Sweden SE
Switzerland CH
Taiwan TW
Tajikistan TJ
Tanzania TZ
Thailand TH
Timor-Leste TL
Togo TG
Tokelau TK
Tonga TO
Trinidad & Tobago TT
Tunisia TN
Turkey TR
Turkmenistan TM
Turks & Caicos Island TC
Tuvalu TV
Uganda UG
Ukraine UA
United Arab Emirates AE
United Kingdom GB
United States of America US
Uruguay UY
Uzbekistan UZ
Vatican City VA
Vanuatu VU
Vietnam VN
Virgin Islands (British) VG
Virgin Islands (US) VI
Wallis & Futuna WF
Zambia ZM

Banned Countries

The following 17 countries are NOT supported due to UN or other sanctions:

Name ISO Code
Congo (Kinshasa) CD
Cuba CU
Iran IR
Iraq IQ
Ivory Coast CI
Korea (North) KP
Lebanon LB
Liberia LR
Libya LY
Myanmar (Burma) MM
Somalia SO
Sudan SD
Syria SY
Venezuela VE
Yemen YE
Zaire ZR
Zimbabwe ZW

Retrieve a country

You can retrieve a country by the country code. For example:

curl \
  -H "Content-Type: application/json" \
  -X GET \
  https://api.paymentrails.com/v1/geography/countries/CA

Response (200 Ok)

{
  "ok": true,
  "country": {
    "name": "Canada",
    "code": "CA",
    "currency": {
      "code": "CAD",
      "name": "Canadian Dollar"
    },
    "regions": {
      "NT": "Northwest Territories",
      "NU": "Nunavut",
      "NS": "Nova Scotia",
      "MB": "Manitoba",
      "SK": "Saskatchewan",
      "QC": "Quebec",
      "PE": "Prince Edward Island",
      "BC": "British Columbia",
      "YT": "Yukon",
      "NB": "New Brunswick",
      "NL": "Newfoundland and Labrador",
      "ON": "Ontario",
      "AB": "Alberta"
    }
  }
}

List of Regions

Example response (200 Ok)

{
  "name": "Canada",
  "code": "CA",
  "currency": {
    "code": "CAD",
    "name": "Canadian Dollar"
  },
  "regions": {
    "AB": "Alberta",
    "BC": "British Columbia",
    "MB": "Manitoba",
    "NB": "New Brunswick",
    "NL": "Newfoundland and Labrador",
    "NT": "Northwest Territories",
    "NS": "Nova Scotia",
    "NU": "Nunavut",
    "ON": "Ontario",
    "PE": "Prince Edward Island",
    "QC": "Quebec",
    "SK": "Saskatchewan",
    "YT": "Yukon"
  }
}
-H "Content-Type: application/json" \
-X GET \
https://api.paymentrails.com/v1/geography/countries/CA

List of regions, states or provinces supported

HTTP Request

GET https://api.paymentrails.com/v1/geography/countries/:code

Fields Description
code
string
ISO ALPHA-2 country code

List of Statuses

Recipient Status

Status Details
active An Active recipient is able to receive a payment. Each recipient must have a minimum amount of profile information to become active and eligible to send payments to. This minimum info includes having an Address, and a Payout Method setup. Please note that an Address is not required to become active when PayPal is the primary payout method for the recipient.
incomplete An Incomplete recipient does not yet have the minimum required profile information to become active. An incomplete recipient can not be sent a payment. The minimum profile info includes having an Address, and a Payout Method setup. Please note that an Address is not required to become active when PayPal is the primary payout method for the recipient.
inactive There are two ways a recipient can become Inactive: 1.) The merchant (you or your staff) manually updates the recipient as Inactive through the dashboard, or via API; or 2.) If the recipient has not been sent a payment for 12 months or more, we will automatically update their status as Inactive. An Inactive recipient is still able to be sent a payment. We use the inactive status to help you organize and filter your recipients, and to help to avoid accidentally sending a manual payment to the wrong recipient, by highlighting recipients that have not been active for the past 12 months.
disabled This status is used to temporarily disable a recipient so they can not be sent a payment. It is used when a recipients account appears to be compromised or hacked. There are two ways a recipient’s status can become Disabled: 1.) The merchant (you or your staff) manually updates the recipient as Disabled through the dashboard or via API; or 2.) Payment Rails has identified suspicious activity on the recipient’s profile, such as changes to the payment account info from an IP address in a different country (contact us for specific risk rules). The Disabled status is a temporary status, and is usually updated to either Suspended or Active status based on a risk review conducted by the merchant.
suspended The Suspended status is used for flagging fraudulent or bad recipients. These recipients can not receive payments and cannot be added to a batch of payments. Suspended recipient information (email, IP address, etc) may also be used to identify and flag other potential bad users (e.g. the same bad user with multiple accounts) within your list of recipients.

Payment Status

Status Details
pending A payment’s status is automatically updated to Pending when a payment is created inside a batch. The payment will remain in Pending status until it is Processed. It is possible to Delete (DELETE) or update (PATCH) a payment in Pending status.
failed A payment’s status will be automatically updated to Failed after it is attempted to be processed, but fails to process due to a number of possible reasons, such as a technical issue. You cannot delete (DELETE) or update (PATCH) a payment in Failed status. A new payment would need to be created to attempt to process it again.
processed A payment’s status will be automatically updated to Processed after it is attempted to be processed, and is successful. You cannot delete (DELETE) or update (PATCH) a payment in Processed status.
returned A payment’s status will be automatically updated to Returned, if it was successfully Processed, however at a later time (from minutes up to weeks later), it was returned to as not deliverable. This is most often caused due to incorrect bank account information being provided, or beneficiary mis-match (the name provided does not match with the name on the bank account. You cannot delete (DELETE) or update (PATCH) a payment in Returned status. Payments with returned status should be actioned by the merchant by requesting the recipient to confirm their bank account or payout method details, and once updated, create a new payment to send to the recipients updated payout method. If a Recipient has a Returned payment, their payout method will be temporarily disabled until the payout method is updated by either the merchant or recipient as being confirmed as accurate.

Batch Status

Status Details
open A new batch is assigned a status of Open when it is first created. You can Delete (DELETE) or update (PATCH) any batch with an Open status. Usually you will update a batch by adding payments to it.
accepted A batch is moved to Accepted status when it involves at least two currencies and a currency conversion needs to take place. If you accept the foreign exchange rate quotation provided, you will lock in that rate by accepting the quote. You can not Delete (DELETE) or update (PATCH) a batch once it is in Accepted.
processing When you initiate a batch to start processing, the status is updated to Processing. This status is temporary, and the status will automatically update once processing is completed, usually within a few seconds. You can not Delete (DELETE) or update (PATCH) a batch once it is in Processing status.
complete Once a batch has been successfully processed, it will be updated as Complete. You can not Delete (DELETE) or update (PATCH) a batch once it is in Complete status.

Payout Methods by Country

Bank Transfers

United States - ACH, on domestic local rails

Country Currency Received by Recipient Daily cut off
United States USD Next business day 3:00pm EST

Canada - EFT, on domestic local rails

Country Currency Received by Recipient Daily cut off
Canada CAD Next business day 4:00pm EST

Eurozone - SEPA, on domestic local rails 21 Countries.

Country Currency Received by Recipient Daily cut off
Austria EUR Next business day 2:00pm EST
Belgium EUR Next business day 2:00pm EST
Cyprus EUR Next business day 2:00pm EST
Estonia EUR Next business day 2:00pm EST
Finland EUR Next business day 2:00pm EST
France EUR Next business day 2:00pm EST
Germany EUR Next business day 2:00pm EST
Greece EUR Next business day 2:00pm EST
Ireland EUR Next business day 2:00pm EST
Italy EUR Next business day 2:00pm EST
Latvia EUR Next business day 2:00pm EST
Lithuania EUR Next business day 2:00pm EST
Luxembourg EUR Next business day 2:00pm EST
Malta EUR Next business day 2:00pm EST
Monaco EUR Next business day 2:00pm EST
Netherlands EUR Next business day 2:00pm EST
Portugal EUR Next business day 2:00pm EST
San Marino EUR Next business day 2:00pm EST
Slovakia EUR Next business day 2:00pm EST
Slovenia EUR Next business day 2:00pm EST
Spain EUR Next business day 2:00pm EST

International ACH - on domestic local rails 38 countries

Country Currency Received by Recipient Daily cut off
Albania ALB 1-2 business days 2:00pm EST
Australia AUD 1-2 business days 2:00pm EST
Barbados BBD 1-2 business days 2:00pm EST
Bosnia & Herzegovina BAM 1-2 business days 2:00pm EST
Brazil BRL 1-2 business days 2:00pm EST
Bulgaria BGN 1-2 business days 2:00pm EST
China CNY 1-2 business days 2:00pm EST
Croatia HRK 1-2 business days 2:00pm EST
Czech Republic CZK 1-2 business days 2:00pm EST
Denmark DKK 1-2 business days 2:00pm EST
Egypt EGP 1-2 business days 2:00pm EST
Gibraltar GIP 1-2 business days 2:00pm EST
Hong Kong HKD 1-2 business days 2:00pm EST
Hungary HUF 1-2 business days 2:00pm EST
Iceland ISK 1-2 business days 2:00pm EST
India INR 1-2 business days 2:00pm EST
Indonesia IDR 1-2 business days 2:00pm EST
Jamaica JMD 1-2 business days 2:00pm EST
Liechtenstein CHF 1-2 business days 2:00pm EST
Macau MOP 1-2 business days 2:00pm EST
Morocco MAD 1-2 business days 2:00pm EST
New Zealand NZD 1-2 business days 2:00pm EST
Norway NOK 1-2 business days 2:00pm EST
Pakistan PKR 1-2 business days 2:00pm EST
Philippines PHP 1-2 business days 2:00pm EST
Poland PLN 1-2 business days 2:00pm EST
Romania RON 1-2 business days 2:00pm EST
Russia RUB 1-2 business days 2:00pm EST
Singapore SGD 1-2 business days 2:00pm EST
Sri Lanka LKR 1-2 business days 2:00pm EST
Sweden SEK 1-2 business days 2:00pm EST
Switzerland CHF 1-2 business days 2:00pm EST
Thailand THB 1-2 business days 2:00pm EST
Trinidad & Tobago TTD 1-2 business days 2:00pm EST
Turkey TRY 1-2 business days 2:00pm EST
United Kingdom GBP 1-3 business days 2:00pm EST
Vietnam VND 1-2 business days 2:00pm EST
Virgin Islands (British) USD 1-2 business days 2:00pm EST

SWIFT Bank Wires - on the Swift wire network (non-local) 161 countries

Country Currency Received by Recipient Daily cut off
Afghanistan AFN 3-5 business days 2:00pm EST
Algeria DZD 3-5 business days 2:00pm EST
American Samoa USD 3-5 business days 2:00pm EST
Andorra EUR 3-5 business days 2:00pm EST
Angola AOA 3-5 business days 2:00pm EST
Anguilla XCD 3-5 business days 2:00pm EST
Antigua & Barbuda XCD 3-5 business days 2:00pm EST
Argentina ARS 3-5 business days 2:00pm EST
Armenia AMD 3-5 business days 2:00pm EST
Aruba AWG 3-5 business days 2:00pm EST
Azerbaijan AZN 3-5 business days 2:00pm EST
Bahamas BSD 3-5 business days 2:00pm EST
Bahrain BHD 3-5 business days 2:00pm EST
Bangladesh BDT 3-5 business days 2:00pm EST
Belarus BYR 3-5 business days 2:00pm EST
Belize BZD 3-5 business days 2:00pm EST
Benin XOF 3-5 business days 2:00pm EST
Bermuda BMD 3-5 business days 2:00pm EST
Bhutan BTN 3-5 business days 2:00pm EST
Bolivia BOB 3-5 business days 2:00pm EST
Bonaire, Sint Eustatius & Saba USD 3-5 business days 2:00pm EST
Botswana BWP 3-5 business days 2:00pm EST
Brunei BND 3-5 business days 2:00pm EST
Burkina Faso XOF 3-5 business days 2:00pm EST
Burundi BIF 3-5 business days 2:00pm EST
Cambodia KHR 3-5 business days 2:00pm EST
Cameroon XAF 3-5 business days 2:00pm EST
Cayman Islands KYD 3-5 business days 2:00pm EST
Central African Republic XAF 3-5 business days 2:00pm EST
Chad XAF 3-5 business days 2:00pm EST
Chile CLP 3-5 business days 2:00pm EST
Christmas Island AUD 3-5 business days 2:00pm EST
Colombia COP 3-5 business days 2:00pm EST
Comoros KMF 3-5 business days 2:00pm EST
Congo (Brazzaville) XAF 3-5 business days 2:00pm EST
Cook Islands NZD 3-5 business days 2:00pm EST
Costa Rica CRC 3-5 business days 2:00pm EST
Curacao ANG 3-5 business days 2:00pm EST
Djibouti DJF 3-5 business days 2:00pm EST
Dominica XCD 3-5 business days 2:00pm EST
Dominican Republic DOP 3-5 business days 2:00pm EST
Ecuador USD 3-5 business days 2:00pm EST
El Salvador USD 3-5 business days 2:00pm EST
Equatorial Guinea XAF 3-5 business days 2:00pm EST
Eritrea ERN 3-5 business days 2:00pm EST
Ethiopia ETB 3-5 business days 2:00pm EST
Falkland Islands (Malvinas) FKP 3-5 business days 2:00pm EST
Faroe Islands DKK 3-5 business days 2:00pm EST
Fiji FJD 3-5 business days 2:00pm EST
French Guiana EUR 3-5 business days 2:00pm EST
French Polynesia XPF 3-5 business days 2:00pm EST
French Southern Territories EUR 3-5 business days 2:00pm EST
Gabon XAF 3-5 business days 2:00pm EST
Gambia GMD 3-5 business days 2:00pm EST
Georgia GEL 3-5 business days 2:00pm EST
Ghana GHS 3-5 business days 2:00pm EST
Greenland DKK 3-5 business days 2:00pm EST
Grenada XCD 3-5 business days 2:00pm EST
Guadeloupe EUR 3-5 business days 2:00pm EST
Guam USD 3-5 business days 2:00pm EST
Guatemala GTQ 3-5 business days 2:00pm EST
Guernsey GBP 3-5 business days 2:00pm EST
Guinea GNF 3-5 business days 2:00pm EST
Guinea-Bissau XOF 3-5 business days 2:00pm EST
Guyana GYD 3-5 business days 2:00pm EST
Haiti HTG 3-5 business days 2:00pm EST
Honduras HNL 3-5 business days 2:00pm EST
Isle of Man GBP 3-5 business days 2:00pm EST
Israel ILS 3-5 business days 2:00pm EST
Japan JPY 2-3 business days 2:00pm EST
Jersey GBP 3-5 business days 2:00pm EST
Jordan JOD 3-5 business days 2:00pm EST
Kazakhstan KZT 3-5 business days 2:00pm EST
Kenya KES 3-5 business days 2:00pm EST
Kiribati AUD 3-5 business days 2:00pm EST
Korea (South) KRW 3-5 business days 2:00pm EST
Kuwait KWD 3-5 business days 2:00pm EST
Kyrgyzstan KGS 3-5 business days 2:00pm EST
Laos LAK 3-5 business days 2:00pm EST
Lesotho LSL 3-5 business days 2:00pm EST
Macedonia MKD 3-5 business days 2:00pm EST
Madagascar MGA 3-5 business days 2:00pm EST
Malawi MWK 3-5 business days 2:00pm EST
Malaysia MYR 3-5 business days 2:00pm EST
Maldives MVR 3-5 business days 2:00pm EST
Mali XOF 3-5 business days 2:00pm EST
Marshall Islands USD 3-5 business days 2:00pm EST
Martinique EUR 3-5 business days 2:00pm EST
Mauritania MRO 3-5 business days 2:00pm EST
Mauritius MUR 3-5 business days 2:00pm EST
Mayotte EUR 3-5 business days 2:00pm EST
Mexico MXN 3-5 business days 2:00pm EST
Micronesia (Federated States of) USD 3-5 business days 2:00pm EST
Moldova MDL 3-5 business days 2:00pm EST
Mongolia MNT 3-5 business days 2:00pm EST
Montenegro EUR 3-5 business days 2:00pm EST
Montserrat XCD 3-5 business days 2:00pm EST
Mozambique MZN 3-5 business days 2:00pm EST
Namibia NAD 3-5 business days 2:00pm EST
Nepal NPR 3-5 business days 2:00pm EST
New Caledonia XPF 3-5 business days 2:00pm EST
Nicaragua NIO 3-5 business days 2:00pm EST
Niger XOF 3-5 business days 2:00pm EST
Nigeria NGN 3-5 business days 2:00pm EST
Niue NZD 3-5 business days 2:00pm EST
Norfolk Island AUD 3-5 business days 2:00pm EST
Northern Mariana Islands USD 3-5 business days 2:00pm EST
Oman OMR 3-5 business days 2:00pm EST
Palau USD 3-5 business days 2:00pm EST
Panama PAB 3-5 business days 2:00pm EST
Papua New Guinea PGK 3-5 business days 2:00pm EST
Paraguay PYG 3-5 business days 2:00pm EST
Peru PEN 3-5 business days 2:00pm EST
Pitcairn NZD 3-5 business days 2:00pm EST
Puerto Rico USD 3-5 business days 2:00pm EST
Qatar QAR 3-5 business days 2:00pm EST
Reunion EUR 3-5 business days 2:00pm EST
Rwanda RWF 3-5 business days 2:00pm EST
Saint Martin (French part) EUR 3-5 business days 2:00pm EST
Samoa WST 3-5 business days 2:00pm EST
Sao Tome & Principe STD 3-5 business days 2:00pm EST
Saudi Arabia SAR 3-5 business days 2:00pm EST
Senegal XOF 3-5 business days 2:00pm EST
Serbia RSD 3-5 business days 2:00pm EST
Seychelles SCR 3-5 business days 2:00pm EST
Sierra Leone SLL 3-5 business days 2:00pm EST
Sint Maarten (Dutch part) ANG 3-5 business days 2:00pm EST
Solomon Islands SBD 3-5 business days 2:00pm EST
South Africa ZAR 3-5 business days 2:00pm EST
South Georgia & the South Sandwich Islands GBP 3-5 business days 2:00pm EST
South Sudan USD 3-5 business days 2:00pm EST
St Barthelemy EUR 3-5 business days 2:00pm EST
St Helena SHP 3-5 business days 2:00pm EST
St Kitts & Nevis XCD 3-5 business days 2:00pm EST
St Lucia XCD 3-5 business days 2:00pm EST
St Pierre & Miquelon EUR 3-5 business days 2:00pm EST
St Vincent & the Grenadines XCD 3-5 business days 2:00pm EST
Suriname SRD 3-5 business days 2:00pm EST
Svalbard & Jan Mayen NOK 3-5 business days 2:00pm EST
Swaziland SZL 3-5 business days 2:00pm EST
Taiwan TWD 3-5 business days 2:00pm EST
Tajikistan TJS 3-5 business days 2:00pm EST
Tanzania TZS 3-5 business days 2:00pm EST
Timor-Leste USD 3-5 business days 2:00pm EST
Togo XOF 3-5 business days 2:00pm EST
Tokelau NZD 3-5 business days 2:00pm EST
Tonga TOP 3-5 business days 2:00pm EST
Tunisia TND 3-5 business days 2:00pm EST
Turkmenistan TMT 3-5 business days 2:00pm EST
Turks & Caicos Islands USD 3-5 business days 2:00pm EST
Tuvalu USD 3-5 business days 2:00pm EST
Uganda UGX 3-5 business days 2:00pm EST
Ukraine UAH 3-5 business days 2:00pm EST
United Arab Emirates AED 3-5 business days 2:00pm EST
Uruguay UYU 3-5 business days 2:00pm EST
Uzbekistan UZS 3-5 business days 2:00pm EST
Vanuatu VUV 3-5 business days 2:00pm EST
Vatican City EUR 3-5 business days 2:00pm EST
Virgin Islands (US) USD 3-5 business days 2:00pm EST
Wallis & Futuna XPF 3-5 business days 2:00pm EST
Zambia ZMW 3-5 business days 2:00pm EST

Country Requirements

Recipient Government ID Number

Some countries have special requirements to provide a Government ID or Tax ID number for recipients you send money to in that country. Below is a list of the countries that have this special requirement. We ask recipients for this information when providing their payout method account details. A recipient from these countries will need a government ID or tax ID on their profile to become active, they will be in incomplete status otherwise.

Country Individual or Business Government ID / Tax ID Length of Number
Argentina Individual CUIT (Código Único de Identificación Tributaria) 11
Argentina Business CUIT (Código Único de Identificación Tributaria) 11
Azerbaijan Individual TIN (Taxpayer Identification Number) 10
Brazil Individual CPF (Cadastro de Pessoas Físicas) 11
Brazil Business CNPJ (Cadastro Nacional de Pessoas Jurídicas) 14
Chile Individual RUT/RUN (Rol Único Tributario/Nacional) 9
Colombia Individual NIT (Número de Identificación Tributaria) 10
Costa Rica Individual Cedula Juridica 9 to 12
Guatemala Individual NIT (Número de Identificación Tributaria) 8 to 12
Kazakhstan Individual IIN (Individual identification number) 12
Paraguay Individual Cedula de Indentidad/RUC 6 to 11

Recipient Phone Number

Select countries have special requirements to provide the phone number for recipients you send money to in that country. Below is a list of the countries that have this special requirement. A recipient in one of these countries will need a phone number on their profile to become active, they will be in incomplete status otherwise.

Country Individual or Business
Argentina Both
Bangladesh Both
Brazil Both
Chile Both
China Both
Colombia Both
Costa Rica Both
Ethiopia Both
Fiji Both
Guatemala Both
Jordan Both
Kazakhstan Both
Kiribati Both
Korea (South) Both
Mongolia Both
Russia Both
South Africa Both
Taiwan Both
Thailand Both
Tuvalu Both
Togo Both
Tonga Both

SDK

Payment Rails SDK

API clients in: Node.js (Javascript), PHP, Ruby, Java, curl, Python, Go, Perl, Swift and Scala.

We want to make integrating with our APIs as easy as possible for developers. That is why we have developed SDKs for the most common languages, which you will find links to below, all hosted on GitHub.

If we don’t have a client for the language you need, please reach out to us on developers@paymentrails.com, and we will see what we can do to add that language.

Language GitHub Repository
PHP https://github.com/PaymentRails/php-sdk
Node.js https://github.com/PaymentRails/paymentrails_nodejs
C# https://github.com/PaymentRails/paymentrails_dotnet