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 Integer 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' => 'CL001',
                '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/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": "CL001",
      "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 Integer 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/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": "CL001",
    "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 Integer 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/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": "CL001",
        "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 Integer 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/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 / Cueta Vista All banks FP001
Cuenta de ahorro All banks FP002
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