Introduction
API Endpoint
https://api.paymentrails.com/v1/
Trolley’ 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.
Trolley 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 Trolley account from your company bank account, to fund your balance before sending payments. |
Interacting with the API
Making requests
The Trolley API follows RESTful design principles. We use the following HTTP verbs:
GET
- Read resourcesPOST
- Create new resourcesPATCH
- Update an existing resourceDELETE
- Remove resources
When making requests, arguments can be passed as params or JSON with correct Content-Type
header of application/json
.
Success Codes
The Trolley 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 Trolley 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
Trolley 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 Trolley 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 Trolley 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 transmittedX-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 theX-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 Trolley 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"
},
"routeType": "ach",
"routeMinimum": "1",
"estimatedFees": "1.25",
"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"
},
"routeType": "ach",
"routeMinimum": "1",
"estimatedFees": "1.25",
"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"
},
"routeType": "ach",
"routeMinimum": "1",
"estimatedFees": "1.25",
"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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Errors Example
If recipient doesn’t exist, the API will respond with an error. For example:
Response (404 Not Found)
{
"ok": false,
"errors": [
{
"code": "not_found",
"message": "Object not found"
}
]
}
Update a recipient
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
var body = { firstName: "John" };
const response = await client.recipient.update(
"R-1a2B3c4D5e6F7g8H9i0J1k",
body
);
console.log(response);
}
require '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"
},
"routeType": "ach",
"routeMinimum": "1",
"estimatedFees": "1.25",
"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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Errors Example
If recipient does not exist, the API will respond with an error. For example:
Response (404 Not Found)
{
"ok": false,
"errors": [
{
"code": "not_found",
"message": "Object not found"
}
]
}
Delete multiple recipients
curl \
-H "Content-Type: application/json" \
-H "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
-H "X-PR-Timestamp: <timestamp>" \
-X DELETE \
-d '{"ids": ["R-1a2B3c4D5e6F7g8H9i0J1k", "R-1a2B3c4D5e6F7g8H9i0J1k"]}' \
https://api.paymentrails.com/v1/recipients
Response (200 Ok)
{
"ok": true,
"object": "deleted"
}
You can delete multiple recipients by sending a DELETE request to the /recipients
endpoint.
HTTP Request
DELETE https://api.paymentrails.com/v1/recipients/
Fields | Description |
---|---|
ids required array of strings |
Recipient IDs to delete |
HTTP Code | Description |
---|---|
200 | All recipients successfully deleted |
401 | Invalid API key |
404 | Recipient not found |
500 | Internal error |
Errors
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Errors Example
If any of the recipients do not exist, the API will respond with an error.
Response (404 Not Found)
{
"ok": false,
"errors": [
{
"code": "not_found",
"message": "Object not found"
}
]
}
List all recipients
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.recipient.search(1, 10, "term");
console.log(response);
}
require '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"
},
"routeType": "ach",
"routeMinimum": "1",
"estimatedFees": "1.25",
"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"
},
"routeType": "ach",
"routeMinimum": "1",
"estimatedFees": "1.25",
"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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Retrieve all logs
curl \
-H "Content-Type: application/json" \
-H "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
-H "X-PR-Timestamp: <timestamp>" \
-X GET \
https://api.paymentrails.com/v1/recipients/:id/logs
Response (200 Ok)
{
"ok": true,
"activities": [
{
"ip": "::ffff:10.0.2.2",
"url": "/v1/recipients/R-91XNW81D85DMG/log",
"method": "GET",
"headers": {
"host": "api.local.dev:3000",
"connection": "keep-alive",
"postman-token": "47cad157-855e-49fe-45d6-d61a02ffa802",
"cache-control": "no-cache",
"user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
"x-api-key": "pk_live_*********************************",
"content-type": "application/json",
"accept": "*/*",
"accept-encoding": "gzip, deflate, sdch",
"accept-language": "en-US,en;q=0.8"
},
"request": "",
"response": "{\"ok\":false,\"errors\":[{\"code\":\"not_found\",\"message\":\"Object not found\"}]}",
"code": 404,
"source": "api",
"testMode": false,
"createdAt": "2017-03-22T17:57:32.786Z"
}
],
"meta": {
"page": 1,
"pages": 1,
"records": 2
}
}
You can retrieve a list of all activity related to a recipient by sending a GET request to the /recipients/:id/logs
endpoint.
HTTP Request
GET https://api.paymentrails.com/v1/recipients/:id/logs
Fields | Description |
---|---|
id required string |
Recipient ID |
HTTP Code | Description |
---|---|
200 | All recipients |
401 | Invalid API key |
404 | Recipient not found |
500 | Internal error |
Errors
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Errors Example
If the recipient does not exist, the API will respond with an error. For example:
Response (404 Not Found)
{
"ok": false,
"errors": [
{
"code": "not_found",
"message": "Object not found"
}
]
}
Retrieve all payments
curl \
-H "Content-Type: application/json" \
-H "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
-H "X-PR-Timestamp: <timestamp>" \
-X GET \
https://api.paymentrails.com/v1/recipients/:id/payments
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Errors Example
If recipient doesn’t exist, the API will respond with an error. For example:
Response (404 Not Found)
{
"ok": false,
"errors": [
{
"code": "not_found",
"message": "Object not found"
}
]
}
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Errors Example
If recipient doesn’t exist, the API will respond with an error. For example:
Response (404 Not Found)
{
"ok": false,
"errors": [
{
"code": "not_found",
"message": "Object not found"
}
]
}
Recipient Account
Our philosophy is to give more choice of payout methods to users. What works for someone in San Francisco, London or Melbourne, might not be the best option for someone else in Jakarta, Nairobi or Mumbai. PayPal doesn’t support all countries, in fact, 97.5% of the worldwide population don’t have a PayPal account, and over 2 billion people don’t have a bank account. So clearly multiple payment options are needed to support a global business. That is why we plan to support every major payout method, so your users have choice of what works best for them.
Multiple Account Available
By POST-ing an account method for a recipient, you are adding a new payment method (such as their bank account, their PayPal account, mobile money account, prepaid card, etc) to the recipient.
A recipient can have multiple accounts with different payout methods assigned, however only one (1) account can be their selected (“primary”) account at any time.
Account Attributes
Below is a list of currently active (live) payout type, and those that are on our future roadmap.
Payout Method Type | Status | Description Method |
---|---|---|
bank-transfer |
live | Bank Transfers (includes local bank transfers to 60+ major countries, and bank wires to all other countries) |
paypal |
live | PayPal account |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
empty_field | A field is required |
invalid_field | A field failed a validation check |
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
<?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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Retrieve Account
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';
$account_id = 'A-KKHb8MpFvju6vDMBLPmtej';
$response = PaymentRails\RecipientAccount::find($recipient_id, $account_id);
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.recipientAccount.find(
"R-4625iLug2GKqKZG2WzAf3e",
"A-a1b2c3d4e5f5g6h7i8j9k0"
);
console.log(response);
}
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Update Account
Update existing PayPal address
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$recipient_id = 'R-PuzPJLVYQXBbPSMQKwmJ5G';
$account_id = 'A-KKHb8MpFvju6vDMBLPmtej';
$response = PaymentRails\RecipientAccount::update($recipient_id, $account_id, [
"primary" => false,
]);
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
var body = { primary: "false" };
const response = await client.recipientAccount.update(
"R-4625iLug2GKqKZG2WzAf3e",
"A-a1b2c3d4e5f5g6h7i8j9k0",
body
);
console.log(response);
}
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
empty_field | A field is required |
invalid_field | A field failed a validation check |
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Payments
The payment object describes a payment. Payments are sent to a recipient via the recipient’s chosen payout method, such as: bank account, PayPal, mobile money, or credit/debit card. If no payment method is setup, the payment will not be processed.
A Batch is a group of Payments. Payments are added to a batch prior to being processed. If your business does regularly scheduled payouts, such as once per day, once per week, every 2 weeks, or even monthly, then using batches will be great for you.
A batch can be made up of just 1 payment, or 100 payments, or hundreds of thousands of payments (there are no upper limits).
Batches also allow you to manually review and approve your payments before processing, if you prefer. This is handy if you conduct some additional fraud reviews on your payouts before processing, or if your company CFO or a senior manager is responsible for approving payouts before they go out.
There are 4 main steps for handling a batch:
Step 1: Create a batch
Firstly, when you Create a batch, the system
will automatically open a new batch and assign a unique batchId
which is generated by our system. The format of all Batch IDs are
“B-1a2B3c4D5e6F7g8H9i0J1k”, with the ‘B-’ prefix indicating Batch, followed
by 22 alphanumeric digits.
When you create a batch, you will also send us the details for your
payments. This includes at a minimum the recipientId
, amount
and
currency
for all the payments for that batch.
Note: You can also use our online Dashboard portal to manually create a batch of payments by uploading a file of payments in .csv file format, or manually adding payments into a batch.
Payment Minimums
While adding payments to a batch, keep in mind there are limits to the minimum amount within a payment you can send through a bank transfer.
If you add payment amounts to a batch which are below the minimum amount allowed, the batch will not be processed.
To avoid this, you should query /recipients/:recipientId
API to find out the payment minimum for a recipient, before adding the payments to the batch.
For more information on how to work with Payment Minimums, and a suggested flow of this operation, have a look at this article: How to get ready for using Bank Transfer Minimums
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 |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
empty_field | A field is required |
invalid_field | A field failed a validation check |
invalid_status | Invalid Status |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Retrieve a batch
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.batch.find("B-1a2b3c4d5e6f7g8h9i0jk1");
console.log(response.batch.id);
}
require '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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Delete a batch
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.batch.remove("B-1a2b3c4d5e6f7g8h9i0jk1");
console.log(response);
}
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$response = PaymentRails\Batch::delete($batch_id);
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_status | Invalid Status |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Delete multiple batches
Expected Response (204 No Content)
You can delete multiple batches by sending a DELETE request to the /batches
endpoint 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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_status | Invalid Status |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
List all batches
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.batch.search(1, 10, "John");
console.log(response);
}
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$batches = PaymentRails\Batch::all($batch_id, $payment_id);
foreach ($batches as $batch) {
print_r($batch);
}
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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 |
Amount you wish to send, e.g. 100.00 USD, in your own currency. Required only if sending a “sourceAmount”. |
sourceCurrency conditional string |
Currency of the amount you wish to send, e.g. 100.00 USD. Required only if sending a “sourceAmount”. |
targetAmount conditional string |
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 |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Retrieve a payment
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.payment.find("P-1a2B3c4D5e6F7g8H9i0J1k");
console.log(response.payment.id);
}
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$payment_id = 'P-1a2B3c4D5e6F7g8H9i0J1k';
$response = PaymentRails\Batch::findPayment($batch_id, $payment_id);
echo $response;
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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"
},
"routeType": "ach",
"routeMinimum": "1",
"estimatedFees": "1.25",
"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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Update a payment
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
var body = { sourceAmount: "900.90" };
const response = await client.payment.update(
'P-1a2B3c4D5e6F7g8H9i0J1k","B-1a2B3c4D5e6F7g8H9i0J1k',
body
);
console.log(response);
}
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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 |
Amount you wish to send, e.g. 100.00 USD, in your own currency. Required only if sending a “sourceAmount”. |
sourceCurrency conditional string |
Currency of the amount you wish to send, e.g. 100.00 USD. Required only if sending a “sourceAmount”. |
targetAmount conditional string |
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 |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_status | Invalid Status |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Delete a payment
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
var body = {
recipient: {
id: "R-1a2B3c4D5e6F7g8H9i0J1k",
},
sourceAmount: "100.10",
sourceCurrency: "CAD",
memo: "Freelance payment",
};
const response = await client.payment.remove(
"B-1a2B3c4D5e6F7g8H9i0J1k",
"P-1a2B3c4D5e6F7g8H9i0J1k"
);
console.log(response);
}
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$payment_id = 'P-1a2B3c4D5e6F7g8H9i0J1k';
$response = PaymentRails\Batch::deletePayment($batch_id, $payment_id);
echo $response;
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_status | Invalid Status |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
List all payments
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.payment.search(1, 10, "John");
console.log(response);
}
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$payments = PaymentRails\Batch::payments($batch_id);
foreach ($payments as $payment) {
print_r($payment);
}
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Generate quote
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.batch.generateQuote("B-1a2b3c4d5e6f7g8h9i0jk1");
console.log(response);
}
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$payment_id = 'P-1a2B3c4D5e6F7g8H9i0J1k';
$response = PaymentRails\Batch::generateQuote($batch_id);
echo $response;
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object not found |
expired_quote | Quote is expired |
invalid_status | Invalid Status |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Batch summary
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.batch.summary("B-1a2b3c4d5e6f7g8h9i0jk1");
console.log(response);
}
<?php
use PaymentRails;
PaymentRails\Configuration::publicKey('YOUR_PUBLIC_KEY');
PaymentRails\Configuration::privateKey('YOUR_PRIVATE_KEY');
$batch_id = 'B-1a2B3c4D5e6F7g8H9i0J1k';
$response = PaymentRails\Batch::summary($batch_id);
echo $response;
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object not found |
expired_quote | Quote is expired |
invalid_status | Invalid Status |
Process a batch
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.batch.startProcessing(
"B-1a2b3c4d5e6f7g8h9i0jk1"
);
console.log(response);
}
require '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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object not found |
invalid_status | Invalid Status |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
non_sufficient_funds | Insufficient funds |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Delete 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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Update 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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Delete 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 | Invoices successfully deleted (invoice IDs that are not found will be ignored) |
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 |
---|---|
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 | Invoice lines successfully deleted (Invoice line IDs that are not found by the given invoice will be ignored) |
401 | Invalid API key |
404 | Invoice not found |
500 | Internal error |
Errors
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
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 invoiceId or invoiceLineIds to make payment against |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Update 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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
Delete 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 | Invoice payment(s) successfully deleted (Invoice line IDs that are not found by the given payment will be ignored) |
401 | Invalid API key |
404 | Payment/Invoice not found |
400 | Validation error |
500 | Internal error |
Errors
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object doesn’t exist |
invalid_api_key | Invalid API key |
internal_server_error | Internal server errors |
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object not found |
internal_server_error | Internal server errors |
Retrieve Payment Rails account balance
curl \
-H "Content-Type: application/json" \
-H "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
-H "X-PR-Timestamp: <timestamp>" \
-X GET \
https://api.paymentrails.com/v1/balances/paymentrails
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.balances.find("paymentrails");
console.log(response);
}
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object not found |
internal_server_error | Internal server errors |
Retrieve PayPal account balance
curl \
-H "Content-Type: application/json" \
-H "Authorization: prsign <ACCESS-KEY>:<SIGNATURE>" \
-H "X-PR-Timestamp: <timestamp>" \
-X GET \
https://api.paymentrails.com/v1/balances/paypal
const paymentrails = require("paymentrails");
const client = paymentrails.connect({
key: "YOUR-API-KEY",
secret: "YOUR-API-SECRET",
environment: "production",
});
async function main() {
const response = await client.balances.find("paypal");
console.log(response);
}
using PaymentRails.Types;
using PaymentRails;
class Program
{
static void Main(string[] args)
{
var client = new PaymentRails.Gateway("YOUR-API-KEY", "YOUR-SECRET-KEY");
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
This table lists the expected errors that this method could return.
However, other errors can be returned in the case where the service
is down or other unexpected factors affect processing. Callers
should always check the value of the ok
params in the response.
Error Code | Description |
---|---|
not_found | Object not found |
internal_server_error | Internal server errors |
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"
}
}
}
Trolley 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 eventX-PaymentRails-Delivery
– This is a unique id that allows your service to know if a webhook has already been delivered. If Trolley 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 Trolley, 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 concatenated 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 Trolley, these webhooks are triggered by events like a new payment being created or processed.
Webhooks are configured in the Trolley 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.
Trolley 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
Trolley 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 |