Introducción
Esta API le permite depositar dinero en la cuenta bancaria de un cliente. El depósito siempre será realizado en moneda local.
https://payouts.paygol.com/api/v1
Firma del mensaje
Todas las solicitudes a la API de pago deben firmarse utilizando la clave secreta del comerciante con el algoritmo HMAC SHA256. La firma debe calcularse utilizando la carga útil de la solicitud, ordenada en orden ascendente y agregando este resultado en un encabezado de solicitud con el nombre 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);
Obtener un token de autorización
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'];
Solicitar pagos
Descripción de parámetros
Parámetro |
Tipo |
Descripción |
Requerido |
pg_serviceid |
String |
Service ID del Merchant |
requerido |
pg_token |
String |
Un token de autenticación válido |
requerido |
payouts |
Array |
Arreglo de objetos Payout (max. 1500) |
requerido |
payout |
Payout object |
Objeto Payout |
requerido |
beneficiary |
Beneficiary object |
Objeto Beneficiary |
requerido |
account |
Account object |
Objeto Account |
requerido |
Objeto Payout
Parámetro |
Tipo |
Descripción |
Requerido |
id |
String (Max. 64 chars) |
Merchan payout ID único |
requerido |
country |
String (2 chars) |
Código de país del cliente. Código ISO 3166-1 alpha-2 |
requerido |
currency |
String (3 chars) |
Código ISO 4217 |
requerido |
amount |
Decimal (max. 2 decimal numbers) |
Monto del pago (en la moneda correspondiente a lo ingresado en “currency”) |
requerido |
beneficiary |
Beneficiary object |
Objeto Beneficiary |
requerido |
account |
Account object |
Objeto Account |
requerido |
details |
String (max. 255 chars) |
Información opcional |
opcional |
Objeto Beneficiary
Parámetro |
Tipo |
Descripción |
Requerido |
type |
String |
person | company |
requerido |
full_name |
String (Max. 128 chars) |
Nombre completo del benficiario |
requerido |
first_name |
String (Max. 32 chars) |
Nombre del beneficiario |
requerido para beneficiario de tipo person |
last_name |
String (Max. 32 chars) |
Apellido del beneficiario |
requerido para beneficiario de tipo person |
surname |
String (Max. 32 chars) |
Apellido materno beneficiario |
opcional |
document_type |
String |
Tipo de documento de identificación del beneficiario. Ver tipos de documentos |
requerido |
document_number |
String (Max. 32 chars) |
Número de documento de identificación del beneficiario. |
requerido |
document_dv |
String (Max. 2 chars) |
Dígito de verificación |
requerido |
email |
String (Max. 128 chars) |
Dirección de correo del beneficiario |
opcional |
Objeto Account
Parámetro |
Tipo |
Descripción |
Requerido |
bank_code |
String (5 chars) |
Código del banco. Ver Códigos bancarios |
requerido |
bank_name |
String (max. 32 chars) |
Nombre del banco. Ver Nombre de bancos |
opcional |
number |
String (max. 64 chars) |
Número cuenta bancaria |
requerido |
type |
String (5 chars) |
Tipo de cuenta. Ver tipos de cuentas |
requerido |
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);
Respuesta
{
"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
}
Comprobar estado
Comprobar el estado de un pago
Parámetro |
Tipo |
Descripción |
Requerido |
pg_serviceid |
String |
Service ID del merchant |
requerido |
pg_token |
String |
Un token de autenticación válido |
requerido |
external_id |
String (max. 64 chars) |
Merchant Payout ID |
requerido |
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);
Respuesta
{
"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
}
Obtener pagos
Obtener el listado de pagos
Parámetro |
Tipo |
Descripción |
Requerido |
pg_serviceid |
String |
Service ID del merchant |
requerido |
pg_token |
String |
Un token de autenticación válido |
requerido |
status |
String |
Un estado de transacción válido. Ver tabla de estados |
opcional |
limit |
Integer > 0 |
Número máximo de resultados (default 50) |
opcional |
page |
Integer > 0 |
Página (default 1) |
opcional |
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);
Respuesta
{
"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
}
Cancelar pago
Cancelar un pago. Para poder cancelar un pago, este debe estar en estado ‘created’.
Parámetro |
Tipo |
Descripción |
Requerido |
pg_serviceid |
String |
Service ID del merchant |
requerido |
pg_token |
String |
Un token de autenticación válido |
requerido |
external_id |
String (max. 64 chars) |
Merchant Payout ID |
requerido |
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);
Respuesta
{
"data": {
"id": "merchant-id-859649",
"old_status": "created",
"new_status": "canceled"
},
"result": 0
}
Notificaciones Webhook
Con webhooks, le brindamos la posibilidad de reaccionar automáticamente a ciertos eventos que ocurren dentro de nuestro sistema. Un webhook es básicamente una URL a la que enviamos una solicitud HTTP POST cada vez que se activa uno de los eventos adjuntos a ese webhook.
Código evento |
Descripción |
payout.received |
El pago se ha creado en el sistema y se encuentra a la espera de una acción. |
payout.in_process |
El pago ha sido enviado al banco para su procesamiento. |
payout.paid |
El pago ha sido paga por el banco. |
payout.canceled |
El pago ha sido cancelado por el merchant. |
payout.failed |
El pago no ha podido ser completado por un error en la información entregada |
<?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()]);
}
País |
Código |
Documento |
Tipo |
Dígito verificador |
Argentina |
ar_cuit |
CUIT |
Numeric (11) |
Último dígito |
Argentina |
ar_cuil |
CUIL |
Numeric (11) |
Último dígito |
Brazil |
br_cpf |
CPF |
Numeric (11) |
Últimos 2 dígitos |
Brazil |
br_cnpj |
CNPJ |
Numeric (14) |
Últimos 2 dígitos |
Chile |
cl_rut |
RUT |
Alphanumeric (8/9) |
Último dígito |
Códigos de bancos
Códigos para el parámetro bank_code.
Chile
Banco |
Código |
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 |
Tipos de cuentas
Códigos para el parámetro account types.
Chile
Cuenta |
Banco |
Código |
Cuenta Corriente / Cueta Vista |
All banks |
FP001 |
Cuenta de ahorro |
All banks |
FP002 |
Chequera electrónica |
Banco Estado |
FP003 |
Cuenta RUT |
Banco Estado |
FP004 |
Estados
Códigos de estados disponibles.
Estado |
Código |
Descripción |
Creado |
created |
El pago ha sido creado |
En proceso de pago |
in-process |
El pago ha sido enviado al banco |
Pagado |
paid |
El pago ha sido completado satisfactoriamemete |
Cancelado |
canceled |
El pago ha sido cancelado por el merchant |
Fallido |
failed |
El pago ha sido rechazado por el banco por error en la información proporcionada |
Códigos de error
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 |