API Documentation

Table of Contents

curl Ruby Python 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 mission is to give more choice of payout methods to merchants world wide. 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 doesn’t have a PayPal account, and over 2 billion people don’t have a bank account. So clearly multiple payout options are needed to support a global business. That is why we plan to support every major payout method, so your users have choice of what works best for them.

Payment Rails currently supports direct payments to via bank transfer (in 220+ countries) and PayPal. In the near future, we will also support payments by mobile money, cash pick-up, paper checks and to existing debit 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, while offering your users a seamless 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.


Please review our API Terms of Use.



Before you start

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

Term ID # Format Description
Recipient R-1a2B3c4D5e6F7g8H9i0J1k A Recipient is the individual or business that you need to send a payment to.
Payment P-1a2B3c4D5e6F7g8H9i0J1k A Payment is an individual payout to a recipient.
Batch B-1a2B3c4D5e6F7g8H9i0J1k A Batch is a group of payments.
Transfer T-1a2B3c4D5e6F7g8H9i0J1k 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_status 400 Status of an object is invalid
invalid_field 400 Field value is invalid
empty_field 400 Field value is required but not provided
expired_quote 400 Quote is expired
invalid_api_key 401 API key is invalid
not_authorized 403 Authentication not permitted to access resource
not_found 404 Object not found
rate_limit_exceeded 429 Rate limit exceeded
partner_integration_error 500 Error occured with one of our partners
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 – The 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 to 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”)
amount All amounts are in string format in order to avoid rounding problems with floating point numbers. The only allowed formats are positive numeric values with either two decimal places or no decimal (e.g. “1.99” or “123”).
currency The type of currency is in ISO 4217 (e.g. “USD”, “CAD”, or “JPY”)


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 authentication 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 contain 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 secret key on the prehash string and timestamp + '\n' + method + '\n' + requestPath + '\n' + body + '\n'.

Example of creating a 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>" \
  -H "X-PR-Timestamp: <timestamp>" \
  -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. You can do this in ‘Settings’ section of the merchant dashboard under the ‘Security’ tab.

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, and Debit/Credit Cards).

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-1a2B3c4D5e6F7g8H9i0J1k”, with the ‘R-’ prefix indicating Recipient.

Recipient Attributes

Example Recipient

{
   "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
   "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 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, e.g. ‘U1234556678’)
email
required
string
Email address of recipient (e.g. ‘john@email.com’)
name
required if type is Business
string
Name of Business (e.g. ABC Company Ltd). Required if Type is Business. (Note: If type is Individual, we will automatically populate this field with firstname and lastname of individual).
lastName
required if type is Individual
string
Recipient’s Last name (surname), (e.g. ‘Smith’). Required if Type is Individual. Optionally can provide contact persons last name if Type is Business.
firstName
required if Type is Individual
string
Recipient’s First name (e.g. ‘John’). Required if Type is Individual. Optionally can provide contact persons first name if Type is Business.
status
string
Status of a recipient in the system
complianceStatus
string
Recipient has passed (‘verified’) AML watchlist compliance screening, or been flagged for further review (‘blocked’).
gravatarUrl
string
The gravatar url of recipient
language
string
2-digit ISO 639-1 language code. Currently only English (‘en’) is supported.
dob
date
Date of Birth (YYYY-MM-DD)
passport
string
Passport number
governmentId
string
Government ID or Tax ID number (e.g. 123456798910). Required for bank transfer payout method for these countries only: If Individual: Argentina (CUIT, 11 digits), Azerbaijan (TIN, 10 digits), Brazil (CPF, 11 digits), Chile (RUT/RUN, 9 digits), Colombia (NIT, 10 digits), Costa Rica (Cedula Juridica, 9-12 digits), Guatemala (NIT, 8-12 digits), Kazakhstan (IIN, 12 digits), Paraguay (6-11 digits). If Business: Argentina (CUIT, 11 digits), Brazil (CNPJ, 14 digits).
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"
}
Field Description
street1
required
string
Recipient’s Street 1 Address. Please do not provide PO Box Address. (E.g. 123 Sample Street). Required for bank transfer payout method. Otherwise it is optional.
street2
optional
string
Recipient’s Street 2 Address (e.g. Apt 5).
city
required
string
Recipient’s address City (e.g. Miami). Required for bank transfer payout method. Otherwise it is Optional.
postalCode
optional
string
Recipient’s address Postal code or Zip code (e.g. 90210, M5X 2X1, 2000).
country
required
string
Recipient Country. Required for bank transfer payout method.Otherwise it is Optional. We can accept ISO 3166-1 alpha-2 (e.g. ‘US’) and full country name (e.g. ‘United States’) although country code is highly recommended.
region
required
string
Region code Recipient’s address Region (state/ province / county). We accept both ISO 3166-2 code (e.g. FL), and full state/province name (e.g. Florida). ISO 3166-2 code is highly recommended.
phone
optional
string
Recipient’s phone number (e.g. 415-123-0000 or +14151230000). Required for bank transfer payout method for these countries only: Argentina, Bangladesh, Brazil, Chile, China, Colombia, Costa Rica, Ethiopia, Fiji, Guatemala, Jordan, Kazakhstan, Kiribati, Korea (South), Mongolia, Russia, South Africa, Taiwan, Thailand, Tuvalu, Togo, Tonga. Otherwise it is optional.

Payout Method

For further information read about the Payout Method Attributes

Create a recipient

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  var body = {
    type: "individual",
    firstName: "John",
    lastName: "Smith",
    email: "jsmith@example.com" 
  };

  const recipient = await client.recipient.create('R-1a2B3c4D5e6F7g8H9i0J1k', body);
  console.log(recipient.id);
}
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
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient = PaymentRails\Recipient::create([
    'type' => "individual",
    'firstName' => 'Tom',
    'lastName' => 'Jones',
    'email' => 'jsmith@example.com',
]);
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            Recipient recipient = new Recipient("individual", "TomJones@example.com", null, "Tom", "Jones");

            Recipient response = client.recipient.create(recipient);

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.recipient import Recipient
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

payload = {"type": "individual", "firstName": "John", "lastName": "Smith", "email": "swd4356d@5gedmple.com"}
response = client.recipient.create(payload)

print(response.id)

Example response (200 Ok)

{
  "ok": true,
  "recipient": {
    "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
    "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-1a2B3c4D5e6F7g8H9i0J1k",
    "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/

Fields Description
id
optional
string
Recipient reference ID as assigned by your business (your internal user reference number, e.g. U1234556678)
type
required
string
Recipient type, either: business or individual
name
conditional
string
Name of Business (e.g. ABC Company Ltd). Required if Type is business. (Note: If type is individual, we will automatically populate this field with firstName and lastName of individual).
firstName
conditional
string
Recipient’s First name (e.g. John). Required if Type is individual. Optionally can provide contact persons first name if Type is business.
lastName
conditional
string
Recipient’s Last name (surname), (e.g. Smith). Required if Type is individual. Optionally can provide contact persons last name if Type is business.
email
required
string
Email address of recipient (e.g. john@email.com)
address
optional
address
Address object. Please read the documentation
referenceId
optional
string
Recipient reference ID as assigned by your business (your internal user reference number, e.g. ‘U1234556678’)
passport
optional
string
Recipients valid passport number
dob
optional
date
Recipient’s date of birth. The format should be YYYY-MM-DD, ie 1990-04-29
phone
optional
string
Recipient’s phone number (e.g. 415-123-0000 or +14151230000). Required for bank transfer payout method for these countries only: Argentina, Bangladesh, Brazil, Chile, China, Colombia, Costa Rica, Ethiopia, Fiji, Guatemala, Jordan, Kazakhstan, Kiribati, Korea (South), Mongolia, Russia, South Africa, Taiwan, Thailand, Tuvalu, Togo, Tonga. Otherwise it is optional.

HTTP Response codes

HTTP Code Description
200 Recipient successfully created
400 One or more fields failed validation, see errors[] in response body
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
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, the 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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await clinet.recipient.get('R-1a2B3c4D5e6F7g8H9i0J1k');
  console.log(recipient.id);
}
require 'payment_rails'

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

recipient = client.recipients.get(recipient_id)
puts recipient
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-1a2B3c4D5e6F7g8H9i0J1k';

$recipient = PaymentRails\Recipient::find($recipient_id);
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            String recipient_id = "R-1a2B3c4D5e6F7g8H9i0J1k";
            Recipient response = client.recipient.find(recipient_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.payment import Recipient
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.recipient.find('R-12345')
print(response.id)

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
required
string
Recipient ID

Response (200 Ok)

{
  "ok": true,
  "recipient": {
    "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
    "referenceId": "jsmith11@example.com",
    "email": "jsmith11@example.com",
    "name": "Richard Hendricks",
    "lastName": "Hendricks",
    "firstName": "Richard",
    "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, the 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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  var body = {firstName: "John"};

  const response = await client.recipient.update('R-1a2B3c4D5e6F7g8H9i0J1k', body);
  console.log(response);
}
require 'payment_rails'

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

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

client.recipients.update(recipient_id, recipient)
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-1a2B3c4D5e6F7g8H9i0J1k';

$response = PaymentRails\Recipient::update($recipient_id, [
    "firstName" => "Mark",
]);
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            Recipient recipient = new Recipient("individual", "TomJones@example.com", null, "Tom", "Jones","R-1234565vcr4");
            String response = PaymentRails_Recipient.patch(recipient);

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.recipient import Recipient
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

payload = {'firstName': 'tom'}
response = client.recipient.update('R-Wx2hvdwDY979ubBcjC4m5w', payload)
print(response)

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.

Note: Account cannot be updated via this interface. Refer to Recipient Account for more information

HTTP Request

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

Fields Description
id
required
string
Recipient ID

HTTP Response codes

HTTP Code Description
200 Recipient successfully updated
400 One or more fields failed validation, see errors[] in response body
403 Invalid API key
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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.recipient.remove('R-1a2B3c4D5e6F7g8H9i0J1k');
  console.log(response);
}
require 'payment_rails'

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

client.recipients.delete(recipient_id)
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-1a2B3c4D5e6F7g8H9i0J1k';

$response = PaymentRails\Recipient::delete($recipient_id);
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            String recipient_id = "R-1a2B3c4D5e6F7g8H9i0J1k";
            String response = client.recipient.delete(recipient_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.recipient import Recipient
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.recipient.delete('R-FR3r9U5TGff93tQTncAZ66')

print(response)

To delete a Recipient, send a DELETE request to the /recipients endpoint with the recipientID. This places the recipient in archived state and can be un-archived.

HTTP Request

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

Fields Description
id
required
string
Recipient 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 "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
  -H "X-PR-Timestamp: <timestamp>" \
  -X DELETE \
  -d '{"ids": ["R-1a2B3c4D5e6F7g8H9i0J1k", "R-1a2B3c4D5e6F7g8H9i0J1k"]}' \
  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 Description
ids
required
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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.recipient.search(1,10,"term");
  console.log(response);
}
require 'payment_rails'

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

puts results
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-1a2B3c4D5e6F7g8H9i0J1k';

$recipients = PaymentRails\Recipient::all();
foreach ($recipients as $recipient) {
    print_r($recipient);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
           var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            List<Recipient> recipients = client.recipient.search("John", 1, 10);

            foreach(Recipient recipient in recipients)
            {
                Console.WriteLine(recipient);
            }
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Recipient
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.search()
print(recipient.id)

Response (200 Ok)

{
  "ok": true,
  "recipients": [
    {
      "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
      "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-1a2B3c4D5e6F7g8H9i0J1k",
      "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 Description
page
optional
int
The page number (default: 1)
pageSize
optional
int
Number of records in a page (default: 10)
search
optional
string
Prefix search of the name, email (username and domain-name) and referenceId
name
optional
string
Prefix search of the name, firstName, lastName
email
optional
string
Exact search of the email address
referenceId
optional
string
Exact search of the referenceId
startDate
optional
date
Ignore older records (based on update date)
endDate
optional
date
Ignore newer records (based on update date)
status
optional
string
Filter by INCOMPLETE = ‘incomplete’,ACTIVE = ‘active’, INACTIVE = ‘inactive’, DELETED = “archived”, DISABLED = “disabled”,SUSPENDED = “suspended”
complianceStatus
optional
string
Filter by pending, verified, blocked
country
optional
string
Filter by ISO2 country code (comma separated list if multiple)
payoutMethod
optional
string
Filter by paypal, bank-transfer
currency
optional
string
Currency of recipient’s bank account. Required for bank transfer payout method. We support 3 letter ISO 4217 codes (e.g. EUR). Not required for PayPal.
orderBy
optional
string
Field name: name, email, referenceId, payoutMethod, createdAt, updatedAt
sortBy
optional
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 "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
  -H "X-PR-Timestamp: <timestamp>" \
   -X GET \
   https://api.paymentrails.com/v1/recipients/:id/logs

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_*********************************",
        "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 Description
id
required
string
Recipient 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 "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
  -H "X-PR-Timestamp: <timestamp>" \
   -X GET \
   https://api.paymentrails.com/v1/recipients/:id/payments
const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.recipient.find('R-1a2B3c4D5e6F7g8H9i0J1k', 'payments');
  console.log(response);
}
from paymentrails.configuration import Configuration
from paymentrails.payment import Payment
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.recipient.find('R-QSCaFZrdWHXyW7raHUmerd','payments')
print(response.id)

Retrieve payments to this recipient

HTTP Request

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

Fields Description
id
required
string
Recipient ID

Response (200 Ok)

{
  "ok": true,
  "payments": [
    {
      "id": "P-1a2B3c4D5e6F7g8H9i0J1k",
      "recipient": {
        "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
        "referenceId": "jsmith11@example.com",
        "email": "jsmith11@example.com",
        "name": "Richard Hendricks",
        "lastName": "Hendricks",
        "firstName": "Richard",
        "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": "memo",
      "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-1a2B3c4D5e6F7g8H9i0J1k",
        "createdAt": "2017-03-21T20:56:43.690Z",
        "updatedAt": "2017-03-21T21:10:05.890Z",
        "sentAt": null,
        "completedAt": null
      }
    },
    {
      "id": "P-1a2B3c4D5e6F7g8H9i0J1k",
      "recipient": {
        "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
        "referenceId": "jsmith11@example.com",
        "email": "jsmith11@example.com",
        "name": "Richard Hendricks",
        "lastName": "Hendricks",
        "firstName": "Richard",
        "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": "memo",
      "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-1a2B3c4D5e6F7g8H9i0J1k",
        "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, the API will respond with an error. For example:

Response (404 Not Found)

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

Recipient Account


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. That is why we plan to support every major payout method, so your users have choice of what works best for them.

Multiple Account Available

By POST-ing an 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.

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
debit-card coming soon Debit and Credit Cards (VISA and MasterCard branded)

Attributes

Fields Description
Id
string
An unique system generated Recipient identifier
type
string
Accepted types are: bank-transfer or PayPal
currency
string
ISO3 currency code (e.g. USD)
primary
boolean
Set recipient account(payout method) as primary (active)
country
string
ISO ALPHA-2 country code (e.g. US)
accountHolderName
string
Exact name of account owner/holder on their bank account, e.g. John S Sample
accountNum
string
Recipient bank account number, (e.g. 123456789). Required for bank transfer payout method. Also use this field for Mexico CLABE account number (e.g. 032180000118359719), and Argentina CBU account number (e.g. 1234567890123456789098). IBAN does not go in this field, use the IBAN field instead. It is also masked so only the last two digits are shown.
bankId
string
Bank ID number. Required for bank transfer payout method in: Canada (Institution Code, 3 digits, e.g. 003).
branchId
string
Bank branch number. Required for bank transfer payout method in: US (Routing Number, 9 digits, e.g. 123456789), Australia (BSB, 6 digits, e.g. 123456), UK/GB (Sort Code, 6 digits, e.g. 123456), Canada (Transit Number, 5 digits, e.g. 12345), New Zealand (Bank/Branch Number, 6 digits, e.g. 030001), India (IFSC Code, 11 digits, e.g. 12345678910)
iban
string
IBAN international bank account number (common in Europe and about 30 other countries). Required for bank transfer payout method if the country uses IBAN bank account number format. (E.g. DE893704004405320130006). It is also masked so only the last two digits are shown.
swiftBic
string
SWIFT-BIC bank code, must be either 8 or 11 characters (e.g. BNBOBOLXPOI). Required for bank transfer payout method, depending on country. Required for most countries we send by Swift Wire as well as some other countries
bankName
string
The bank name, auto-populated by Payment Rails based on bank info provided
bankAddress
string
Recipient’s bank branch address (can include branch name, Address line 1 and Address line 2 in this field. E.g. 123 Wellington Road, Suite 100). Required if adding a bank transfer payout method for countries requiring SWIFT-BIC
bankCity
string
Recipient’s bank branch address City. (E.g. London). Required if adding a bank transfer payout method for countries requiring SWIFT-BIC
bankRegion
string
Recipient’s bank branch address region /state /province/ county. Free text field. (e.g. Kent). Optional if adding a bank transfer payout method for countries requiring SWIFT-BIC
emailAddress
string
A valid email address associated with recipient’s PayPal account (e.g. johnsample@email.com)

Create Account

<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';

$response = PaymentRails\RecipientAccount::create($recipient_id, [
    "type" => "bank-transfer",
    "primary" => "true",
    "country" => "CA",
    "currency" => "CAD",
    "accountNum" => "012345678",
    "bankId" => "004",
    "branchId" => "47261",
    "accountHolderName" => "John Smith"
]);
const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  var body = {
    "type": "bank-transfer",
    "primary": "true",
    "country": "CA",
    "currency": "CAD",
    "accountNum": "012345678",
    "bankId": "004",
    "branchId": "47261",
    "accountHolderName": "John Smith"
  };
  const response = await client.recipientAccount.create('R-4625iLug2GKqKZG2WzAf3e', body);
  console.log(response);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            RecipientAccount recipientAccount = new RecipientAccount("bank-transfer", "EUR", null, null, "FR", "FR14 **** **** **** **** **** ***", "123456");
            RecipientAccount recipientAccount = client.recipientAccount.create(recipient.id, recipientAccount);

            Console.WriteLine(recipientAccount);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.recipient_account import RecipientAccount
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

payload = {"type": "bank-transfer", "primary": "true", "country": "CA", "currency": "CAD","accountNum": "604622847", "bankId": "123", "branchId": "47261",  "accountHolderName": "John Smith"}
response = client.recipientAccount.create('R-4625iLug2GKqKZG2WzAf3e', payload)

print(response.id)

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"
   }
}

To add a Recipient Account (ie payout method) such as a bank account or a PayPal account, to a Recipient, POST the following HTTP Request relevant to the Recipient’s payout method type.

A recipient can have multiple accounts with different payout methods assigned, however, only one (1) payout method can be their selected “primary” (active) account at any time. If you add the Recipient Account (payout method) when creating the Recipient, you do not need to add it again. The first account that is added to a recipient will be considered primary.

HTTP Request

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

Payment Rails currently supports two types of payout methods: paypal (PayPal) and bank-transfer (Bank Transfers).

Based on the payout method type (ie: paypal or bank-transfer), apply the appropriate fields below.

Bank Transfer

Fields Description
id
required
string
Recipient ID
type
required
string
Payout method, bank-transfer
currency
required
string
ISO3 currency code (ie: ‘USD’)
primary
optional
boolean
Set recipient account(payout method) as primary (active)
country
required
string
ISO ALPHA-2 country codes (ie: ‘US’)
accountHolderName
required
string
Exact name of account owner/holder on their bank account.
accountNum
required
string
Bank account number, includes Mexico CLABE, Argentina CBU. Does not include IBAN.
bankId
conditional
string
Bank ID, only required in Canada (Institution Code).
branchId
conditional
string
Bank’s branch number, only required in US (Routing Number), Australia (BSB), UK (Sort Code), Canada (Transit Number), India (IFSC Code)
iban
conditional
string
IBAN international bank account number, required for IBAN countries
swiftBic
conditional
string
SWIFT-BIC bank code, required for SWIFT countries (8 or 11 characters)


PayPal

Fields Description
id
required
string
Recipient ID
type
required
string
Payout method, paypal
primary
optional
boolean
Set recipient account(payout method) as primary (active)
emailAddress
required
string
Recipients PayPal account email address


Example of code for paypal type account

<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';

$response = PaymentRails\RecipientAccount::create($recipient_id, [
    "type" => "paypal",
    "emailAddress": "jsmithpaypal@example.com",
]);

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

<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';

$response = PaymentRails\RecipientAccount::create($recipient_id, [
    "type" => "bank-transfer",
    "primary" => true,
    "country" => "CA",
    "currency" => "CAD",
    "accoutNum" => "604622847",
    "branchId" => "47261",
    "bankId" => "123",
    "accountHolderName" => "John Smith",
]);

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

Errorss

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

<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';
$account_id = 'A-KKHb8MpFvju6vDMBLPmtej';

$response = PaymentRails\RecipientAccount::delete($recipient_id, $account_id);
const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.recipientAccount.remove('R-4625iLug2GKqKZG2WzAf3e', 'A-1a2b3c4f5g6h7j8k9l0m');
  console.log(response);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            var response = client.recipientAccount.delete("R-1234", "A-1234");

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.recipient_account import RecipientAccount
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.recipientAccount.delete('R-4625iLug2GKqKZG2WzAf3e','A-14WyPhgH2XPEy2Kha47MDk')

print(response)

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 Description
id
required
string
recipientId
recipientAccountId
required
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

<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';
$account_id = 'A-KKHb8MpFvju6vDMBLPmtej';

$response = PaymentRails\RecipientAccount::find($recipient_id, $account_id);
const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.recipientAccount.find('R-4625iLug2GKqKZG2WzAf3e', 'A-a1b2c3d4e5f5g6h7i8j9k0');
  console.log(response);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            RecipientAccount recipientAccount = client.recipientAccount.find(recipient.id, recipientAccount);

            Console.WriteLine(recipientAccount);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.recipient_account import RecipientAccount
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.recipientAccount.find('R-4625iLug2GKqKZG2WzAf3e','A-2DQMpN4jurTFn9gRxobx4C')

print(response.id)

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 Description
id
required
string
recipientId
recipientAccountId
required
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

<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';
$account_id = 'A-KKHb8MpFvju6vDMBLPmtej';

$response = PaymentRails\RecipientAccount::update($recipient_id, $account_id, [
    "primary" => false,
]);
const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  var body = {"primary": "false"};
  const response = await client.recipientAccount.update('R-4625iLug2GKqKZG2WzAf3e','A-a1b2c3d4e5f5g6h7i8j9k0', body);
  console.log(response);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            RecipientAccount recipientAccount = new RecipientAccount("bank-transfer", "EUR", null, null, "FR", "FR14 **** **** **** **** **** ***", "123456");
            RecipientAccount recipientAccount = client.recipientAccount.create(recipient.id, recipientAccount);

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

Example response (200 Ok)

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

Update existing Bank Transfer method

Set primary for an account

Example response (200 Ok)

{
  "ok": true,
  "object": "updated"
}
from paymentrails.configuration import Configuration
from paymentrails.recipient_account import RecipientAccount
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

payload = {"accountHolderName": "Acer Phillips"}
response = client.RecipientAccount.update('R-4625iLug2GKqKZG2WzAf3e','A-2DQMpN4jurTFn9gRxobx4C', payload)

print(response)

Update a payout method for a recipient. You can update existing primary method. When an account is updated, a new account id is generated.

HTTP Request

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

Fields Description
id
required
string
recipientId
recipientAccountId
required
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, mobile money, or credit/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-1a2B3c4D5e6F7g8H9i0J1k”, with the ‘B-’ prefix indicating Batch, followed by 22 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 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 (open) until your account is funded. You can see your account balance in the Dashboard under the ‘Transfers’ tab, which is updated in real time. You can also get your account balance by sending a GET request to the /balance endpoint.

Step 4: Process the batch

Once the batch is created, and there is sufficient 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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  var body = {
        "payments": [{
            "recipient": {
                "id": "R-1a2B3c4D5e6F7g8H9i0J1k"
            },
            "sourceAmount": "65",
            "sourceCurrency": "CAD"
        }]
    };
  const response = await client.batch.create(body);
  console.log(response.batch.id);
}
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
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';

$response = PaymentRails\Batch::create([
      'sourceCurrency' => 'CAD',
      'payments' => [
          'recipient' => [ 'id' => 'R-1a2B3c4D5e6F7g8H9i0J1k' ],
          'sourceAmount' => "65",
          'memo' => ''
      ]
]);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            Batch batch = new Batch("Integration Test Create", null, "USD", 0);

            Batch response = client.batch.create(batch);

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Batch
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

payload = {"payments": [{"recipient": {"id": "R-1a2B3c4D5e6F7g8H9i0J1k"},"sourceAmount": "65", "memo": "", "sourceCurrency": "USD"}]}
response = client.batch.create(payload)
print(response.id)

Example response (200 Ok)

{
  "ok": true,
  "batch": {
    "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
    "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 Description
sourceCurrency
optional
string
ISO3 currency code (ie: ‘USD’). The currency will default to your merchant accounts default currency. Or the sourceCurrency of the first payment.
description
optional
string
A description of the batch that you would like to add for internal reference
payments
optional
array
Array of payments
payments[].recipient
required
object
Specific Recipient within the Payment. One of id, email or referenceId must be provided
payments[].recipient.id
required
string
Recipient ID
payments[].recipient.email
required
string
Valid Email associated with the Recipient
payments[].sourceAmount
optional
string
You need either sourceAmount or targetAmount
payments[].targetAmount
optional
string
You need either sourceAmount or targetAmount
payments[].memo optional
string
Description of payment
HTTP Code Description
200 Batch successfully updated
400 One or more fields failed validation, see errors[] in response body
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
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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.batch.find('B-1a2b3c4d5e6f7g8h9i0jk1');
  console.log(response.batch.id);
}
require 'payment_rails'

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

batch = client.batches.find(batch_id)

puts batch
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';

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

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            Batch response = client.batch.find("B-1a2B3c4D5e6F7g8H9i0J1ks");

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Batch
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.batch.find('B-7ySLLBn57BhebTEMSiAkDH')
print(recipient.id)

Example response (200 Ok)

{
  "ok": true,
  "batch": {
    "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
    "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-1a2B3c4D5e6F7g8H9i0J1k",
          "recipient": {
            "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
            "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": "memo",
          "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-1a2B3c4D5e6F7g8H9i0J1k",
          "recipient": {
            "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
            "referenceId": "jsmith11@example.com",
            "email": "jsmith11@example.com",
            "name": "Richard Hendricks",
            "status": "active",
            "country": "Canada"
          },
          "method": "bank",
          "methodDisplay": "Bank Transfer",
          "status": "pending",
          "sourceAmount": "100.00",
          "targetAmount": "0.00",
          "isSupplyPayment": false,
          "memo": "memo",
          "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 Description
id
required
string
Batch 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

Delete a batch

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.batch.remove('B-1a2b3c4d5e6f7g8h9i0jk1');
  console.log(response);
}
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';

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

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            String response = client.batch.delete("B-1a2B3c4D5e6F7g8H9i0J1k");

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Batch
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.batch.delete('B-UPQsFgaADFetkXtwJPnjGF')
print(response)

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/:batch-id

{
  "ok": true,
  "object": "updated"
}
Fields Description
id
required
string
Batch ID
HTTP Code Description
200 Batch successfully deleted
400 Invalid status
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 multiple 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/:id

{
  "ok": true,
}
Fields Description
id
required
string
Batch ID
HTTP Code Description
200 Batch successfully deleted
400 Invalid status
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

List all batches

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.batch.search(1,10,"John");
  console.log(response);
}
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batches = PaymentRails\Batch::all($batch_id, $payment_id);
foreach ($batches as $batch) {
  print_r($batch);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            List<Batch> batches = client.batch.search("John",1,10);

            foreach(Batch batch in batches){
                Console.WriteLine(batches);
            }
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Batch
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.batch.search()
print(batch.id)

Expected response (200 Ok)

{
  "ok": true,
  "batches": [
    {
      "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
      "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-1a2B3c4D5e6F7g8H9i0J1k",
      "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 Description
page
required
int
The page number (default: 1)
pageSize
required
int
Number of records in a page (default: 10)
search
required
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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  var body = {
        "recipient": {
            "id": "R-1a2B3c4D5e6F7g8H9i0J1k"
        },
        "sourceAmount": "100.10",
        "sourceCurrency": "CAD",
        "memo": "Freelance payment"
    };
  const response = await client.payment.create(body);
  console.log(response.batch.id);
}
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';

$response = PaymentRails\Batch::createPayment($batch_id, [
    'recipient' => [ 'id' => 'R-1a2B3c4D5e6F7g8H9i0J1k' ],
    'sourceAmount' => "100.10",
    'memo' => 'Freelance payment'
]);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            Recipient recipient = new Recipient("individual", "TomJones@example.com", null, "Tom", "Jones", "R-1234c356vrcerc54js")

            Payment payment = new Payment(recipient, 10.00, "EUR", 0, null, null);
            Payment response = client.payment.create(payment);

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.payment import Payment
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

payload = {"recipient":{"id": "R-12345"},"sourceAmount":"100.10","memo":"Freelance payment"}
response = client.batch.create(payload)
print(response.id)

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 Description
recipient
required
object
recipient.id
required
string
Recipient ID assigned by Payment Rails, e.g. ‘R-12Ga2s31aH2233sa993HgsGs’. Used to identify the correct recipient to pay. You must provide at least one of: Email, Reference ID, or Recipient ID).
recipient.email
required
string
Recipient’s email address (e.g. john@email.com). Used to identify the correct recipient to pay. You must provide at least one of: Email, Reference ID, or Recipient ID).
recipient.referenceId
required
string
Recipient reference ID as assigned by your business (your internal user reference number, e.g. ‘U1234556678’). Used to identify the correct recipient to pay. You must provide at least one of: Email, Reference ID, or Recipient ID).
amount
conditional
string
Amount you wish to send, e.g. 100.00 USD, in your own currency.
currency
conditional
string
Currency of the amount you wish to send, e.g. 100.00 USD.
coverFees
optional
boolean
If the merchant should cover the network fees for this payment (default: false).
sourceAmount
conditional
string
deprecated
Amount you wish to send, e.g. 100.00 USD, in your own currency. Required only if sending a “sourceAmount”.
sourceCurrency
conditional
string
deprecated
Currency of the amount you wish to send, e.g. 100.00 USD. Required only if sending a “sourceAmount”.
targetAmount
conditional
string
deprecated
Amount you wish the recipient to receive, e.g. 85.00 EUR, in the recipient’s currency. Required only if sending a “Receive Amount”.
targetCurrency
conditional
string
deprecated
Currency of the amount you wish the recipient to receive, e.g. 85.00 EUR, in the recipient’s currency. Required only if sending a “Receive Amount”.
memo
optional
string
A short note which will be sent along with the payment to the recipient’s bank, as well as on the payment confirmation email if enabled. This memo will be displayed on the recipient’s bank statement descriptor to help them identify who the payment is from. The number of display characters depends on the recipient’s bank, so its best to keep short to less than 30 characters, otherwise the end may get cut off. Special characters are not supported on bank statement so will be stripped out by the bank. The memo field is good for referring to an invoice or reference number. We also strongly suggest to include your (short) business name at the start, as some banks globally dont support displaying your business as the sender name. A good sample memo for an invoice payment from Airbnb would be: “AIRBNB INV 12345678”.
externalId
optional
string/null
Storage for your internal reference ID for this payment.

Example response (200 Ok)

{
  "ok": true,
  "payment": {
    "id": "	P-1a2B3c4D5e6F7g8H9i0J1k",
    "recipient": {
      "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
      "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": "momo",
    "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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.payment.find('P-1a2B3c4D5e6F7g8H9i0J1k');
  console.log(response.payment.id);
}
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$payment_id = 'P-1a2B3c4D5e6F7g8H9i0J1k';

$response = PaymentRails\Batch::findPayment($batch_id, $payment_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            Payment response = PaymentRails_Payment.find("P-1a2B3c4D5e6F7g8H9i0J1k");

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.payment import Payment
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.payment.find('P-UPQsFgaADFetkXtwJPnjGF')
print(response)

Expected response (200 Ok)

{
  "ok": true,
  "payment": {
    "id": "P-1a2B3c4D5e6F7g8H9i0J1k",
    "recipient": {
      "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
      "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": "memo",
    "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-1a2B3c4D5e6F7g8H9i0J1k",
      "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/: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 Description
batch-id
required
string
Batch ID
payment-id
required
string
Payment 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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  var body = { "sourceAmount": "900.90" };
  const response = await client.payment.update('P-1a2B3c4D5e6F7g8H9i0J1k","B-1a2B3c4D5e6F7g8H9i0J1k', body);
  console.log(response);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            Recipient recipient = new Recipient("individual", "test.create" + uuid + "@example.com", null, "Tom", "Jones");
            Payment payment = new Payment(recipient, 10.00, "EUR", 0, null, null);
            payment.batchId ="B-12345";
            string response = PaymentRails_Payment.update(payment);

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.payment import Payment
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

payload = {"sourceAmount":"100.10"}
response = client.payment.create(payload)
print(response.id)

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 Description
batch-id
required
string
Batch ID
payment-id
required
string
Payment ID
amount
conditional
string
Amount you wish to send, e.g. 100.00 USD, in your own currency.
currency
conditional
string
Currency of the amount you wish to send, e.g. 100.00 USD.
coverFees
optional
boolean
If the merchant should cover the network fees for this payment (default: false).
sourceAmount
conditional
string
deprecated
Amount you wish to send, e.g. 100.00 USD, in your own currency. Required only if sending a “sourceAmount”.
sourceCurrency
conditional
string
deprecated
Currency of the amount you wish to send, e.g. 100.00 USD. Required only if sending a “sourceAmount”.
targetAmount
conditional
string
deprecated
Amount you wish the recipient to receive, e.g. 85.00 EUR, in the recipient’s currency. Required only if sending a “Receive Amount”.
targetCurrency
conditional
string
deprecated
Currency of the amount you wish the recipient to receive, e.g. 85.00 EUR, in the recipient’s currency. Required only if sending a “Receive Amount”.
memo
optional
string
A short note which will be sent along with the payment to the recipient’s bank, as well as on the payment confirmation email if enabled. This memo will be displayed on the recipient’s bank statement descriptor to help them identify who the payment is from. The number of display characters depends on the recipient’s bank, so its best to keep short to less than 30 characters, otherwise the end may get cut off. Special characters are not supported on bank statement so will be stripped out by the bank. The memo field is good for referring to an invoice or reference number. We also strongly suggest to include your (short) business name at the start, as some banks globally dont support displaying your business as the sender name. A good sample memo for an invoice payment from Airbnb would be: “AIRBNB INV 12345678”.
externalId
optional
string/null
Storage for your internal reference ID for this 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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  var body = {
        "recipient": {
            "id": "R-1a2B3c4D5e6F7g8H9i0J1k"
        },
        "sourceAmount": "100.10",
        "sourceCurrency": "CAD",
        "memo": "Freelance payment"
    };
  const response = await client.payment.remove('B-1a2B3c4D5e6F7g8H9i0J1k','P-1a2B3c4D5e6F7g8H9i0J1k');
  console.log(response);
}
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$payment_id = 'P-1a2B3c4D5e6F7g8H9i0J1k';

$response = PaymentRails\Batch::deletePayment($batch_id, $payment_id);
echo $response;
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            String response = client.payment.delete("P-1a2B3c4D5e6F7g8H9i0J1k","B-1a2B3c4D5e6F7g8H9i0J1k");

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.payment import Payment
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.payment.delete('P-UPQsFgaADFetkXtwJPnjGF')
print(response)

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/:batch-id/payments/:payment-id

Fields Description
batch-id
required
string
Batch ID
payment-id
required
string
Payment 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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.payment.search(1,10,"John");
  console.log(response);
}
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';

$payments = PaymentRails\Batch::payments($batch_id);
foreach ($payments as $payment) {
    print_r($payment);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            String batch_id = "B-1a2B3c4D5e6F7g8H9i0J1k";
            List<Payment> payments = PaymentRails_Payment.search("John", 1, 10, batch_id);

            foreach(Payment payment in payments){
                Console.WriteLine(payment);
            }
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Recipient
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.payment.search()
print(response)

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-1a2B3c4D5e6F7g8H9i0J1k",
         "recipient":{
            "id":"R-1a2B3c4D5e6F7g8H9i0J1k",
            "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":"memo",
         "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-1a2B3c4D5e6F7g8H9i0J1k",
         "recipient":{
            "id":"R-1a2B3c4D5e6F7g8H9i0J1k",
            "referenceId":"jsmith11@example.com",
            "email":"jsmith11@example.com",
            "name":"Richard Hendricks",
            "status":"active",
            "country":"Canada"
         },
         "method":"bank",
         "methodDisplay":"Bank Transfer",
         "status":"pending",
         "sourceAmount":"100.00",
         "targetAmount":"0.00",
         "isSupplyPayment":false,
         "memo":"memo",
         "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 Description
batch-id
required
string
Batch ID
Query Param Description
page
required
int
The page number (default: 1)
pageSize
required
int
Number of records in a page (default: 10)
search
required
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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.batch.generateQuote('B-1a2b3c4d5e6f7g8h9i0jk1');
  console.log(response);
}
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$payment_id = 'P-1a2B3c4D5e6F7g8H9i0J1k';

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

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            String response = client.batch.generateQuote("B-1a2B3c4D5e6F7g8H9i0J1k");

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Batch
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.batch.generate_quote('B-UPQsFgaADFetkXtwJPnjGF')
print(response)

Example response (200 Ok)

{
  "ok": true,
  "batch": {
    "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
    "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/:batch-id/generate-quote

Fields Description
batch-id
required
string
Batch 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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.batch.summary('B-1a2b3c4d5e6f7g8h9i0jk1');
  console.log(response);
}
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';

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

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");
            String response = client.batch.summary("B-1a2B3c4D5e6F7g8H9i0J1k");

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Batch
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.batch.summary('B-WeGxM72wG6KJjqYXfqkwBK')
print(recipient.id)

Example response (200 Ok)

{
  "ok": true,
  "batchSummary": {
    "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
    "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 Description
batch-id
required
string
Batch 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

const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.batch.startProcessing('B-1a2b3c4d5e6f7g8h9i0jk1');
  console.log(response);
}
require 'payment_rails'

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

client.batches.start_processing!(batch_id)
<?php
use PaymentRails;

PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');

$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';

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

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");

            String batch_id = "B-1a2B3c4D5e6F7g8H9i0J1k";
            String response = client.batch.processBatch(batch_id);

            Console.WriteLine(response);
            Console.Read();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.batch import Batch
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.batch.process_batch('B-UPQsFgaADFetkXtwJPnjGF')
print(response)
{
  "ok": true,
  "batch": {
    "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
    "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/:batch-id/start-processing

Fields Description
batch-id
required
string
Batch ID
HTTP Code Description
200 Batch successfully processed
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
non_sufficient_funds Insufficient funds

Balances


Balances relates to your business (merchant) account balance. 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. Balance always refers to the merchant’s funding account balances. 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 "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
  -H "X-PR-Timestamp: <timestamp>" \
  -X GET \
  https://api.paymentrails.com/v1/balances
const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.balances.find();
  console.log(response);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");
            Dictionary<String, Balance> balances = client.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();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.balances import Balances
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.balances.find()

print(response)

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/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 "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
  -H "X-PR-Timestamp: <timestamp>" \
  -X GET \
  https://api.paymentrails.com/v1/balances/paymentrails
const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.balances.find('paymentrails');
  console.log(response);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");
            Dictionary<String, Balance> balances = client.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();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.balances import Balances
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.balances.find("paymentrails")

print(response)

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/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 "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
  -H "X-PR-Timestamp: <timestamp>" \
  -X GET \
  https://api.paymentrails.com/v1/balances/paypal
const paymentrails = require('paymentrails');

const client = paymentrails.connect({
  key: "YOUR-API-KEY",
  secret: "YOUR-API-SECRET",
  environment: "production",
});

async function main() {
  const response = await client.balances.find('paypal');
  console.log(response);
}
using paymentrails.Types;
using paymentrails;

class Program
    {
        static void Main(string[] args)
        {
            var client = new PaymentRails_Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY", "production");
            Dictionary<String, Balance> balances = client.blances.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();
        }
    }
from paymentrails.configuration import Configuration
from paymentrails.balances import Balances
from paymentrails.gateway import Gateway

client = Configuration.gateway("YOUR-PUBLIC-API","YOUR-PRIVATE-API","production")

response = client.balances.find("paypal")

print(response)

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/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
Kosovo XK
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
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 16 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
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
required
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 cannot be sent a payment. The minimum amount of profile info required is 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. This is done 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 cannot be sent a payment. It is used when a recipient’s 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.
archived This status is used to classify recipients that are deleted. Once a recipient is deleted, it becomes archived. Archived recipients are NOT deleted, they can aslo be un-archived.
suspended The Suspended status is used for flagging fraudulent or bad recipients. These recipients cannot 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 automatically be updated to ‘Failed’ if after an attempt to process it fails for any reason, 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, but was retured as not deliverable at a later time (from minutes up to weeks later). This is mostly occurs when the bank account number that was provided was found to be invalid, or there was a 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 confirm their bank account or payout method details. Once updated, create a new payment to send to the recipients using an 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.
processing A payment’s status becomes processing once a user attempts to process a payment.

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.
awaiting_approval A batch in the the approval process if it is configured. You can update a batch, but this will reset the batch to the open state
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 cannot 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 cannot Delete (DELETE) or update (PATCH) a batch once it is in Processing status.
complete One or more payments in a batch has been successfully processed, it will be updated as Complete. You cannot Delete (DELETE) or update (PATCH) a batch once it is in Complete status.
failed All payment in the batch have failed to be processed. You cannot Delete (DELETE) or update (PATCH) a batch once it is in failed 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


United Kingdom - Faster Payments System (FPS) & SEPA, on domestic local rails

Country Currency Received by Recipient Daily cut off
United Kingdom GBP, EUR Same or next business day 2:00pm EST


International ACH & SEPA - on domestic local rails in 65 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
Austria EUR Next business day 2:00pm EST
Barbados BBD 1-2 business days 2:00pm EST
Belgium EUR Next business day 2:00pm EST
Bosnia & Herzegovina BAM 1-2 business days 2:00pm EST
Brazil BRL 1-2 business days 2:00pm EST
Bulgaria BGN, EUR 1-2 business days 2:00pm EST
China CNY 1-2 business days 2:00pm EST
Croatia HRK, EUR 1-2 business days 2:00pm EST
Cyprus EUR Next business day 2:00pm EST
Czech Republic CZK, EUR 1-2 business days 2:00pm EST
Denmark DKK, EUR 1-2 business days 2:00pm EST
Egypt EGP 1-2 business days 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
French Guiana EUR Next business day 2:00pm EST
Germany EUR Next business day 2:00pm EST
Gibraltar GIP, EUR 1-2 business days 2:00pm EST
Greece EUR Next business day 2:00pm EST
Guadeloupe EUR Next business days 2:00pm EST
Hong Kong HKD 1-2 business days 2:00pm EST
Hungary HUF, EUR 1-2 business days 2:00pm EST
Iceland ISK, EUR 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
Ireland EUR Next business day 2:00pm EST
Italy EUR Next business day 2:00pm EST
Jamaica JMD 1-2 business days 2:00pm EST
Latvia EUR Next business day 2:00pm EST
Lithuania EUR Next business day 2:00pm EST
Liechtenstein CHF, EUR 1-2 business days 2:00pm EST
Luxembourg EUR Next business day 2:00pm EST
Macau MOP 1-2 business days 2:00pm EST
Malta EUR Next business day 2:00pm EST
Martinique EUR Next business days 2:00pm EST
Mayotte EUR Next business days 2:00pm EST
Monaco EUR Next business day 2:00pm EST
Morocco MAD 1-2 business days 2:00pm EST
Netherlands EUR Next business day 2:00pm EST
New Zealand NZD 1-2 business days 2:00pm EST
Norway NOK, EUR 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, EUR 1-2 business days 2:00pm EST
Portugal EUR Next business day 2:00pm EST
Reunion EUR Next business days 2:00pm EST
Romania RON, EUR 1-2 business days 2:00pm EST
Russia RUB 1-2 business days 2:00pm EST
Saint Martin (French part) EUR Next business day 2:00pm EST
San Marino EUR Next business day 2:00pm EST
Singapore SGD 1-2 business days 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
Sri Lanka LKR 1-2 business days 2:00pm EST
St Barthelemy EUR Next business days 2:00pm EST
St Pierre & Miquelon EUR Next business day 2:00pm EST
Sweden SEK, EUR 1-2 business days 2:00pm EST
Switzerland CHF, EUR 1-2 business days 2:00pm EST
Thailand THB 1-2 business days 2:00pm EST
Turkey TRY 1-2 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) in 153 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 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
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
Mauritania MRO 3-5 business days 2:00pm EST
Mauritius MUR 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
Rwanda RWF 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 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 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
Trinidad & Tobago TTD 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, C#, and Python.

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
Python https://github.com/PaymentRails/python-sdk
PHP https://github.com/PaymentRails/php-sdk
Javascript https://github.com/PaymentRails/javascript-sdk
C# https://github.com/PaymentRails/paymentrails_dotnet
Ruby Coming Soon
Java Coming Soon