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:

GET - Read resources
POST - Create new resources
PATCH - Update an existing resource
DELETE - Remove resources

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.

The rate limits are as follows:

200 requests per minute from any single IP address
100 requests per minute for any regular merchant
50 requests per minute for any sandbox merchant

If your requests are being rate limited, HTTP response code 429 will be returned with an rate_limit_exceeded error. Contact us to discuss rate limits at api@paymentrails.com.

Deprecation Policy

Technology evolves quickly and we are always looking for better ways to serve our customers. From time to time we need to make room for innovation by removing sections of code that are no longer necessary. We understand this can be disruptive and consequently we have designed a Deprecation Policy that protects our customers’ investment and that allows us to take advantage of modern tools, frameworks and practices in developing software.

Deprecation means that we discourage the use of a feature, design or practice because it has been superseded or is no longer considered efficient or safe but instead of removing it immediately, we mark it as Deprecated to provide backwards compatibility and time for you to update your projects. While the deprecated feature remains in the API and/or SDK for a period of time, we advise that you replace it with the recommended alternative which is explained in the relevant section of API documentation or the SDK code.

We remove deprecated features after 3 months from the time of announcement.

The security of our customers’ assets is of paramount importance to us and sometimes we have to deprecate features because they may pose a security threat or because new, more secure, ways are available. On such occasions we reserve the right to set a different deprecation period which may range from immediate removal to the standard 3 months.

Once a feature has been marked as deprecated, we no longer develop the code or implement bug fixes. We only do security fixes.

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:

Authorization Where your signed request information will be transmitted
X-PR-Timestamp The timestamp of your request

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

timestamp This is the same value as transmitted in the X-PR-Timestamp header and is the seconds past 1970 (Unix Epoch) in UTC time.
method The request method in all upper case.
requestPath The full request path including all query parameters (e.g. /v1/recipients/?search=bob)
body The JSON body of the request.

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 Payment Rails 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-letter ISO 639-1 language code and optional 2-letter ISO-3166 country code. (eg. “en” and “en-CA” both are acceptable) Supported Languages
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
accounts object	Recipient Account information
tags array	A collection of keywords to help identify the recipient.
contactEmails array	A list of secondary email addresses that will be CC’d in all recipient emails (excluding Portal login code/authentication emails).

Address

Example Address

{
  "street1": "123 Main St",
  "street2": "",
  "city": "San Francisco",
  "region": "CA",
  "postalCode": "94131",
  "country": "US",
  "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 accept ISO 3166-1 alpha-2 (e.g. ‘US’, ‘DE’)
region optional 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",
    address: {
      city: "Montréal",
      country: "CA",
      phone: "+15141111111",
      postalCode: "A1A 1A1",
      region: "BC",
      street1: "Toad Street",
      street2: "Avenue Rock",
    },
  };

  const recipient = await client.recipient.create(body);
  console.log(recipient.id);
}


require 'paymentrails'

recipient = {
  type:"individual",
  firstName: 'John',
  lastName: 'Smith',
  email: 'jsmith@example.com',
  address: {
    city: "Montréal",
    country: "CA",
    phone: "+15141111111",
    postalCode: "A1A 1A1",
    region: "BC",
    street1: "Toad Street",
    street2: "Avenue Rock"
  }
  account: {
    type: 'paypal',
    emailAddress: 'jsmithpaypal@example.com'
  }
}

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

client.recipient.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',
    'address' => [
      "city" => "Montréal",
      "country" => "CA",
      "phone" => "+15141111111",
      "postalCode" => "A1A 1A1",
      "region" => "BC",
      "street1" => "Toad Street",
      "street2" => "Avenue Rock",
    ],
]);


using PaymentRails.Types;
using PaymentRails;

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

            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-1a3B3c4D5e6F7g8H9i0J1k",
    "referenceId": "jsmith11@example.com",
    "email": "jsmith11@example.com",
    "name": "John Smith",
    "lastName": "John",
    "firstName": "Smith",
    "type": "individual",
    "status": "incomplete",
    "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",
    "placeOfBirth": null,
    "ssn": null,
    "tags": [],
    "passport": "",
    "payoutMethod": "bank-transfer",
    "compliance": {
      "status": "verified",
      "checkedAt": "2017-03-20T19:06:23.916Z"
    },
    "accounts": [],
    "address": {
      "street1": "",
      "street2": null,
      "city": "",
      "postalCode": "",
      "phone": "",
      "country": null,
      "region": null
    },
    "primaryCurrency": "CAD"
  }
}

Example response of Recipient with address (200 Ok)

{
  "ok": true,
  "recipient": {
    "id": "R-1a3B3c4D5e6F7g8H9i0J1k",
    "referenceId": "jsmith11@example.com",
    "email": "jsmith11@example.com",
    "name": "John Smith",
    "lastName": "John",
    "firstName": "Smith",
    "type": "individual",
    "status": "incomplete",
    "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",
    "placeOfBirth": null,
    "ssn": null,
    "tags": [],
    "passport": "",
    "payoutMethod": "bank-transfer",
    "compliance": {
      "status": "verified",
      "checkedAt": "2017-03-20T19:06:23.916Z"
    },
    "accounts": [],
    "address": {
      "street1": "Apt# 14",
      "street2": null,
      "city": "",
      "postalCode": "H3WXXX",
      "phone": "",
      "country": "CA",
      "region": "QC"
    },
    "primaryCurrency": "CAD"
  }
}

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
referenceId 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
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
401	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 client.recipient.find("R-1a2B3c4D5e6F7g8H9i0J1k");
  console.log(recipient.id);
}

require 'paymentrails'

recipient_id = 3
client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

recipient = client.recipient.find(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");

            String recipient_id = "R-1a2B3c4D5e6F7g8H9i0J1k";
            Recipient response = client.recipient.find(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.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",
    "placeOfBirth": null,
    "ssn": null,
    "tags": [],
    "passport": "",
    "payoutMethod": "bank-transfer",
    "compliance": {
      "status": "verified",
      "checkedAt": "2017-03-20T19:06:23.916Z"
    },
    "accounts": [
      {
        "accountHolderName": "Richard Hendricks",
        "bankId": "123",
        "currency": "CAD",
        "country": "CA",
        "bankName": "TD CANADA TRUST",
        "branchId": "47261",
        "accountNum": "*****47"
      }
    ],
    "address": {
      "street1": "Apt# 14",
      "street2": null,
      "city": "",
      "postalCode": "H3WXXX",
      "phone": "",
      "country": "CA",
      "region": "QC"
    },
    "primaryCurrency": "CAD"
  }
}

HTTP Code	Description
200	Recipient Object
401	Invalid API key
404	Recipient not found
500	Internal error

Errors

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 'paymentrails'

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

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

client.recipient.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");

            Recipient recipient = new Recipient("individual", "TomJones@example.com", null, "Tom", "Jones","R-1234565vcr4");
            bool res = client.recipient.update(recipient);
        }
    }

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,
  "recipient": {
    "id": "R-1a3B3c4D5e6F7g8H9i0J1k",
    "referenceId": "jsmith11@example.com",
    "email": "jsmith11@example.com",
    "name": "John Smith",
    "lastName": "John",
    "firstName": "tom",
    "type": "individual",
    "status": "incomplete",
    "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",
    "placeOfBirth": null,
    "ssn": null,
    "tags": [],
    "passport": "",
    "payoutMethod": "bank-transfer",
    "compliance": {
      "status": "verified",
      "checkedAt": "2017-03-20T19:06:23.916Z"
    },
    "accounts": [],
    "address": {
      "street1": "Apt# 14",
      "street2": null,
      "city": "",
      "postalCode": "H3WXXX",
      "phone": "",
      "country": "CA",
      "region": "QC"
    },
    "primaryCurrency": "CAD"
  }
}

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
401	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 'paymentrails'

recipient_id = "R-1a2B3c4D5e6F7g8H9i0J1k"
client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

client.recipient.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
401	Invalid API key
404	Recipient not found
500	Internal error

Errors

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
401	Invalid API key
404	Recipient not found
500	Internal error

Errors

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 'paymentrails'

client  = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")
results = client.recipient.search()

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.recipient import Recipient
from paymentrails.gateway import Gateway

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

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

Response (200 Ok)

{
  "ok": true,
  "recipients": [
    {
      "id": "R-1a2B3c4D5e6F7g8H9i0J1k",
      "referenceId": "rhendricks@example.com",
      "email": "rhendricks@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",
      "placeOfBirth": null,
      "ssn": null,
      "tags": [],
      "passport": "",
      "payoutMethod": "bank-transfer",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "accounts": [
        {
          "accountHolderName": "Richard Hendricks",
          "bankId": "123",
          "currency": "CAD",
          "country": "CA",
          "bankName": "TD CANADA TRUST",
          "branchId": "47261",
          "accountNum": "*****47"
        }
      ],
      "address": {
        "street1": "Apt# 14",
        "street2": null,
        "city": "",
        "postalCode": "H3WXXX",
        "phone": "",
        "country": "CA",
        "region": "QC"
      },
      "primaryCurrency": "CAD"
    },
    {
      "id": "R-1a3B3c4D5e6F7g8H9i0J1k",
      "referenceId": "jsmith11@example.com",
      "email": "jsmith11@example.com",
      "name": "John Smith",
      "lastName": "John",
      "firstName": "Smith",
      "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",
      "placeOfBirth": null,
      "ssn": null,
      "tags": [],
      "passport": "",
      "payoutMethod": "bank-transfer",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "accounts": [
        {
          "accountHolderName": "John Smith",
          "bankId": "123",
          "currency": "CAD",
          "country": "CA",
          "bankName": "TD CANADA TRUST",
          "branchId": "47261",
          "accountNum": "*****47"
        }
      ],
      "address": {
        "street1": "Apt# 14",
        "street2": null,
        "city": "",
        "postalCode": "H3WXXX",
        "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 recipient statuses
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
401	Invalid API key
500	Internal error

Errors

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
401	Invalid API key
404	Recipient not found
500	Internal error

Errors

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.payment.search({
    recipientId: "R-1a2B3c4D5e6F7g8H9i0J1k",
  });
  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",
        "placeOfBirth": null,
        "ssn": null,
        "tags": [],
        "passport": "",
        "payoutMethod": "bank-transfer",
        "compliance": {
          "status": "verified",
          "checkedAt": "2017-03-20T19:06:23.916Z"
        },
        "accounts": [
          {
            "accountHolderName": "Richard Hendricks",
            "bankId": "123",
            "currency": "CAD",
            "country": "CA",
            "bankName": "TD CANADA TRUST",
            "branchId": "47261",
            "accountNum": "*****47"
          }
        ],
        "address": {
          "street1": "Apt# 14",
          "street2": null,
          "city": "",
          "postalCode": "H3WXXX",
          "phone": "",
          "country": "CA",
          "region": "QC"
        },
        "primaryCurrency": "CAD"
      },
      "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",
        "placeOfBirth": null,
        "ssn": null,
        "tags": [],
        "passport": "",
        "payoutMethod": "bank-transfer",
        "compliance": {
          "status": "verified",
          "checkedAt": "2017-03-20T19:06:23.916Z"
        },
        "accounts": [
          {
            "accountHolderName": "Richard Hendricks",
            "bankId": "123",
            "currency": "CAD",
            "country": "CA",
            "bankName": "TD CANADA TRUST",
            "branchId": "47261",
            "accountNum": "*****47"
          }
        ],
        "address": {
          "street1": "Apt# 14",
          "street2": null,
          "city": "",
          "postalCode": "H3WXXX",
          "phone": "",
          "country": "CA",
          "region": "QC"
        },
        "primaryCurrency": "CAD"
      },
      "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
401	Invalid API key
404	Recipient not found
500	Internal error

Errors

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

Retrieve recipient’s offline 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.offlinePayment.search({
    recipientId: "R-1a2B3c4D5e6F7g8H9i0J1k",
  });
  console.log(response);
}

<?php
use PaymentRails;

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

$offlinePayments = PaymentRails\OfflinePayments::search(["recipientId" => "R-1a2B3c4D5e6F7g8H9i0J1k"]);
foreach ($offlinePayments as $offlinePayment) {
  print_r($offlinePayment);
}


require 'paymentrails'

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

offline_payments = client.offline_payment.search("R-1a2B3c4D5e6F7g8H9i0J1k")

Retrieve a recipient’s offline payments

HTTP Request

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

Fields	Description
id required string	Recipient ID

Response (200 Ok)

{
  "ok": true,
  "offlinePayments": [
    {
      "amount": "100.00",
      "category": "services",
      "createdAt": "2019-10-31T20:24:29.954Z",
      "currency": "USD",
      "deletedAt": null,
      "equivalentWithholdingAmount": "24.00",
      "equivalentWithholdingCurrency": "USD",
      "externalId": "id-123",
      "id": "OP-3xghXMEcedrjPEo3KedqsR",
      "memo": "A memo",
      "processedAt": "2019-08-15T20:23:59.000Z",
      "recipientId": "R-4321c356vrcerc54js",
      "tags": [],
      "taxReportable": true,
      "updatedAt": "2019-10-31T20:24:29.954Z",
      "withholdingAmount": "24.00",
      "withholdingCurrency": "USD"
    },
    {
      "amount": "100.00",
      "category": "services",
      "createdAt": "2019-10-31T20:24:29.954Z",
      "currency": "USD",
      "deletedAt": null,
      "equivalentWithholdingAmount": "24.00",
      "equivalentWithholdingCurrency": "USD",
      "externalId": "id-123",
      "id": "OP-4xghXMEcedrjPEo3KedqsR",
      "memo": "A memo",
      "processedAt": "2019-08-15T20:23:59.000Z",
      "recipientId": "R-4321c356vrcerc54js",
      "tags": [],
      "taxReportable": true,
      "updatedAt": "2019-10-31T20:24:29.954Z",
      "withholdingAmount": "24.00",
      "withholdingCurrency": "USD"
    }
  ]
}

HTTP Code	Description
200	Recipient’s payments
401	Invalid API key
404	Recipient not found
500	Internal error

Errors

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
`check`	live	USD Checks printed and mailed to US based recipients
`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` or `check`
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`)
mailing object	The mailing address associated to a `check` account

Mailing

Example Mailing attributes

{
  "name": "Jon Smith",
  "street1": "123 Main St",
  "street2": "",
  "city": "San Francisco",
  "region": "CA",
  "postal": "94131",
  "country": "US"
}

Field	Description
name required string	Name of individual or business to be written on the `check` (Pay to the order of).
street1 required string	Mailing Street 1 Address. PO Box addresses are acceptable.
street2 optional string	Mailing Street 2 Address (e.g. Apt 5).
city required string	Mailing address City (e.g. Miami).
postal required string	Mailing address Zip code (e.g. 90210 or 90210-1234).
country required string	Mailing Country. Must be `US`
region required string	Region code Mailing address State / 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.

Create Account

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);
}

require 'paymentrails'

account = {
  "type": "bank-transfer",
  "primary": "true",
  "country": "CA",
  "currency": "CAD",
  "accountNum": "012345678",
  "bankId": "004",
  "branchId": "47261",
  "accountHolderName": "John Smith"
}

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

client.recipient_account.create('R-4625iLug2GKqKZG2WzAf3e', 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"
]);

using PaymentRails.Types;
using PaymentRails;

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

            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
401	Invalid API key
404	Object not found
406	One or more fields failed validation, see errors[] in response body
500	Internal error

Errors

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

<?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");

            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 Account

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
401	Invalid API key
404	Object not found
500	Internal error

Errors

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");

            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
401	Invalid API key
404	Object not found
500	Internal error

Errors

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");

            RecipientAccount recipientAccount = new RecipientAccount("bank-transfer", "EUR", "A-UnukXDTbLtxtDLXVZGE9re", null, "FR", "FR14 1234 1234 1234 1234 1234 123", "123456");
            RecipientAccount recipientAccount = client.recipientAccount.update(recipient.id, recipientAccount);

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

Example response (200 Ok)

{
{
  "ok": true
  "account": {
       "recipientAccountId": "A-UnukXDTbLtxtDLXVZGE9re",
       "primary": true,
       "currency": "EUR",
       "country": "FR",
       "type": "bank-transfer",
       "accountNum": "FR14 **** **** **** **** **** ***",
       "accountHolderName": "John Smith",
   }
}
}

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
401	Invalid API key
404	Object not found
406	One or more fields failed validation, see errors[] in response body
500	Internal error

Errors

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",
        },
        amount: "65",
        currency: "CAD",
      },
    ],
  };
  const response = await client.batch.create(body);
  console.log(response.batch.id);
}

require 'paymentrails'

# "id" replaceable with referenceId or email
batch = {
  description: "Batch Description",
  currency: "USD",
  payments: [
    { recipient: { id: "R-RECIPIENT_ID" }, amount: "100", currency: "USD" },
    { recipient: { id: "R-RECIPIENT_ID" }, amount: "200", currency: "USD", }
  ]
}

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

client.batch.create(batch)

<?php
use PaymentRails;

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

$response = PaymentRails\Batch::create([
      'description' => "Batch Description",
      'currency' => 'USD',
      'payments' => [
          0 => [
              "recipient" => [
                  "id" => "R-RECIPIENT_ID",
              ],
              "amount" => "100",
              "currency" => "USD"
          ],
          1 => [
              "recipient" => [
                  "email" => "RECIPIENT_EMAIL",
              ],
              "amount" => "200",
              "currency" => "USD"
          ],
      ],
]);

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");

            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"}, "amount": "65", "memo": "", "currency": "USD"}]}
response = client.batch.create(payload)
print(response.id)

Example response (200 Ok)

{
  "ok": true,
  "batch": {
    "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
    "status": "open",
    "tags": [],
    "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",
    "quoteExpiredAt": "2017-03-28T04:08:52.634Z"
  }
}

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
currency 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 conditional string	Recipient ID, only required if no other recipient identifier is provided
payments[].recipient.email conditional string	Valid Email associated with the Recipient, only required if no other recipient identifier is provided
payments[].amount required string	The amount in the specified currency
payments[].currency required string	The amount’s ISO3 currency code (ie: ‘USD’)
payments[].memo optional _string_	Description of payment

Amount and Currency

    <p>In most cases, you will specify an amount and a currency when you send a payment. For example, you need to send a payout to a freelancer for 100 USD, and your Payment Rails funding currency is USD. So the payment's amount is 100.00 and it's currency is USD.</p>

    <p>In some cases, such as when paying a supplier invoice, you might owe the supplier a specific amount, after any fees, such as 200 EUR. Here, you simply need to set the payment's amount to 200, and it's currency to EUR, and additionally set it's "coverFees" to TRUE. You would pay the fees in this case so the Recipient doesn't have to.</p>

</div>

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

Errors

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 'paymentrails'

batch_id = "B-1a2B3c4D5e6F7g8H9i0J1k"
client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-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");

            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",
    "tags": [],
    "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",
    "quoteExpiredAt": "2017-03-29T04:08:52.634Z",
    "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
401	Invalid API key
404	Object not found
500	Internal error

Errors

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");

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

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

Fields	Description
id required string	Batch ID

HTTP Code	Description
200	Batch successfully deleted
400	Invalid status
401	Invalid API key
404	Object not found
500	Internal error

Errors

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 with a list of batch ids in the request body.

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

HTTP Request

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

{
  "ok": true
}

Fields	Description
ids required array	Batch IDs

HTTP Code	Description
200	Batch successfully deleted
400	Invalid status
401	Invalid API key
404	Object not found
500	Internal error

Errors

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");

            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",
      "status": "accepted",
      "tags": [],
      "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",
      "quoteExpiredAt": "2017-01-12T04:08:52.634Z"
    },
    {
      "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
      "status": "complete",
      "tags": [],
      "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",
      "quoteExpiredAt": "2017-01-12T04:08:52.634Z"
    }
  ]
}

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 optional string	Wildcard search across batches

HTTP Code	Description
200	List of batches
401	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",
  };
  var batchId = "B-1a2B3c4D5e6F7g8H9i0J1k";
  const response = await client.payment.create(batchId, 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");

            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.batchId = "B-1a2B3c4D5e6F7g8H9i0J1k";
            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"}
batchId = "B-1a2B3c4D5e6F7g8H9i0J1k"
response = client.payment.create(payload, batchId)
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	Information about the recipient of the payment. One identifier must be provided.
recipient.id conditional 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 conditional 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 conditional 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, if present it must be unique.
taxReportable optional boolean	If the merchant should apply tax withholding on the payment, and in turn adding it to the tax reporting (default: true).
forceUsTaxActivity optional boolean	Set this to true ONLY when the tax reporting system is enabled AND the payment is taxReportable AND you intend to override the recipient’s W8’s “certify no us activities” to assert that the payment definately DOES involve US activities. (default: false).
category conditional string	Income type if the payment is Tax Reportable, either `services`, `royalties`, `rent`, `royalties_film` or `prizes`, otherwise `education` and `refunds` are supported for non Tax Reportable payments.

Example response (200 Ok)

{
  "ok": true,
  "payment": {
    "id": "	P-1a2B3c4D5e6F7g8H9i0J1k",
    "recipient": {
      "id": "R-1a3B3c4D5e6F7g8H9i0J1k",
      "referenceId": "jsmith11@example.com",
      "email": "jsmith11@example.com",
      "name": "John Smith",
      "lastName": "John",
      "firstName": "Smith",
      "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",
      "placeOfBirth": null,
      "ssn": null,
      "tags": [],
      "passport": "",
      "payoutMethod": "bank-transfer",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "accounts": [
        {
          "accountHolderName": "John Smith",
          "bankId": "123",
          "currency": "CAD",
          "country": "CA",
          "bankName": "TD CANADA TRUST",
          "branchId": "47261",
          "accountNum": "*****47"
        }
      ],
      "address": {
        "street1": "Apt# 14",
        "street2": null,
        "city": "",
        "postalCode": "H3WXXX",
        "phone": "",
        "country": "CA",
        "region": "QC"
      },
      "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
    },
    "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"
    },
    "sourceCurrency": "CAD",
    "sourceCurrencyName": "Canadian Dollar",
    "targetCurrency": "CAD",
    "targetCurrencyName": "Canadian Dollar",
    "category": "services",
    "coverFees": false,
    "currency": "CAD",
    "equivalentWithholdingAmount": "0.00",
    "equivalentWithholdingCurrency": "CAD",
    "estimatedDeliveryAt": null,
    "externalId": "",
    "failureMessage": null,
    "initiatedAt": null,
    "isSupplyPayment": false,
    "merchantId": "M-Osg3dh2b0m1cRg9b8Shd2d",
    "methodDisplay": "Bank Transfer",
    "returnedAmount": "0.00",
    "returnedAt": null,
    "returnedNote": null,
    "returnedReason": [],
    "settledAt": null,
    "tags": [],
    "taxBasisAmount": "0.00",
    "taxBasisCurrency": "CAD",
    "taxReportable": true,
    "withholdingAmount": "0.00",
    "withholdingCurrency": "CAD"
  }
}

HTTP Code	Description
200	Batch successfully deleted
401	Invalid API key
404	Object not found
406	Validation error
500	Internal error

Errors

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");

            Payment response = client.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": "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",
      "placeOfBirth": null,
      "ssn": null,
      "tags": [],
      "passport": "",
      "payoutMethod": "bank-transfer",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "accounts": [
        {
          "accountHolderName": "Richard Hendricks",
          "bankId": "123",
          "currency": "CAD",
          "country": "CA",
          "bankName": "TD CANADA TRUST",
          "branchId": "47261",
          "accountNum": "*****47"
        }
      ],
      "address": {
        "street1": "Apt# 14",
        "street2": null,
        "city": "",
        "postalCode": "H3WXXX",
        "phone": "",
        "country": "CA",
        "region": "QC"
      },
      "primaryCurrency": "CAD"
    },
    "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"
    },
    "category": "services",
    "coverFees": false,
    "currency": "CAD",
    "equivalentWithholdingAmount": "0.00",
    "equivalentWithholdingCurrency": "CAD",
    "estimatedDeliveryAt": null,
    "externalId": "",
    "failureMessage": null,
    "initiatedAt": null,
    "isSupplyPayment": false,
    "merchantId": "M-Osg3dh2b0m1cRg9b8Shd2d",
    "methodDisplay": "Bank Transfer",
    "returnedAmount": "0.00",
    "returnedAt": null,
    "returnedNote": null,
    "returnedReason": [],
    "settledAt": null,
    "tags": [],
    "taxBasisAmount": "0.00",
    "taxBasisCurrency": "CAD",
    "taxReportable": true,
    "withholdingAmount": "0.00",
    "withholdingCurrency": "CAD"
  }
}

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
401	Invalid API key
404	Object not found
500	Internal error

Errors

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");

            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 = client.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, if present it must be unique.
taxReportable optional boolean	If the merchant should apply tax withholding on the payment, and in turn adding it to the tax reporting (default: true).
category conditional string	Income type if the payment is Tax Reportable, either `services`, `royalties`, `rent` or `goods`.

Response (200 Ok)

{
  "ok": true,
  "payment": {
    "id": "	P-1a2B3c4D5e6F7g8H9i0J1k",
    "recipient": {
      "id": "R-1a3B3c4D5e6F7g8H9i0J1k",
      "referenceId": "jsmith11@example.com",
      "email": "jsmith11@example.com",
      "name": "John Smith",
      "lastName": "John",
      "firstName": "Smith",
      "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",
      "placeOfBirth": null,
      "ssn": null,
      "tags": [],
      "passport": "",
      "payoutMethod": "bank-transfer",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "accounts": [
        {
          "accountHolderName": "John Smith",
          "bankId": "123",
          "currency": "CAD",
          "country": "CA",
          "bankName": "TD CANADA TRUST",
          "branchId": "47261",
          "accountNum": "*****47"
        }
      ],
      "address": {
        "street1": "Apt# 14",
        "street2": null,
        "city": "",
        "postalCode": "H3WXXX",
        "phone": "",
        "country": "CA",
        "region": "QC"
      },
      "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
    },
    "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"
    },
    "sourceCurrency": "CAD",
    "sourceCurrencyName": "Canadian Dollar",
    "targetCurrency": "CAD",
    "targetCurrencyName": "Canadian Dollar",
    "category": "services",
    "coverFees": false,
    "currency": "CAD",
    "equivalentWithholdingAmount": "0.00",
    "equivalentWithholdingCurrency": "CAD",
    "estimatedDeliveryAt": null,
    "externalId": "",
    "failureMessage": null,
    "initiatedAt": null,
    "isSupplyPayment": false,
    "merchantId": "M-Osg3dh2b0m1cRg9b8Shd2d",
    "methodDisplay": "Bank Transfer",
    "returnedAmount": "0.00",
    "returnedAt": null,
    "returnedNote": null,
    "returnedReason": [],
    "settledAt": null,
    "tags": [],
    "taxBasisAmount": "0.00",
    "taxBasisCurrency": "CAD",
    "taxReportable": true,
    "withholdingAmount": "0.00",
    "withholdingCurrency": "CAD"
  }
}

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

Errors

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");

            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
401	Invalid API key
404	Object not found
406	invalid status
500	Internal error

Errors

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");

            String batch_id = "B-1a2B3c4D5e6F7g8H9i0J1k";
            List<Payment> payments = client.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": "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",
            "placeOfBirth": null,
            "ssn": null,
            "tags": [],
            "passport": "",
            "payoutMethod": "bank-transfer",
            "compliance": {
            "status": "verified",
            "checkedAt": "2017-03-20T19:06:23.916Z"
            },
            "accounts": [
            {
               "accountHolderName": "Richard Hendricks",
               "bankId": "123",
               "currency": "CAD",
               "country": "CA",
               "bankName": "TD CANADA TRUST",
               "branchId": "47261",
               "accountNum": "*****47"
            }
            ],
            "address": {
            "street1": "Apt# 14",
            "street2": null,
            "city": "",
            "postalCode": "H3WXXX",
            "phone": "",
            "country": "CA",
            "region": "QC"
            },
            "primaryCurrency": "CAD"
         },
         "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"
         },
         "category": "services",
         "coverFees": false,
         "currency": "CAD",
         "equivalentWithholdingAmount": "0.00",
         "equivalentWithholdingCurrency": "CAD",
         "estimatedDeliveryAt": null,
         "externalId": "",
         "failureMessage": null,
         "initiatedAt": null,
         "isSupplyPayment": false,
         "merchantId": "M-Osg3dh2b0m1cRg9b8Shd2d",
         "methodDisplay": "Bank Transfer",
         "returnedAmount": "0.00",
         "returnedAt": null,
         "returnedNote": null,
         "returnedReason": [],
         "settledAt": null,
         "tags": [],,
         "taxBasisAmount": "0.00",
         "taxBasisCurrency": "CAD",
         "taxReportable": true,
         "withholdingAmount": "0.00",
         "withholdingCurrency": "CAD"
      },
      {
         "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",
            "placeOfBirth": null,
            "ssn": null,
            "tags": [],
            "passport": "",
            "payoutMethod": "bank-transfer",
            "compliance": {
            "status": "verified",
            "checkedAt": "2017-03-20T19:06:23.916Z"
            },
            "accounts": [
            {
               "accountHolderName": "Richard Hendricks",
               "bankId": "123",
               "currency": "CAD",
               "country": "CA",
               "bankName": "TD CANADA TRUST",
               "branchId": "47261",
               "accountNum": "*****47"
            }
            ],
            "address": {
            "street1": "Apt# 14",
            "street2": null,
            "city": "",
            "postalCode": "H3WXXX",
            "phone": "",
            "country": "CA",
            "region": "QC"
            },
            "primaryCurrency": "CAD"
         },
         "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"
         },
         "category": "services",
         "coverFees": false,
         "currency": "CAD",
         "equivalentWithholdingAmount": "0.00",
         "equivalentWithholdingCurrency": "CAD",
         "estimatedDeliveryAt": null,
         "externalId": "",
         "failureMessage": null,
         "initiatedAt": null,
         "isSupplyPayment": false,
         "merchantId": "M-Osg3dh2b0m1cRg9b8Shd2d",
         "methodDisplay": "Bank Transfer",
         "returnedAmount": "0.00",
         "returnedAt": null,
         "returnedNote": null,
         "returnedReason": [],
         "settledAt": null,
         "tags": [],
         "taxBasisAmount": "0.00",
         "taxBasisCurrency": "CAD",
         "taxReportable": true,
         "withholdingAmount": "0.00",
         "withholdingCurrency": "CAD"
      }
   ],
   "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 optional string	Wildcard search across payments
status optional string	Filter by payment statuses. Comma separate list if multiple.

HTTP Code	Description
200	List of payments
401	Invalid API key
404	Object not found
500	Internal error

Errors

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");

            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",
    "tags": [],
    "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",
    "quoteExpiredAt": "2017-03-28T04:08:52.634Z"
  }
}

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

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");
            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": {
    "detail": {
      "bank-transfer": {
        "count": 1,
        "totalFees": "1.00",
        "merchantFees": "1.00",
        "debitAmount": "11.00",
        "sendingAmount": "10.00",
        "totalWithheld": "0.00"
      },
      "paypal": {
        "count": 1,
        "totalFees": "1.00",
        "merchantFees": "1.00",
        "debitAmount": "11.00",
        "sendingAmount": "10.00",
        "totalWithheld": "0.00"
      }
    },
    "total": {
      "count": 1,
      "totalFees": "2.00",
      "merchantFees": "2",
      "debitAmount": "22.00",
      "sendingAmount": "20.00",
      "totalWithheld": "0.00"
    }
  }
}

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
401	Invalid API key
404	Object not found
406	One or more fields failed validation, see errors[] in response body
500	Internal error

Errors

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 'paymentrails'

batch_id = "a123"
client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-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");

            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)

Example response (200 Ok)

{
  "ok": true,
  "batch": {
    "id": "B-1a2B3c4D5e6F7g8H9i0J1k",
    "status": "processing",
    "tags": [],
    "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",
    "quoteExpiredAt": "2017-03-29T04: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
401	Invalid API key
404	Object not found
500	Internal error

Errors

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

Offline Payments

An Offline Payment represents a payment that was made outside of the Payment Rails platform, such as a manual check payment or made with another payouts provider. There are two primary reason you would want to pass this information to us: 1.) to allow those payments to be included in your end of year US tax reporting statements (Forms 1099-MISC, 1099-NEC, 1042-S) and E-filing return, and 2.) to display those payments to your recipients in the Payments History page on the Recipient Widget or Portal, so recipients can see all their payments, even those that weren’t processed with Payment Rails or were processed before your migrated to Payment Rails.

Create an offline payment

const paymentrails = require("paymentrails");

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

async function main() {
  var body = {
    amount: "100.00",
    category: "services",
    currency: "USD",
    externalId: "id-123",
    memo: "A memo",
    processedAt: "2019-08-15T20:23:59.000Z",
    tags: [],
    payoutMethod: "paypal",
    taxReportable: true,
    withholdingAmount: "24.00",
    withholdingCurrency: "USD",
  };
  const recipientId = "R-4321c356vrcerc54js";

  const response = await client.offlinePayment.create(recipientId, body);
  console.log(response.offlinePayment);
}

<?php
use PaymentRails;

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

$recipient_id = "R-4321c356vrcerc54js";

$response = PaymentRails\OfflinePayment::create($recipient_id, [
    'amount' => "100.00",
    'category' => "services",
    'currency' => "USD",
    'externalId' => "id-123",
    'memo' => "A memo",
    'processedAt' => "2019-08-15T20:23:59.000Z",
    'tags' => [],
    'payoutMethod' => "bank-transfer",
    'taxReportable' => true,
    'withholdingAmount' => "24.00",
    'withholdingCurrency' => "USD"
]);
echo $response;


require 'paymentrails'

offline_payment = {
  amount: "100.00",
  category: "services",
  currency: "USD",
  externalId: "id-123",
  memo: "A memo",
  processedAt: "2019-08-15T20:23:59.000Z",
  tags: [],
  payoutMethod: "other",
  taxReportable: true,
  withholdingAmount: "24.00",
  withholdingCurrency: "USD"
}

recipientd_id = "R-4321c356vrcerc54js"

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

client.offline_payment.create(recipientd_id, offline_payment)

To create an offline payment for a recipient send a POST request to the /recipients/:id/offlinePayments endpoint and include the offline payments details in the request body. An auto-generated ID (id) will be generated which can be used to retrieve or update the offline payment details at a later time.

HTTP Request

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

Fields	Description
externalId optional string	The payment identifier used on your external platform.
memo optional string	A short note which may help in identifying or detailing the payment.
taxReportable conditional boolean	Should be `true` if the payment needs to be included in end of year tax reporting of earnings, and `false` if it should not be reportable as earnings for tax purposes.
category conditional string	Income type if the payment is Tax Reportable, either `services`, `royalties`, `royalties_film`, `rent` or `prizes`.
processedAt optional string	The date that the payment was made to the recipient (used to report in the correct tax year, and also to convert amounts in another currency to USD equavalent, based on the mid-market FX rate of this date.
amount required string	The payment amount.
currency optional boolean	The payment’s currency. (If it is not in USD, and it is Tax Reportable, we will convert the amount to USD equivalent based on the mid-market FX rate of the date of the payment).
tags optional string	Tags or keywords which may help identifying the payment.
payoutMethod optional string	The payout method used off platform for this payment, either `bank-transfer`, `paypal`, `interac`, `check`, `bitcoin`, `mobile-money` or `other`.
withholdingAmount required string	The amount withheld from the payment for tax purposes.
withholdingCurrency optional string	The currency associated to the `withholdingAmount`.

Example response (200 Ok)

{
  "ok": true,
  "offlinePayments": {
    "amount": "100.00",
    "category": "services",
    "createdAt": "2019-10-31T20:24:29.954Z",
    "currency": "USD",
    "deletedAt": null,
    "equivalentWithholdingAmount": "24.00",
    "equivalentWithholdingCurrency": "USD",
    "externalId": "id-123",
    "id": "OP-3xghXMEcedrjPEo3KedqsR",
    "memo": "A memo",
    "processedAt": "2019-08-15T20:23:59.000Z",
    "recipientId": "R-4321c356vrcerc54js",
    "tags": [],
    "taxReportable": true,
    "updatedAt": "2019-10-31T20:24:29.954Z",
    "withholdingAmount": "24.00",
    "withholdingCurrency": "USD"
  }
}

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

List all offline 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.offlinePayments.search();
  console.log(response);
}

<?php
use PaymentRails;

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

$offlinePayments = PaymentRails\OfflinePayments::all();
foreach ($offlinePayments as $offlinePayment) {
  print_r($batch);
}


require 'paymentrails'

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

client.offline_payment.search()

Expected response (200 Ok)

{
  "ok": true,
  "offlinePayments": [
    {
      "amount": "100.00",
      "category": "services",
      "createdAt": "2019-10-31T20:24:29.954Z",
      "currency": "USD",
      "deletedAt": null,
      "equivalentWithholdingAmount": "24.00",
      "equivalentWithholdingCurrency": "USD",
      "externalId": "id-123",
      "id": "OP-3xghXMEcedrjPEo3KedqsR",
      "memo": "A memo",
      "processedAt": "2019-08-15T20:23:59.000Z",
      "recipientId": "R-4321c356vrcerc54js",
      "tags": [],
      "taxReportable": true,
      "updatedAt": "2019-10-31T20:24:29.954Z",
      "withholdingAmount": "24.00",
      "withholdingCurrency": "USD"
    },
    {
      "amount": "100.00",
      "category": "services",
      "createdAt": "2019-10-31T20:24:29.954Z",
      "currency": "USD",
      "deletedAt": null,
      "equivalentWithholdingAmount": "24.00",
      "equivalentWithholdingCurrency": "USD",
      "externalId": "id-123",
      "id": "OP-4xghXMEcedrjPEo3KedqsR",
      "memo": "A memo",
      "processedAt": "2019-08-15T20:23:59.000Z",
      "recipientId": "R-4321c356vrcerc54js",
      "tags": [],
      "taxReportable": true,
      "updatedAt": "2019-10-31T20:24:29.954Z",
      "withholdingAmount": "24.00",
      "withholdingCurrency": "USD"
    }
  ]
}

You can retrieve all offline payments by sending a GET request to the /offline-payments endpoint.

HTTP Request

GET https://api.paymentrails.com/v1/offline-payments?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
401	Invalid API key
500	Internal error

Error Code	Description
invalid_api_key	Invalid API key
internal_server_error	Internal server errors

Update an offline payment

const paymentrails = require("paymentrails");

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

async function main() {
  var body = {
    amount: "100.00",
    category: "services",
    currency: "USD",
    externalId: "id-123",
    memo: "A memo",
    processedAt: "2019-08-15T20:23:59.000Z",
    tags: [],
    payoutMethod: "check",
    taxReportable: true,
    withholdingAmount: "24.00",
    withholdingCurrency: "USD",
  };

  const recipientId = "R-4321c356vrcerc54js";
  const offlinePaymentId = "OP-3xghXMEcedrjPEo3KedqsR";

  const response = await client.offlinePayment.update(
    recipientId,
    offlinePaymentId,
    body
  );
  console.log(response.offlinePayment);
}

<?php
use PaymentRails;

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

$recipient_id = "R-4321c356vrcerc54js";
$offline_payment_id = "OP-3xghXMEcedrjPEo3KedqsR"

$response = PaymentRails\OfflinePayment::update($recipient_id, $offline_payment_id, [
    'amount' => "100.00",
    'category' => "services",
    'currency' => "USD",
    'externalId' => "id-123",
    'memo' => "A memo",
    'processedAt' => "2019-08-15T20:23:59.000Z",
    'tags' => [],
    'payoutMethod' => "mobile-money",
    'taxReportable' => true,
    'withholdingAmount' => "24.00",
    'withholdingCurrency' => "USD"
]);
echo $response;


require 'paymentrails'

offline_payment = {
  amount: "100.00",
  category: "services",
  currency: "USD",
  externalId: "id-123",
  memo: "A memo",
  processedAt: "2019-08-15T20:23:59.000Z",
  tags: [],
  payoutMethod: "interac",
  taxReportable: true,
  withholdingAmount: "24.00",
  withholdingCurrency: "USD"
}

offline_payment_id = "OP-3xghXMEcedrjPEo3KedqsR"
recipientd_id = "R-4321c356vrcerc54js"

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

client.offlinePayment.create(recipientd_id, offline_payment_id, offline_payment)

To update an offline payment for a recipient send a PATCH request to the /recipients/:recipientId/offlinePayments/:offlinePaymentId endpoint and include the offline payments details in the request body.

HTTP Request

PATCH https://api.paymentrails.com/v1/recipients/:recipientId/offlinePayments/:offlinePaymentId

Fields	Description
externalId optional string	The payment identifier used on your external platform.
memo optional string	A short note which may help in identifying or detailing the payment.
taxReportable conditional boolean	Should be `true` if the an amount has been withheld from the payment for tax withholding purposes, in other words if `withholdingAmount` is greater than `0.00`.
category conditional string	Either `services`, `royalties`, `royalties_film`, `rent` or `prizes`, to help contextualize the `withholdingAmount` if it is greater than `0.00`.
processedAt optional string	The date that the payment was made to the recipient.
amount required string	The payment amount.
currency optional boolean	The payment’s currency.
tags optional string	Keywords which may help identifying or detailing the payment.
payoutMethod optional string	The payout method used off platform for this payment, either `bank-transfer`, `paypal`, `interac`, `check`, `bitcoin`, `mobile-money` or `other`.
withholdingAmount required string	The amount withheld from the payment for tax purposes.
withholdingCurrency optional string	The currency associated to the `withholdingAmount`.

Example response (200 Ok)

{
  "ok": true,
  "offlinePayments": {
    "amount": "100.00",
    "category": "services",
    "createdAt": "2019-10-31T20:24:29.954Z",
    "currency": "USD",
    "deletedAt": null,
    "equivalentWithholdingAmount": "24.00",
    "equivalentWithholdingCurrency": "USD",
    "externalId": "id-123",
    "id": "OP-3xghXMEcedrjPEo3KedqsR",
    "memo": "A memo",
    "processedAt": "2019-08-15T20:23:59.000Z",
    "recipientId": "R-4321c356vrcerc54js",
    "tags": [],
    "taxReportable": true,
    "updatedAt": "2019-10-31T20:24:29.954Z",
    "withholdingAmount": "24.00",
    "withholdingCurrency": "USD"
  }
}

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

Delete an offline payment

<?php
use PaymentRails;

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

$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';
$offline_payment_id = 'OP-KKHb8MpFvju6vDMBLPmtej';

$response = PaymentRails\OfflinePayment::delete($recipient_id, $offline_payment_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.offlinePayment.remove(
    "R-4625iLug2GKqKZG2WzAf3e",
    "OP-KKHb8MpFvju6vDMBLPmtej"
  );
  console.log(response);
}


require 'paymentrails'

client = PaymentRails.client("YOUR-PUBLIC-KEY", "YOUR-PRIVATE-KEY")

offline_payment_id = "OP-3xghXMEcedrjPEo3KedqsR"
recipientd_id = "R-4321c356vrcerc54js"

client.offline_payment.delete(recipientd_id, offline_payment_id)

Example response (200 Ok)

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

Delete a recipient’s offline payment

HTTP Request

DELETE https://api.paymentrails.com/v1/recipients/:recipientId/offlinePayments/:offlinePaymentId

Fields	Description
recipientId required string	The recipient’s `id`.
offlinePaymentId required string	The offlinePayment’s `id`.

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

Errors

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

Invoices (beta)

The invoices object is designed to handle an accounts payable bill. Invoices are a collection of header information about who the bill is from and when it’s due along with some total information about the individual lines on the bill.

Invoices will have one or more line items with a maximum of 500 lines per invoice. Each line item can have distinct tax treatments but must all be in the same currency.

Payments can be associated with the Invoice / Invoice Line to indicate that payments have been made against this invoice. This will cause the appropriate tax handling to be updated for these payments for accounting purposes. In the event that you’re modifying invoice payments after the payment has been processed the underlying payment will not be updated, since it’s money movement, but the tax handling will be updated.

Create an invoice (beta)

To create an invoice for a recipient send a POST request to the /invoices/create endpoint and include the recipientId for the given recipient. You can also add additional details and the invoice lines when you create the invoice. Note: Invoices are limited to 500 lines.

HTTP Request

POST https://api.paymentrails.com/v1/invoices/create

Fields	Description
recipientId required string	The ID of the recipient
description optional string	A description of the invoice that you would like to add for internal reference.
externalId optional string	The invoice identifier used on your external platform.
invoiceDate optional string	The date the invoice was issued.
dueDate optional string	The date the invoice is due
lines optional lines[]	The invoice lines for this invoice - see Create Invoice Line for details

Example response (200 Ok)

{
  "ok": true,
  "invoice": {}
}

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

Create an invoice line (beta)

To create an invoice line for a given recipient send a POST request to the /invoices/create-lines endpoint and include a list of lines in the request body. You will get back the updated invoice in the response.

HTTP Request

POST https://api.paymentrails.com/v1/invoices/create-lines

Fields	Description
invoiceId required string	The invoice that these lines will be added to.
lines required string	Array of lines
lines[].unitAmount.value required string	The amount of this line item.
lines[].unitAmount.currency required string	The currency code of this line item
lines[].category optional string	The payment category for this line item (see Category List)
lines[].description optional string	Item description
lines[].externalId optional string	Reference for this line in your system
lines[].taxReportable optional boolean	Is this line item subject to EOY tax reporting
lines[].forceUsTaxActivity optional boolean	Is this line item subject to US withholding for EOY tax reporting
lines[].tags optional string[]	Tags that are associated with this line

Get invoice (beta)

You can retrieve an invoice by sending POST /v1/invoices/get

HTTP Request

POST /v1/invoices/get

Query Param	Description
id required string	The invoice to fetch

HTTP Code	Description
200	List of batches
401	Invalid API key
500	Internal error

Error Code	Description
invalid_api_key	Invalid API key
internal_server_error	Internal server errors

Search invoices (beta)

You can retrieve a list of invoices using the search method.

HTTP Request

POST https://api.paymentrails.com/v1/invoices/search

Query Param	Description
invoiceIds optional array	List of IDs to return
recipientId optional array	List of recipientIDs
invoiceNumber optional array	List of invoiceNumbers
invoiceDate optional string	The date the invoice was issued.
externalId optional array	List of external IDs
tags optional array	List of tags
page optional int	The page number (default: 1)
pageSize optional int	Number of records in a page (default: 10)

HTTP Code	Description
200	List of batches
401	Invalid API key
500	Internal error

Error Code	Description
invalid_api_key	Invalid API key
internal_server_error	Internal server errors

Update an invoice (beta)

To update an invoice for a recipient send a POST request to the /invoices/update endpoint and include the invoice details in the request body.

HTTP Request

POST https://api.paymentrails.com/v1/invoices/update

Fields	Description
invoiceId required string	The invoice ID
description optional string	A description of the invoice that you would like to add for internal reference.
externalId optional string	The invoice identifier used on your external platform.
invoiceDate optional string	The date the invoice was issued.
dueDate optional string	The date the invoice is due
tags optional array	List of tags assoicated with this invoice

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

Update invoice lines (beta)

Update invoice line items for a given invoice

HTTP Request

POST https://api.paymentrails.com/v1/invoices/update-lines

Fields	Description
invoiceId required string	The invoice identifier
lines[] required array	Array of line updates
lines[].invoiceLineId required array	Line identifier
lines[].unitAmount.value optional string	The new unit amount (both value and currency must be provide)
lines[].unitAmount.currency optional string	The new unit amount (both value and currency must be provide)
lines[].quantity optional string	Quantity
lines[].description optional string	Line item description
lines[].externalId optional string	External ID in your system
lines[].taxReportable optional boolean	Is US Tax activity reporting
lines[].forceUsTaxActivity optional boolean	Is US Tax activity for US reporting
lines[].tags optional []string	list of string tags
lines[].category optional string	Payment category

Example response (200 Ok)

{
  "ok": true
}

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

Delete an invoice (beta)

Delete a list of invoices

HTTP Request

POST https://api.paymentrails.com/v1/invoices/delete

Fields	Description
invoiceIds required []string	List of invoice IDs

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

Errors

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

Delete an invoice line (beta)

Delete multiple lines from a given invoice

HTTP Request

POST https://api.paymentrails.com/v1/invoices/delete-lines

Fields	Description
invoiceId required string	The invoice ID
invoiceLineIds required []string	List of invoice line IDs

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

Errors

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

Create an invoice payment (beta)

To create an invoice payment for an invoice send a POST request to the /invoices/payment/create endpoint and include the invoice details in the request body.

HTTP Request

POST https://api.paymentrails.com/v1/invoices/payment/create

Fields	Description
batchId optional array	Batch to add the payments to
ids[] required array	A list of payments to make
ids[].invoiceId conditional string	Either the invoiceId or invoiceLineId must be provided
ids[].invoiceLineId conditional string	Either the invoiceId or invoiceLineId must be provided
ids[].amount.value optional string	The value (e.g. “100.00”) to pay. Note if the `value` is provided, `currency` must be provided
ids[].amount.currency optional string	Currency to pay in - must match the invoice currency

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

Update an invoice payment (beta)

HTTP Request

POST https://api.paymentrails.com/v1/invoices/payment/update

Fields	Description
invoiceLineId required string	Invoice Line ID
paymentId required string	Invoice Payment ID
amount.value required string	Amount of the payment
amount.currency required string	Currency of the payment

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

Search invoice payments (beta)

Find all invoice and payment combinations.

HTTP Request

POST https://api.paymentrails.com/v1/invoices/payment/search

Fields	Description
paymentIds optional []string	List of payment identifiers
invoiceIds optional []string	List of invoice identifiers

Example response (200 Ok)

{
  "ok": true,
  "offlinePayments": {
    "amount": "100.00",
    "category": "services",
    "createdAt": "2019-10-31T20:24:29.954Z",
    "currency": "USD",
    "deletedAt": null,
    "equivalentWithholdingAmount": "24.00",
    "equivalentWithholdingCurrency": "USD",
    "externalId": "id-123",
    "id": "OP-3xghXMEcedrjPEo3KedqsR",
    "memo": "A memo",
    "processedAt": "2019-08-15T20:23:59.000Z",
    "recipientId": "R-4321c356vrcerc54js",
    "tags": [],
    "taxReportable": true,
    "updatedAt": "2019-10-31T20:24:29.954Z",
    "withholdingAmount": "24.00",
    "withholdingCurrency": "USD"
  }
}

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

Delete an invoice payment (beta)

Remove the association between a payment and an invoice. Note: if the payment is processed then this will not change the value of the payment.

HTTP Request

POST https://api.paymentrails.com/v1/invoices/payment/delete

Fields	Description
paymentId required string	The payment identifier
invoiceLineIds required []string	List of payment line identifiers

Example response (200 Ok)

{
  "ok": true
}

HTTP Code	Description
200	Offline payment successfully added
401	Invalid API key
404	Object not found
400	Validation error
500	Internal error

Errors

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

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");
            List<Balance> balances = client.balances.all();
            foreach(Balance balance in balances)
            {
                Console.WriteLine("Balance Account #" + balance.accountNumber);
                Console.WriteLine("Balance Amount" + balance.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.89",
      "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
401	Invalid API key
404	Object not found
500	Internal error

Errors

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");
            List<Balance> balances = client.balances.find("all"); // "all" | "paymentrails" | "paypal"
            foreach(Balance balance in balances)
            {
                Console.WriteLine("Balance Account #" + balance.accountNumber);
                Console.WriteLine("Balance Amount" + balance.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.89",
      "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
401	Invalid API key
404	Object not found
500	Internal error

Errors

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");
            List<Balance> balances = client.balances.find("paypal");
            foreach(Balance balance in balances)
            {
                Console.WriteLine("Balance Account #" + balance.accountNumber);
                Console.WriteLine("Balance Amount" + balance.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
401	Invalid API key
404	Object not found
500	Internal error

Errors

Error Code	Description
not_found	Object not found
internal_server_error	Internal server errors

Webhooks

Example Webhook Payload

{
  "model": "recipient",
  "action": "updated",
  "body": {
    "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",
      "placeOfBirth": null,
      "ssn": null,
      "tags": [],
      "passport": "",
      "payoutMethod": "bank-transfer",
      "compliance": {
        "status": "verified",
        "checkedAt": "2017-03-20T19:06:23.916Z"
      },
      "accounts": [
        {
          "accountHolderName": "Richard Hendricks",
          "bankId": "123",
          "currency": "CAD",
          "country": "CA",
          "bankName": "TD CANADA TRUST",
          "branchId": "47261",
          "accountNum": "*****47"
        }
      ],
      "address": {
        "street1": "Apt# 14",
        "street2": null,
        "city": "",
        "postalCode": "H3WXXX",
        "phone": "",
        "country": "CA",
        "region": "QC"
      },
      "primaryCurrency": "CAD"
    }
  }
}

Payment Rails Webhooks

We use webhooks to communicate to your servers events that happen, for example payment is processed or returned. We do this via http POST calls to your services. To make it easy for your service to have both security and robusness we provide three additional headers for you.

X-PaymentRails-Signature – This contains a timestamp and a unique HMAC 256 signature to help verify the sender of the event
X-PaymentRails-Delivery – This is a unique id that allows your service to know if a webhook has already been delivered. If Payment Rails does not receive a 200 response from your service when sending a webhook it will retry with the same ID.
X-PaymentRails-Created – This is when the event was created at payment rails, we attempt to deliver all webhooks in order, it’s not guaranteed due to network issues so this allows you to ignore older events if necessary.

# Sample webhook headers

  X-PaymentRails-Created: 2021-02-15T13:55:15.690Z
  X-PaymentRails-Delivery: 33e72212-ba53-4a22-bce0-3cb09077e87c
  X-PaymentRails-Signature: t=1613397437,v1=29814ed539eedd76ef776fc9d3827591ba9e4ed8eb326525b3e2e8233b6a90d7

Checking signatures

The X-PaymentRails-Signature header contains a string formatted with comma , separated values where the t=NNNN value will contain the current timestamp of when the webhook was sent and the v1 value will contain the signature value.

To check to make sure that the secret is correct, the timestamp is contacted with the raw body of the HTTP request and then the sha256 signature is computed.

Some simple code to verify the values is demonstrated below:

values = dict(x.strip().split('=') for x in header['X-PaymentRails-Signature'].split(','))
digest = hmac.new(shared_key, values['t'], raw_body, hashlib.sha256).hexdigest()

# digest === values['v1']

Webhook uniqueness

Webhooks may be delivered multiple times for the same object. If you need to check the idempotency of a webhook we provide a X-PaymentRails-Delivery delivery header which contains an unique ID that can be used to check for unique delivery.

Note: It is possible to receive more than one webhook callback for action on the server. For instance it’s possible that a single payment update on the UI or API may trigger two payment update events for a receiver of the webhook.

Testing webhooks

Note: you should it is not recomended that you use any proxy service for webhooks, this is outlined for testing purposes.

While most connections in the web world are from you to a server, webhooks are the rare type of connection that server makes towards you! When it comes to Payment Rails, these webhooks are triggered by events like a new payment being created or processed.

Webhooks are configured in the payment rails merchant dashboard settings. Keep in mind that the webhook settings for sandbox and live modes are separate so be sure to configure web hooks in the right mode. When creating a new webhook, you can specify the URL you would like to use as well as which events and models you would like to subscribe to.

When development testing you can receive web hooks using tools such as Webhook inbox. Webhook inbox provides you with a webhook URL that you can use to watch web hook callbacks as they come in. This can be useful when trying to understand how webhook callbacks are formated.

Once you’ve written your code you can get webhook callbacks on your workstation using tools such as Ultrahook. Ultrahook will allow your workstation or laptop to receive web hooks even it’s behind firewalls or NATs. Ultrahook can’t help you if your machine is off, so remember to plug it in and turn it on.

Payment rails webhooks will callback on urls that match the url configured, with a POST and a payload similar to the example on the right. In this case the webhook is to signal that a new payment has been created. The payload contains the “model”, which is the type of object that fired the event. The payload contains the actions, which is the type of action that spawned the event. It also contains a body object which specified the affected model instance(s). Inside the body we will find the model object. The model object is serialized in the same format as the other endpoints so refer to documentation for that model for the full format.

References

List of Countries and Territories

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

Country Name	Country ISO 3166-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
Congo (Kinshasa)	CD
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
Iraq	IQ
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
Lebanon	LB
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
Myanmar (Burma)	MM
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 Barthelemy	BL
Saint Martin (French part)	MF
Saint Pierre and Miquelon	PM
Samoa	WS
San Marino	SM
Sao Tome & Principe	ST
Saudi Arabia	SA
Senegal	SN
Serbia	RS
Seychelles	SC
Sierra Leone	SL
Singapore	SG
Sint Maarten (Dutch part)	SX
Slovakia	SK
Slovenia	SI
Solomon Islands	SB
South Africa	ZA
South Georgia & the South Sandwich Islands	GS
Spain	ES
Sri Lanka	LK
St Helena	SH
St Kitts & Nevis	KN
St Lucia	LC
St Vincent & the Grenadines	VC
Suriname	SR
Svalbard & Jan Mayen	SJ
Swaziland	SZ
Sweden	SE
Switzerland	CH
Taiwan	TW
Tajikistan	TJ
Tanzania	TZ
Thailand	TH
Timor-Leste	TL
Togo	TG
Tokelau	TK
Tonga	TO
Trinidad & Tobago	TT
Tunisia	TN
Turkey	TR
Turkmenistan	TM
Turks & Caicos Island	TC
Tuvalu	TV
Uganda	UG
Ukraine	UA
United Arab Emirates	AE
United Kingdom	GB
United States of America	US
Uruguay	UY
Uzbekistan	UZ
Vanuatu	VU
Vatican City	VA
Vietnam	VN
Virgin Islands (British)	VG
Virgin Islands (US)	VI
Wallis & Futuna	WF
Zambia	ZM
Zimbabwe	ZW

PayPal Supported Countries

The following countries are ONLY supported for PayPal payments.

Country Name	Country ISO 3166-2
Ivory Coast	CI
Cuba	CU
Liberia	LR
Libya	LY
Sudan	SD
Somalia	SO
South Sudan	SS
Syria	SY
Venezuela	VE
Yemen	YE

Sanctioned Countries

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

Country Name	Country ISO 3166-2
Iran	IR
Korea (North)	KP

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 Supported Languages

Payment Rails accepts 2-letter ISO 639-1 language code and optional 2-letter ISO-3166 country code as recipient language preferences. Currently we support the following list of langauges in our outbounding recipient emails and widget portal experience.

Supported ISO 639-1 language codes:

Code	Language
bg	Bulgarian
bn	Bengali
cs	Czech
da	Danish
de	Deutsch
el	Greek
en	English
es	Spanish
fi	Finnish
fr	French
hr	Croatian
hu	Hungarian
id	Indonesian
it	Italian
ja	Japanese
ko	Korean
lt	Lithuanian
lv	Latvian
mk	Macedonian
ms	Malay
nl	Dutch
no	Norwegian
pl	Polish
pt	Portuguese
pt-BR	Brazilian Portuguese
ro	Romanian
ru	Russian
sk	Slovakian
sl	Slovenian
sv	Swedish
th	Thai
tr	Turkish
uk	Ukrainian
vi	Vietnamese
zh	Chinese (Traditional)
zh-CN	Chinese (Simplified)

List of Categories

Category	Details
`services`	Services
`rent`	Rent
`royalties`	Royalties
`royalties_film`	Royalties Film & TV
`prizes`	Prize payment
`education`	Education
`refunds`	Refunds

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 payment ‘Returned’, their payout method might be temporarily disabled until the payout method is updated by either the merchant or recipient. We recommend subscribing to the recipient update webhooks to keep track of this occuring.
`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. You cannot Delete (DELETE) or update (PATCH) a batch once it is in Processing status.
`complete`	Once all payments in a batch have been processed, failed or returned, 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

Local Bank Transfers

Country	Currency	Received by Recipient	Daily cut off
United States	USD	Next business day	3:00pm EST
Canada	CAD, USD	Same or next business day	4:00pm EST
United Kingdom	GBP, EUR	Same or next business day	2:00pm EST
Argentina *	ARS	1-2 business days	2:00pm EST
Australia	AUD	1-2 business days	2:00pm EST
Austria	EUR	Next business day	2:00pm EST
Belgium	EUR	Next business day	2:00pm EST
Brazil	BRL	1-2 business days	2:00pm EST
Bulgaria	BGN, EUR	1-2, Next business day	2:00pm EST
Chile *	CLP	1-2 business days	2:00pm EST
China *	CNY, USD	1-2, 3-5 business days	2:00pm EST
Colombia *	COP	1-2 business days	2:00pm EST
Croatia	HRK, EUR	1-2, Next business day	2:00pm EST
Cyprus	EUR	Next business day	2:00pm EST
Czech Republic	CZK, EUR	1-2, Next business day	2:00pm EST
Denmark	DKK, EUR	1-2, Next business day	2:00pm EST
Estonia	EUR	Next business day	2:00pm EST
Finland	EUR	Next business day	2:00pm EST
France	EUR	Next business day	2:00pm EST
French Guiana	EUR	Next business day	2:00pm EST
Germany	EUR	Next business day	2:00pm EST
Gibraltar	EUR, GIP	Next, 3-5 business days	2:00pm EST
Greece	EUR	Next business day	2:00pm EST
Guadeloupe	EUR	Next business days	2:00pm EST
Guernsey	EUR, GBP	Next, 2-3 business days	2:00pm EST
Hong Kong	HKD	1-2 business days	2:00pm EST
Hungary	HUF, EUR	1-2, Next business days	2:00pm EST
Iceland	EUR, ISK	1-2, 3-5 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
Isle of Man	EUR, GBP	1-2, 3-5 business days	2:00pm EST
Italy	EUR	Next business day	2:00pm EST
Jersey	EUR, GBP	Next, 3-5 business days	2:00pm EST
Kenya *	KES	1-2 business days	2:00pm EST
Latvia	EUR	Next business day	2:00pm EST
Liechtenstein	EUR, CHF	Next, 3-5 business days	2:00pm EST
Lithuania	EUR	Next business day	2:00pm EST
Luxembourg	EUR	Next business day	2:00pm EST
Malaysia	MYR	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
Mexico *	MXN	1-2 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
Norway	NOK, EUR	1-2, Next business day	2:00pm EST
Paraguay *	PYG	1-2 business days	2:00pm EST
Peru *	PEN	1-2 business days	2:00pm EST
Philippines	PHP	1-2 business days	2:00pm EST
Poland	PLN, EUR	1-2, Next business day	2:00pm EST
Portugal	EUR	Next business day	2:00pm EST
Reunion	EUR	Next business days	2:00pm EST
Romania	RON, EUR	1-2, Next business day	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
St Barthelemy	EUR	Next business days	2:00pm EST
St Pierre & Miquelon	EUR	Next business day	2:00pm EST
Sweden	SEK, EUR	1-2, Next business day	2:00pm EST
Switzerland	CHF, EUR	1-2, Next business days	2:00pm EST
Thailand	THB	1-2 business days	2:00pm EST
Uruguay *	UYU	1-2 business days	2:00pm EST
Vatican City	EUR	Next business day	2:00pm EST
Vietnam	VND	1-2 business days	2:00pm EST

SWIFT Bank Wires

Country	Currency	Received by Recipient	Daily cut off
Albania	ALB	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
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
Barbados	BBD	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
Bosnia & Herzegovina	BAM	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
Christmas Island	AUD	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
Egypt *	EGP	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
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
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
Israel	ILS	3-5 business days	2:00pm EST
Jamaica	JMD	3-5 business days	2:00pm EST
Japan	JPY	2-3 business days	2:00pm EST
Jordan	JOD	3-5 business days	2:00pm EST
Kazakhstan	KZT	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
Kosovo	EUR	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
Macau	MOP	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
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
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
New Zealand *	NZD	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
Pakistan *	PKR	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
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
Russia	RUB	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
Sri Lanka *	LKR	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
Trinidad & Tobago	TTD	3-5 business days	2:00pm EST
Tunisia	TND	3-5 business days	2:00pm EST
Turkey	TRY	3-4 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, USD	3-5, 3-5 business days	2:00pm EST
United Arab Emirates	AED	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
Virgin Islands (British)	USD	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	RUN (Rol Único Nacional)	8 or 9
Chile	Business	RUT (Rol Único Tributario)	8 or 9
China	Individual	NIDN (National ID Number)	15 or 18
China	Business	BRN (Business Registration Number)	18
Colombia	Individual	NIT (Número de Identificación Tributaria)	10
Costa Rica	Individual	Cedula Juridica	9 to 12
Dominican Republic	Individual	Cédula de Residencia	11
Dominican Republic	Business	RNC (Dominican Republic tax number)	9
Dominican Republic	Business	NCF (\Dominican Republic receipt number)	11 or 13 or 19
Guatemala	Individual	CUI (Código Único de Identificación)	13
Guatemala	Business	NIT (Número de Identificación Tributaria)	8 to 12
Kazakhstan	Individual	IIN (Individual identification number)	12
Korea	Individual	RRN (South Korean resident registration number)	13
Korea	Business	BRN (South Korea Business Registration Number)	10
Mexico	Individual	CURP (Mexican personal ID)	18
Mexico	Individual	RFC (Mexican tax number)	13
Mexico	Business	RFC (Mexican tax number)	12
Nepal	Individual	PAN (Permanent account number)	9
Nepal	Business	PAN (Permanent account number)	9
Pakistan	Individual	CNIC (Pakastan Computerize National Identiy Card)	11
Pakistan	Business	NTT (Pakastan Tax Identification Number)	11
Paraguay	Individual	RUC number (Paraguay tax number)	8 or 9
Paraguay	Business	RUC number (Paraguay tax number).	8 or 9
Peru	Individual	CUI (Peruvian identity number)	8
Peru	Individual	CE (Peruvian ID card for foreigners)	9
Peru	Business	RUC (Peruvian company tax number)	11
Russia	Individual	ИНН (Russian tax identifier)	12
Russia	Business	ИНН (Russian tax identifier)	10
Tajikistan	Individual	National ID	9
Tajikistan	Business	National ID	9
Uruguay	Individual	Cedula (Urugual Person number)	9
Uruguay	Individual	NIE (Uruguay Foreigners Identification Number)	9
Uruguay	Business	RUT (Uruguay tax number)	9

Additional Requirements

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

Country	Phone Number	First Name	Last Name	Date of Birth	Postal Code	Region Code
Argentina	✔
Bangladesh	✔
Brazil	✔	✔	✔		✔
Canada					✔	✔
Chile	✔
China		✔	✔			✔
Columbia	✔
Dominican Republic	✔
Egypt	✔	✔	✔
Ethopia	✔
Fiji	✔
Guatemala	✔
India				✔
Israel					✔
Jordan	✔
Khazakhstan	✔
Mongolia	✔
Russia	✔
South Africa	✔	✔	✔
Taiwan	✔
Thailan	✔
Togo	✔
Tonga	✔
Tuvalu	✔
United States					✔

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	https://github.com/PaymentRails/ruby-sdk
Java	https://github.com/PaymentRails/java-sdk

Table of Contents

Introduction

Before you start

Interacting with the API

Making requests

Success Codes

Error Codes

CORS

Fields

Rate limiting

Deprecation Policy

Authentication

Signing requests

Making a request

Example of creating a signature

Additional Security for API Keys

Recipients

Recipient Attributes

Address

Payout Method

Create a recipient

HTTP Request

HTTP Response codes

Errors

Errors Example

Retrieve a recipient

HTTP Request

Errors

Errors Example

Update a recipient

HTTP Request

HTTP Response codes

Errors

Errors Example

Delete a recipient

HTTP Request

Errors

Errors Example

Delete multiple recipients

HTTP Request

Errors

Errors Example

List all recipients

HTTP Request

Errors

Retrieve all logs

HTTP Request

Errors

Errors Example

Retrieve all payments

HTTP Request

Errors

Errors Example

Retrieve recipient’s offline payments

HTTP Request

Errors

Errors Example

Recipient Account

Multiple Account Available

Account Attributes

Mailing

Create Account

HTTP Request

Errors

Delete Account

HTTP Request

Errors

Retrieve Account

HTTP Request

Errors

Update Account

HTTP Request

Errors

Payments

Step 1: Create a batch

Step 2: Generate Quote of FX rates

Step 3: Check account balance

Step 4: Process the batch

Step 5: Summary of the batch

Create a batch