Introduction
This api allows you to deposit money in the bank account of a customer. The deposit will always be in local currency. Once the wire is confirmed by the bank, Paygol will send a notification to your merchant notification url informing you of the wire result code. The notification URL is defined by default by the merchant. These parameter can be over-ridden at any time using the notification parameter (however, this new url is only active for that particular cashout, following which we will revert to the default URL previously provided).
https://payouts.paygol.com/api/v1
Signature of message
All requests to the payment API must be signed using the merchant’s secret key with the HMAC SHA256 algorithm. The signature must be calculated using the payload of the request, sorted in ascending order and adding this result in a request header with the name X-PG-SIG.
<?php
/**
* Merchant shared secret
*
* @var string
*/
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";
$payload = [...];
ksort($payload, SORT_NATURAL | SORT_FLAG_CASE);
$signature = hash_hmac('sha256', json_encode($payload), $shared_secret);
Request an authentication access token
POST /auth/token
<?php
/**
* Merchant service ID
*
* @var int
*/
$service_id = "123";
/**
* Merchant shared secret
*
* @var string
*/
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";
$payload = json_encode(['pg_serviceid' => $service_id]);
$signature = hash_hmac("sha256", $payload, $shared_secret);
// API URL
$url = 'https://payouts.paygol.com/api/v1/auth/token';
$opts = [
'http' => [
'method' => 'POST',
'header' => [
'Content-type: application/json',
'X-PG-SIG: ' . $signature,
],
'content' => $payload,
],
];
$context = @stream_context_create($opts);
$json_response = @file_get_contents($url, false, $context);
$result = json_decode($json_response, true);
$token = $result['token'];
Request Payouts
Parameters description
Field |
Type |
Description |
Requirement |
pg_serviceid |
String |
Merchant service ID |
required |
pg_token |
String |
A valid authentication access token |
required |
payouts |
Array |
Array of Payout objects (max. 1500) |
required |
payout |
Payout object |
Payout object |
required |
beneficiary |
Beneficiary object |
Beneficiary object |
required |
account |
Account object |
Account object |
required |
Payout object
Field |
Type |
Description |
Requirement |
id |
String (Max. 64 chars) |
Unique merchant payout ID |
required |
country |
String (2 chars) |
The user’s country. ISO 3166-1 alpha-2 code |
required |
amount |
Decimal (max. 2 decimal numbers) |
Payout amount (in the currency entered in the field “currency”) |
required |
currency |
String (3 chars) |
ISO 4217 curency code |
required |
beneficiary |
Beneficiary object |
Beneficiary object |
required |
account |
Account object |
Account object |
required |
details |
String (max. 255 chars) |
Optional information |
optional |
Beneficiary object
Field |
Type |
Description |
Requirement |
type |
String |
person | company |
required |
full_name |
String (Max. 128 chars) |
Person or Company name |
required |
first_name |
String (Max. 32 chars) |
Beneficiary first name |
required for beneficiary type person |
last_name |
String (Max. 32 chars) |
Beneficiary last name |
required for beneficiary type person |
surname |
String (Max. 32 chars) |
Beneficiary surnaame |
optional |
document_type |
String |
Beneficiary’s personal identification type. See document validation information |
required |
document_number |
String (Max. 32 chars) |
Beneficiary’s personal identification number |
required |
document_dv |
String (Max. 2 chars) |
Verification digit |
required |
email |
String (Max. 128 chars) |
Email of the beneficiary |
optional |
Account object
Field |
Type |
Description |
Requirement |
bank_code |
String (5 chars) |
Beneficiary’s bank code. See bank codes |
required |
bank_name |
String (max. 32 chars) |
Beneficiary’s bank name. See bank names |
optional |
number |
String (max. 64 chars) |
Beneficiary’s bank account number |
required |
type |
String (5 chars) |
The type of account. See account types |
required |
POST /payouts
<?php
/**
* Merchant service ID
*
* @var int
*/
$service_id = "123";
/**
* Merchant shared secret
*
* @var string
*/
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";
// Get an authentication access token
$token = '302ec9c75bf9390db75959e2eded9ae3f5cdb7c1';
// Unique merchant payout ID
$uniqueid = $service_id . '-' . rand(10000, 99999);
$payload = [
'pg_mode' => 'strict',
'pg_serviceid' => $service_id,
'pg_token' => $token,
'payouts' => [
[
'id' => $uniqueid,
'country' => 'CL',
'amount' => 1000000.00,
'currency' => 'CLP',
'beneficiary' => [
'type' => 'person',
'full_name' => 'Robert Pani Hernandez',
'first_name' => 'Robert',
'last_name' => 'Pani',
'surname' => 'Hernandez',
'document_type' => 'cl_rut',
'document_number' => '14555555',
'document_dv' => '4',
'email' => '[email protected]',
],
'account' => [
'bank_code' => '001',
'number' => '002555-343456',
'type' => 'FP001',
],
'details' => 'Debt payment',
],
...
],
];
// sort payload
ksort($payload, SORT_NATURAL | SORT_FLAG_CASE);
$payload = json_encode($payload);
$signature = hash_hmac("sha256", $payload, $shared_secret);
// API URL
$url = 'https://payouts.paygol.com/api/v1/payouts';
$opts = [
'http' => [
'method' => 'POST',
'header' => [
'Content-type: application/json',
'X-PG-SIG: ' . $signature,
],
'content' => $payload,
],
];
$context = @stream_context_create($opts);
$json_response = @file_get_contents($url, false, $context);
Response
{
"data": {
"mode": "strict",
"inserted_rows": 1,
"error_rows": 0,
"mode": "strict",
"payouts": [{
"payout_id": "pay_5d711e7f6b9598-37174324",
"country": "CL",
"amount": 1000000.00,
"currency": "CLP",
"external_id": "merchant-id-5d711e7ec9525666850",
"full_name": "Robert Pani Hernandez",
"first_name": "Robert",
"last_name": "Pani",
"surname": "Hernandez",
"document_type": "cl_rut",
"document_number": "14555555",
"document_dv": "4",
"email": "[email protected]",
"bank_code": "001",
"account_type": "FP001",
"account_number": "002555-343456",
"details": "Pago remuneracion USD",
"status": "created"
}]
},
"result": 0
}
Check status
Check the status of a payout
Field |
Type |
Description |
Requirement |
pg_serviceid |
String |
Merchant service ID |
required |
pg_token |
String |
A valid authentication access token |
required |
external_id |
String (max. 64 chars) |
Payout ID (at the merchant site) |
required |
POST /payouts/status
<?php
/**
* Merchant service ID
*
* @var int
*/
$service_id = "123";
/**
* Merchant shared secret
*
* @var string
*/
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";
// Get an authentication access token
$token = '302ec9c75bf9390db75959e2eded9ae3f5cdb7c1';
$payload = [
'pg_serviceid' => $service_id,
'pg_token' => $token,
'external_id' => 'merchant-id-859649'
];
// sort payload
ksort($payload, SORT_NATURAL | SORT_FLAG_CASE);
$payload = json_encode($payload);
$signature = hash_hmac("sha256", $payload, $shared_secret);
// API URL
$url = 'https://payouts.paygol.com/api/v1/payouts/status';
$opts = [
'http' => [
'method' => 'POST',
'header' => [
'Content-type: application/json',
'X-PG-SIG: ' . $signature,
],
'content' => $payload,
],
];
$context = @stream_context_create($opts);
$json_response = @file_get_contents($url, false, $context);
Response
{
"data": {
"country": "CL",
"amount": 1000000,
"currency": "CLP",
"merchant_payout_id": "merchant-id-859649",
"pay_at": null,
"full_name": "Robert Pani Hernandez",
"first_name": "Robert",
"last_name": "Pani",
"surname": "Hernandez",
"document_type": "cl_rut",
"document_number": "14555555",
"document_dv": "4",
"email": "[email protected]",
"bank_code": "001",
"account_number": "002555-343456",
"account_type": "FP001",
"details": "Debt payment",
"status": "created",
"events": []
},
"result": 0
}
Get payouts
Get a list of payouts
Field |
Type |
Description |
Requirement |
pg_serviceid |
String |
Merchant service ID |
required |
pg_token |
String |
A valid authentication access token |
required |
status |
String |
A valid Paygol payout status. See status table |
optional |
limit |
Integer > 0 |
Maximum number of results (default 50) |
optional |
page |
Integer > 0 |
Page number(default 1) |
optional |
POST /payouts/list
<?php
/**
* Merchant service ID
*
* @var int
*/
$service_id = "123";
/**
* Merchant shared secret
*
* @var string
*/
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";
// Get an authentication access token
$token = '302ec9c75bf9390db75959e2eded9ae3f5cdb7c1';
$payload = [
'pg_serviceid' => $service_id,
'pg_token' => $token,
'status' => 'created',
'limit' => 5,
'page' => 2
];
// sort payload
ksort($payload, SORT_NATURAL | SORT_FLAG_CASE);
$payload = json_encode($payload);
$signature = hash_hmac("sha256", $payload, $shared_secret);
// API URL
$url = 'https://payouts.paygol.com/api/v1/payouts/list';
$opts = [
'http' => [
'method' => 'POST',
'header' => [
'Content-type: application/json',
'X-PG-SIG: ' . $signature,
],
'content' => $payload,
],
];
$context = @stream_context_create($opts);
$json_response = @file_get_contents($url, false, $context);
Response
{
"data": {
"items": [
{
"country": "CL",
"amount": 58509,
"currency": "CLP",
"merchant_payout_id": "77722",
"pay_at": null,
"full_name": "Roberto Pani 5o",
"first_name": "Roberto",
"last_name": "Pani",
"surname": null,
"document_type": 1,
"document_number": "23708467",
"document_dv": "4",
"email": null,
"bank_code": "001",
"account_number": "0002555-1232137",
"account_type": "FP001",
"details": null,
"status": "created"
},
{...},
{...},
{...},
{...}
],
"total": 118,
"current_page": 2,
"last_page": 24,
"per_page": 5
},
"result": 0
}
Cancel payout
This action cancels a payout. The status of the payout should be ‘created’.
Field |
Type |
Description |
Requirement |
pg_serviceid |
String |
Merchant service ID |
required |
pg_token |
String |
A valid authentication access token |
required |
external_id |
String (max. 64 chars) |
Payout ID (at the merchant site) |
required |
POST /payouts/cancel
<?php
/**
* Merchant service ID
*
* @var int
*/
$service_id = "123";
/**
* Merchant shared secret
*
* @var string
*/
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";
// Get an authentication access token
$token = '302ec9c75bf9390db75959e2eded9ae3f5cdb7c1';
$payload = [
'pg_serviceid' => $service_id,
'pg_token' => $token,
'external_id' => 'merchant-id-859649'
];
// sort payload
ksort($payload, SORT_NATURAL | SORT_FLAG_CASE);
$payload = json_encode($payload);
$signature = hash_hmac("sha256", $payload, $shared_secret);
// API URL
$url = 'https://payouts.paygol.com/api/v1/payouts/cancel';
$opts = [
'http' => [
'method' => 'POST',
'header' => [
'Content-type: application/json',
'X-PG-SIG: ' . $signature,
],
'content' => $payload,
],
];
$context = @stream_context_create($opts);
$json_response = @file_get_contents($url, false, $context);
Response
{
"data": {
"id": "merchant-id-859649",
"old_status": "created",
"new_status": "canceled"
},
"result": 0
}
Webhook notifications
With webhooks, we give you the possibility to react automatically to certain events which happen within our system. A webhook is basically a URL where we send an HTTP POST request to, every time one of the events attached to that webhook is triggered.
Event code |
Description |
payout.received |
The payout transaction has been created in the system and is awaiting an action. |
payout.in_process |
The payout transaction has been sent to the bank for processing. |
payout.paid |
The payout transaction has been paid. |
payout.canceled |
The payout transaction has been canceled by the merchant. |
payout.failed |
The payout has not been completed by mistake of the bank or beneficiary information |
<?php
/**
* Merchant shared secret
*
* @var string
*/
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";
try {
$headers = getallheaders();
$content_json = file_get_contents('php://input');
$payload = json_decode($content_json, true);
$signature = hash_hmac("sha256", json_encode($payload), $shared_secret);
if (empty($headers['X-Pg-Sig']) || $headers['X-Pg-Sig'] !== $signature) {
throw new \Exception('Invalid signature');
}
http_response_code(200);
echo json_encode(['OK']);
} catch (\Exception $e) {
http_response_code(401);
echo json_encode(['error' => $e->getMessage()]);
}
Country |
Code |
Document |
Type |
Verification digit |
Argentina |
ar_cuit |
CUIT |
Numeric (11) |
Last digit |
Argentina |
ar_cuil |
CUIL |
Numeric (11) |
Last digit |
Brazil |
br_cpf |
CPF |
Numeric (11) |
Last two digits |
Brazil |
br_cnpj |
CNPJ |
Numeric (14) |
Last two digits |
Chile |
cl_rut |
RUT |
Alphanumeric (8/9) |
Last digit |
Bank codes
Codes for bank_code parameter.
Chile
Bank |
Code |
Banco Del Estado De Chile |
012 |
Banco Bbva ( Bilbao Vizcaya Argentaria Chile) / Banco Bhif |
504 |
Banco Bice |
028 |
Banco Consorcio |
055 |
Banco Corpbanca |
027 |
Banco De Chile / Banco A. Edwards / Credichile / Citybank |
001 |
Banco De Crédito E Inversiones (BCI) / Tbanc |
016 |
Banco Del Desarrollo |
507 |
Banco Falabella |
051 |
Banco Internacional |
009 |
Banco Itau Chile / Bank Boston |
039 |
Banco Ripley |
053 |
Banco París |
057 |
Banco Santander – Santiago / Banco Santander / Banefe |
037 |
Banco Security |
049 |
Coopeuch |
672 |
Hsbc Bank (Chile) |
031 |
Scotiabank / Sud – Americano |
014 |
Account types codes
Codes for account types.
Chile
Method |
Bank |
Code |
Cuenta Corriente / Cuenta Vista |
All banks (CCA Participating Banks) |
FP001 |
Chequera electrónica |
Banco Estado |
FP003 |
Cuenta RUT |
Banco Estado |
FP004 |
Payout status
Available status codes.
Status |
Code |
Description |
Created |
created |
Payout has been received |
In Process |
in-process |
Payout has been sent to the bank for payment |
Paid |
paid |
Payout has been successfully completed |
Canceled |
canceled |
Payout has been canceled by the merchant |
Failed |
failed |
Payout has not been completed by mistake of the bank or beneficiary information |
Error codes
Code |
Description |
999 |
Internal error |
600 |
The pg_serviceid field is required |
601 |
The pg_serviceid field is invalid |
605 |
The pg_token field is required |
604 |
The pg_token field is invalid |
606 |
Signature is missing |
607 |
Signature mismatch |
610 |
The id field is required |
611 |
The id field must be unique |
612 |
The id field is too long |
613 |
The country field is required |
614 |
The country field format is invalid |
615 |
The amount field is required |
616 |
The amount field is invalid |
617 |
The amount is too low |
618 |
The currency field is required |
619 |
The currency field format is invalid |
620 |
The beneficiary object is required |
621 |
The beneficiary type field is required |
622 |
The beneficiary full_name field is required |
623 |
The beneficiary first_name field is required |
624 |
The beneficiary last_name field is required |
625 |
The beneficiary email field is required |
626 |
The beneficiary document_type field is required |
627 |
The beneficiary document_type field is invalid |
628 |
The beneficiary document_number field is required |
629 |
The beneficiary document_dv field is required |
630 |
The account object is required |
631 |
The account bank_code field is required |
632 |
The account number field is required |
633 |
The account type field is required |
634 |
The account bank_code field is invalid |
635 |
The payouts array is required |
636 |
The payouts field must by an array |
637 |
The payouts array is too long |
602 |
Your account is not enabled |
603 |
Payouts are not enabled for this account |