Payouts

by Info emailPosted on Posted in Uncategorized

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 required
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()]);
}

Document validation information.

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