Servicio de pagos

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

Información de documento.

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