# Payku API — 🇻🇪 Venezuela (EN)

> Official Payku API documentation for Venezuela, auto-generated from the OpenAPI specification (v2.1.01). Source: https://docs.payku.com/ · Sandbox: https://des.payku.cl/

Base URL: `https://app.payku.cl/` (Production) · `https://des.payku.cl/` (Sandbox)

## Introduction

Welcome to the Payku API. You can use our API to access the different
Payku endpoints, where you can generate and manage payments through different
methods and get information from them.

The API is organized around REST. It has predictable URLs and resource-oriented,
and uses HTTP response codes to indicate the result of the call. All API
responses return objects JSON, including errors.

User should look for a 200 result code. If received any result code other
than 200, the request, or the response is invalid, which means that the fields
did not pass the checks of validation from payku. We use features included in
the HTTP protocol, such as authentication, which are supported by the most HTTP
clients.

**Important — How to tell if an operation failed**

Do not rely only on the HTTP status code (for example, 200). In our API, many
error responses also return HTTP 200. This is intentional and part of how the
API is designed.

Always read the JSON response body and check the `status` field:
- If `status` is `"success"`, the operation completed successfully.
- If `status` is `"failed"`, there was an error (for example, invalid data or a
  rejected operation). Also check the error message included in the same response.

## Authentication

Payku uses Token Based Authentication over HTTPS for authentication. To have
access to our API, access your account in the section of Integration you will
find the option of integration and API tokens. The request Unauthenticated or
incorrect will return an Invalid token response.

## API Security

Each request is required to have included in the header:
  - Authorization: Bearer **TOKEN-PÚBLICO**

## Signature

In the case of the third-party payments (payout) API, an additional layer of security was added
through of a signature that is sent in the request header, to obtain said signature
is necessary the following:

The Request Path must be concatenated in url format along with all the request
parameters, which must be ordered alphabetically by key, such that key = value.
Therefore, if the client email value is "example@domain.com" the correct format
would be "example%40domain.com" and then concatenated with the character '&'.

Once the character sets are ordered and concatenated, the hash is calculated
using the HMAC function with encryption type sha256, and the private token.

**Note:** If an element of the data has as value an object or array, it is excluded from the data. This function is in the PHP and Javascript example.

### PHP Example
API Endpoint:
```php
$request_path = urlencode('/api/suclient');
```
Sorting the parameters:
```php
$data = [
  'email' => 'support@youwebsite.cl',
  'name' => 'Joe Doe',
  'phone' => '923122312',
  'address' => 'Moneda 101',
  'country' => 'Chile',
  'region' => 'Metropolitana',
  'city' => 'Santiago',
  'postal_code' => '850000',
  'additional_parameters' => [
    'parameter_1' => 'example',
    'parameter_2' => 'example 2',
  ]
];
ksort($data);
```
Transformation of the parameters to url format:
```php
    $contador = 0;
    $concatenar = null;

    if (!empty($data) && !is_null($data)) {
        foreach ($data as $key => $val) {
            if(gettype($val)!='array' && gettype($val)!='object'){
                if ($contador>0) {
                    $concatenar .= '&';
                }
                $concatenar .= $key . '=' . urlencode($val);
                $contador++;
            }
        }
    };
```
Concatenation of the parameters in url format with the API endpoint:
```php
$concat = $request_path.'&'.$concatenar;
```
Sign:
```php
$sign = hash_hmac('sha256', $concat, 'fe551abcef62fcf002dc598922e68f0a');
```

### JavaScript Example
Import CryptoJS dependency:
```javascript
const CryptoJS = require("crypto-js");
```
API Endpoint:
```javascript
const requestPath = encodeURIComponent('/api/suclient');
```
Sorting the parameters:
```javascript
const data = {
  email: "support@youwebsite.cl",
  name: "Joe Doe",
  phone: "923122312",
  address: "Moneda 101",
  country: "Chile",
  region: "Metropolitana",
  city: "Santiago",
  postal_code: "850000"
};
const orderedData = {};
Object.keys(data).sort().forEach(function(key) {
  orderedData[key] = data[key];
  if (typeof orderedData[key] === 'object') {
        delete orderedData[key];
  }
});
```
Transformation of the parameters to url format:
```javascript
const arrayConcat = new URLSearchParams(orderedData).toString();
```
Concatenation of the parameters in url format with the API endpoint:
```javascript
const concat = requestPath + "&" + arrayConcat;
```
Sign:
```javascript
const sign = CryptoJS.HmacSHA256(concat, "fe551abcef62fcf002dc598922e68f0a").toString();
```

The result of the signature obtained for both examples is:

```javascript
"d891663698d31aa8b68babe96ac6497f5a0d874024368102998d5b79a4d12c36"
```

## Errors

Payku uses conventional HTTP responses to indicate the success or failure of a request.
In general, codes in the 2xx range indicate success, codes in the 4xx range indicate
an error that failed due to the information provided (ex: a required parameter was
skipped, a payment failed, etc.), and codes in the 5xx range indicate an error with
Payku servers (these are rare).

## Error codes
<div class="errorContent">
<table>
  <tbody>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">400</strong>
        <p class="psmall">Bad Request</p>
      </td>
      <td class="errorDescription">There is a problem with your request</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">401</strong>
        <p class="psmall">Unauthorized</p>
      </td>
      <td class="errorDescription">Your token is incorrect or signature is incorrect</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">403</strong>
        <p class="psmall">Forbidden</p>
      </td>
      <td class="errorDescription">You do not have permission to view this page</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">404</strong>
        <p class="psmall">Not Found</p>
      </td>
      <td class="errorDescription">The specified resource was not found</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">405</strong>
        <p class="psmall">Method Not Allowed</p>
      </td>
      <td class="errorDescription">You tried to enter a resource with an invalid method</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">406</strong>
        <p class="psmall">Not Acceptable</p>
      </td>
      <td class="errorDescription">You requested a format other than JSON</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">410</strong>
        <p class="psmall">Gone</p>
      </td>
      <td class="errorDescription">The requested resource was removed from our servers</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">422</strong>
        <p class="psmall">Unprocessable Entity</p>
      </td>
      <td class="errorDescription">We cannot process your request, please review it.</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">429</strong>
        <p class="psmall">Too Many Requests</p>
      </td>
      <td class="errorDescription">You are requesting a lot of resources! Stop!</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">500</strong>
        <p class="psmall">Internal Server Error</p>
      </td>
      <td class="errorDescription">We had a problem with our server. Please try again later.</td>
    </tr>
    <tr>
      <td style="text-align: right"><strong class="errorTitle">503</strong>
        <p class="psmall">Service Unavailable</p>
      </td>
      <td class="errorDescription">We are offline for maintenance. Please try again later.</td>
    </tr>
  </tbody>
</table>
</div>

## API access

If you have a payku account, you can access the REST API through the following endpoints:

<div class="content">
  <table class="center smallTable">
    <thead>
      <tr>
        <th style="text-align:center;"><strong>Site</strong></th>
        <th style="text-align:center;"><strong>BASE URL FOR REST ENDPOINT</strong></th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><strong>Production</strong></td>
        <td align="center"><a href="https://app.payku.cl/api">https://app.payku.cl/</a></td>
      </tr>
      <tr>
        <td><strong>Sandbox</strong></td>
        <td><a href="https://des.payku.cl/api">https://des.payku.cl/</a></td>
      </tr>
    </tbody>
  </table>
</div>

- **Production**: provides direct access to generate actual transactions.
- **Sandbox**: allows you to test your integration without affecting the actual data.

## Transaction

### Create

`POST /api/transaction`

This method allows you to create a payment order and returns the **URL** and **TOKEN** that identify the transaction.

Additional parameters:

1. **additional_parameters** = Allows you to send additional information that will be recorded with the transaction:

  **IMPORTANT additional_parameters.gateway:**
  - Allows specifying the final payment method
  - **<span style="color: red">REQUIRED</span>** for merchants using the On-Site method

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | ✓ | Payer's email — ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ — [ 20 .. 100 ] — Example: `payer@domain.com` |
| `order` | string | ✓ | Merchant's order — ^[a-zA-Z0-9- ]{1,40}$ — [ 20 .. 40 ] — Example: `order-commerce-999` |
| `subject` | string | ✓ | Order description — ^[a-zA-Z0-9 ]{1,200}$ — [ 1 .. 200 ] — Example: `description of the order` |
| `amount` | integer | ✓ | Order amount — ^[0-9]+$ — Example: `100` |
| `currency` | string | ✓ | VES — ISO 4217 — [ 3 .. 3 ] — Example: `VES` |
| `payment` | integer | ✓ | 17 — ^[0-9]{1,2}$ — Example: `17` |
| `urlreturn` | string |  | Merchant return URL where the payer will be redirected after the transaction result is obtained. — ^https:\/\/([\w\-]+\.)+[\w\-]+(\/[\w\-\.\/?%&=]*)?$ — [ 1 .. 255 ] — Example: `https://youwebsite.com/return/client/order-commerce-999` |
| `urlnotify` | string | ✓ | Merchant callback URL where the payment result will be notified. **Note:** Once the client completes the payment process, the callback URL (urlnotify) will be notified with the result of the banking operation. **Example of a successful response:** ```json { "transaction_id": "991...", "payment_key": "trx...", "transaction_key": "991...", "verification_key": "8b3...", "order": "199...", "status": "success" } ``` **Example of a failed response:** ```json { "transaction_id": "991...", "payment_key": "trx3...", "transaction_key": "991...", "verification_key": "8b3e...", "order": "199...", "status": "failed" } ``` — ^https:\/\/([\w\-]+\.)+[\w\-]+(\/[\w\-\.\/?%&=]*)?$ |
| `additional_parameters` | object |  | Additional merchant parameters. |
| ↳ `gateway` | string |  | Select the desired payment method: \| Code \| Method \| Description \| On-Site \| \|------\|--------\|-------------\|---------\| \| VZLAVECAP2C \| Mobile Payment (P2C) \| PagoMóvil (Most popular) \| YES \| \| BMIGVECAP2C \| Mobile Payment (P2C) \| PagoMóvil (Most popular) \| \| \| BMIGVECAC2P \| Mobile Payment (C2P) \| BancAmiga (Instant payment) \| \| \| BAMRVECAC2P \| Mobile Payment (C2P) \| Mercantil (Instant payment) \| \| \| UNIOVECAP2C \| Banesco \| BotónPago (Bank transfer) \| \| \| VZLAVECABIO \| Cards \| BDV BioPago (Debit and Credit) \| \| Note: For methods marked as "On-Site: YES", the response will include additional information: ```json { "status": "register", "id": "trx...", "url": "https://[BASE_URL]/api/validonsite", "account_service": { "bank_method": "PA...", "bank_number": "04...", "bank_document": "J-...", "bank_name": "Ban...", "bank_nameshort": "Ve...", "bank_code": "01...", "bank_linkqr": "htt..." }, "attributes_request": { "transaction": "trx...", "payer": { "phone_number": "required", "payment_reference": "required", "id_number": "required", "bank_code": "required", "payment_date": "optional" } } } ``` Key fields in the On-Site response: - status: Initial transaction status - id: Unique transaction identifier - url: URL to complete the payment, e.g. `/api/validonsite` - account_service: Bank info to be shown in the payment form - attributes_request: Required data to complete the payment — Example: `CODE` |

**cURL**

```bash
curl -X POST \
https://BASE-URL/api/transaction \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer TOKEN-PUBLIC' \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL' \
-d '{
  "email": "payer@domain.com",
  "order": "order-commerce-999",
  "subject": "description of the order",
  "amount": 100,
  "currency": "VES",
  "payment": 17,
  "urlreturn": "https://youwebsite.com/return/client/order-commerce-999",
  "urlnotify": "https://youwebsite.com/callback/commerce/order-commerce-999",
  "additional_parameters": {
    "gateway":"GATEWAY_CODE"
  }
}'
```

**PHP**

```php
$client = new \GuzzleHttp\Client();
$body = $client->request('POST', 'https://BASE_URL/api/transaction', [
  'json' => [
    'email' => 'payer@domain.com',
    'order' => 'order-commerce-999',
    'subject' => 'description of the order',
    'amount' => 100,
    'currency' => 'VES',
    'payment' => 17,
    'urlreturn' => 'https://youwebsite.com/return/client/order-commerce-999',
    'urlnotify' => 'https://youwebsite.com/callback/commerce/order-commerce-999',
    'additional_parameters' => [
      'gateway' => 'GATEWAY_CODE'
    ]
  ],
  'headers' => [
    'Authorization' => 'Bearer TOKEN_PUBLIC'
  ]
])->getBody();
$response = json_decode($body);
```

**JS**

```js
const data = {
  "email": "payer@domain.com",
  "order": "order-commerce-999",
  "subject": "description of the order",
  "amount": 100,
  "currency": "VES",
  "payment": 17,
  "urlreturn": "https://youwebsite.com/return/client/order-commerce-999",
  "urlnotify": "https://youwebsite.com/callback/commerce/order-commerce-999",
  "additional_parameters": {
    "gateway": "GATEWAY_CODE"
  }
};
const request = async (data) => {
  const response = await fetch('https://BASE_URL/api/transaction', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer TOKEN_PUBLIC'
    },
    body: JSON.stringify(data)
  });
  const result = await response.json();
  console.log(result)
}
request(data);
```

**Responses**

*200*

```json
{
  "status": "register",
  "id": "trx6...",
  "url": "https://[BASE_URL]/path?id=trx...&valid=e3c4...",
  "account_service": {
    "bank_method": "PA..",
    "bank_number": "04...",
    "bank_document": "J...",
    "bank_name": "Ban...",
    "bank_nameshort": "Ve...",
    "bank_code": "01...",
    "bank_linkqr": "ht..."
  },
  "attributes_request": {
    "transaction": "tr...",
    "payer": {
      "phone_number": "string",
      "payment_reference": "required"
    }
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Transaction status. The possible status values are: - register - success — Example: `register` |
| `id` | string |  | Unique identifier of the transaction — Example: `trx6...` |
| `url` | string |  | URL to redirect the user. — Example: `https://[BASE_URL]/path?id=trx...&valid=e3c4...` |
| `account_service` | object |  | **[!ONLY FOR ON-SITE METHODS!]** Banking service information required to make the payment. |
| ↳ `bank_method` | string |  | Bank payment method — Example: `PA..` |
| ↳ `bank_number` | string |  | Mobile payment phone number — Example: `04...` |
| ↳ `bank_document` | string |  | Bank identification document — Example: `J...` |
| ↳ `bank_name` | string |  | Full name of the bank — Example: `Ban...` |
| ↳ `bank_nameshort` | string |  | Short name of the bank — Example: `Ve...` |
| ↳ `bank_code` | string |  | Bank code — Example: `01...` |
| ↳ `bank_linkqr` | string |  | URL of the QR code for payment — Example: `ht...` |
| `attributes_request` | object |  | **[!ONLY FOR ON-SITE METHODS!]** Data required to complete and report the payment. |
| ↳ `transaction` | string |  | Transaction identifier — Example: `tr...` |
| ↳ `payer` | object |  | Required payer information |
| ↳ ↳ `phone_number` | string |  | Payer's phone number |
| ↳ ↳ `payment_reference` | string |  | Payment reference — Example: `required` |

*400* — Bad request.

```json
{
  "status": "failed",
  "type": "Unprocessable Entity",
  "message_error": "subject:invalid,amount:is empty,email:is empty,order:invalid"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Unprocessable Entity` |
| `message_error` | string |  | Error message. — Example: `subject:invalid,amount:is empty,email:is empty,order:invalid` |

### Confirm On-Site

`POST /api/validonsite`

This method allows the payment to be confirmed on the merchant's website by sending payer information for verification. The result of the transaction will be reported via the [urlnotify] callback.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | string | ✓ | Unique transaction identifier — Example: `trx24...` |
| `payer` | object | ✓ | Payer information |
| ↳ `phone_number` | string | ✓ | Payer's phone number — Example: `04129874563` |
| ↳ `payment_reference` | string | ✓ | Payment reference issued by the banking entity — Example: `12345600` |
| ↳ `id_number` | string | ✓ | Payer's ID number — Example: `V12987456` |
| ↳ `bank_code` | string | ✓ | Payer's bank code — Example: `0102` |
| ↳ `payment_date` | string |  | Payment date (optional) — Example: `2026-08-25` |

**cURL**

```bash
curl -X POST \
'https://BASE_URL/api/validonsite' \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer TOKEN-PUBLIC' \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL' \
-d '{
  "transaction": "trx2...",
  "payer": {
    "phone_number": "04129874563",
    "payment_reference": "12345600",
    "id_number": "V12987456",
    "bank_code": "0102",
    "payment_date": "2026-08-25"
  }
}'
```

**PHP**

```php
$client = new \GuzzleHttp\Client();
$body = $client->request('POST', 'https://BASE_URL/api/validonsite', [
  'json' => [
    'transaction' => 'trx2...',
    'payer' => [
      'phone_number' => '04129874563',
      'payment_reference' => '12345600',
      'id_number' => 'V12987456',
      'bank_code' => '0102',
      'payment_date' => '2026-08-25'
    ]
  ],
  'headers' => [
    'Authorization' => 'Bearer TOKEN_PUBLICO'
  ]
])->getBody();
$response = json_decode($body);
```

**JS**

```js
const data = {
  "transaction": "trx2...",
  "payer": {
    "phone_number": "04129874563",
    "payment_reference": "12345600",
    "id_number": "V12987456",
    "bank_code": "0102",
    "payment_date": "2026-08-25"
  }
};
const request = async (data) => {
  const response = await fetch('https://BASE_URL/api/validonsite', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer TOKEN_PUBLICO'
    },
    body: JSON.stringify(data)
  });
  const result = await response.json();
  console.log(result)
}
request(data);
```

**Responses**

*200* — Successful response

```json
{
  "transaction": "trx24...",
  "status": "register",
  "message": "payment received and pending verification",
  "gateway": {
    "status": "successful"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | string | ✓ | Unique transaction identifier — Example: `trx24...` |
| `status` | string | ✓ | Transaction status — Example: `register` |
| `message` | string | ✓ | Descriptive status message — Example: `payment received and pending verification` |
| `gateway` | object | ✓ | Payment gateway information |
| ↳ `status` | string |  | Gateway status — Example: `successful` |

*400* — Bad request

```json
{
  "transaction": "trx24...",
  "status": "failed",
  "message_error": "charge already used or consumed"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transaction` | string | ✓ | Unique transaction identifier — Example: `trx24...` |
| `status` | string | ✓ | Transaction status — Example: `failed` |
| `message_error` | string | ✓ | Descriptive error message — Example: `charge already used or consumed` |

### Get

`GET /api/transaction/{id}`

This method allows you to obtain the information of a transaction

**Path parameters**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | ✓ | Unique transaction identifier - id: Identifier of the transaction (Transaction/POST) — maximum 40 characters |

**Responses**

*200*

```json
{
  "status": "success",
  "id": "10ac494c1d8da71d98ea",
  "created_at": "2019-10-25 14:10:03",
  "order": "1572023402",
  "email": "support@youwebsite.cl",
  "subject": "1572023402",
  "amount": "98745",
  "payment": {
    "start": "2020-12-16 15:10:33",
    "end": "2020-12-16 15:10:36",
    "media": "VEPUY",
    "transaction_id": 107999,
    "transaction_key": null,
    "deposit_date": "2023-10-05",
    "verification_key": "666...",
    "authorization_code": "10...",
    "last_4_digits": "0000",
    "installments": 0,
    "card_type": "VN",
    "additional_parameters": {
      "gateway": "CODE_GATEWAY",
      "network": {
        "ip_address": "192.0.2.123"
      }
    },
    "currency": "VES"
  },
  "nullify": {
    "status": "complete"
  },
  "gateway_response": {
    "status": "success",
    "message": "successful transaction"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Transaction status The possible statuses you can get are the following: - register - pending - success - rejected — Example: `success` |
| `id` | string |  | Transaction identifier created by Payku. — Example: `10ac494c1d8da71d98ea` |
| `created_at` | string |  | Registration date. — Example: `2019-10-25 14:10:03` |
| `order` | string |  | Number of order. — Example: `1572023402` |
| `email` | string |  | Client email. — Example: `support@youwebsite.cl` |
| `subject` | string |  | Description of the purchase order. — Example: `1572023402` |
| `amount` | string |  | Amount. — Example: `98745` |
| `payment` | object |  |  |
| ↳ `start` | string |  | Inicio de la transacción. — Example: `2020-12-16 15:10:33` |
| ↳ `end` | string |  | Fin de la transacción. — Example: `2020-12-16 15:10:36` |
| ↳ `media` | string |  | Payment method, used by the user. — Example: `VEPUY` |
| ↳ `transaction_id` | string |  | Identifier of the transaction created by payku. — Example: `107999` |
| ↳ `transaction_key` | string |  | Transaction identifier created by Payku. |
| ↳ `deposit_date` | string |  | Date on which the deposit will be made to the customer. — Example: `2023-10-05` |
| ↳ `verification_key` | string |  | Verification code generated by Payku. — Example: `666...` |
| ↳ `authorization_code` | string |  | Authorization code. — Example: `10...` |
| ↳ `last_4_digits` | string |  | Last 4 digits of the affiliated card. — Example: `0000` |
| ↳ `installments` | int |  | Installments. — Example: `0` |
| ↳ `card_type` | string |  | Card type. — Example: `VN` |
| ↳ `additional_parameters` | object |  | **Example** of additional parameters that may be sent by Payku. |
| ↳ ↳ `gateway` | string |  | Example: `CODE_GATEWAY` |
| ↳ ↳ `network` | object |  | User network data: |
| ↳ ↳ ↳ `ip_address` | string |  | **Example** of IP Address of the user: — Example: `192.0.2.123` |
| ↳ `currency` | string |  | Currency. — Example: `VES` |
| `nullify` | object |  | Objeto que contiene información de la respuesta de la anulación |
| ↳ `status` | string |  | Estatus de anulación. Los posibles estados que puede obtener son los siguientes: - pending - awaiting_funds - waiting_bank_details - complete - reverse_deleted - reverse_completed — Example: `complete` |
| `gateway_response` | object |  | Object containing transaction response information |
| ↳ `status` | string |  | Transaction status The possible statuses you can get are the following: - pending - success - rejected - refunded partial - refunded — Example: `success` |
| ↳ `message` | string |  | Message describing the status. - successful transaction - Transaction rejected. - Transaction must be retried. - Error transaction. - Rate Error Rejection. - Exceeds maximum monthly quota. - Exceeds daily limit per transaction. - unauthorized item. — Example: `successful transaction` |

*400* — Request failed.

```json
{
  "status": "failed",
  "type": "Unprocessable Entity",
  "message_error": "subject:invalid,amount:is empty,email:is empty,order:invalid"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Unprocessable Entity` |
| `message_error` | string |  | Error message. — Example: `subject:invalid,amount:is empty,email:is empty,order:invalid` |

*404* — Identifier does not exist.

```json
{
  "status": "failed",
  "type": "Not Found",
  "id": "is not valid"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Not Found` |
| `id` | string |  | Id information — Example: `is not valid` |

### List

`GET /api/transaction?success=true`

This method allows you to retrieve information about transactions made on Payku. It supports pagination with a maximum of 4000 records per page.

| Parameter  | Description | Example |
|------------|-------------|---------|
| date_init  | Start date for the transaction search. If not specified, the current date is used. | date_init=2025-01-01 |
| date_end   | End date for the transaction search. If not specified, the current date is used. | date_end=2025-12-31 |
| success    | Filters successful transactions. | success=true |
| pending    | Filters pending transactions. | pending=true |
| rejected   | Filters rejected transactions. | rejected=true |
| page       | Page number for pagination. | page=1 |
| per_page   | Number of records per page (max 4000). | per_page=100 |

**Example of full URL:**
```
https://[BASE_URL]/api/transaction?date_init=2025-01-01&date_end=2025-12-31&success=true&page=1&per_page=100
```

**Responses**

*200*

```json
{
  "status": "success",
  "id": "10ac494c1d8da71d98ea",
  "created_at": "2019-10-25 14:10:03",
  "order": "1572023402",
  "email": "support@youwebsite.cl",
  "subject": "1572023402",
  "amount": "98745",
  "payment": {
    "start": "2020-12-16 15:10:33",
    "end": "2020-12-16 15:10:36",
    "media": "VEPUY",
    "transaction_id": 107999,
    "transaction_key": null,
    "deposit_date": "2023-10-05",
    "verification_key": "666...",
    "authorization_code": "10...",
    "last_4_digits": "0000",
    "installments": 0,
    "card_type": "VN",
    "additional_parameters": {
      "gateway": "CODE_GATEWAY",
      "network": {
        "ip_address": "192.0.2.123"
      }
    },
    "currency": "VES"
  },
  "nullify": {
    "status": "complete"
  },
  "gateway_response": {
    "status": "success",
    "message": "successful transaction"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Transaction status The possible statuses you can get are the following: - register - pending - success - rejected — Example: `success` |
| `id` | string |  | Transaction identifier created by Payku. — Example: `10ac494c1d8da71d98ea` |
| `created_at` | string |  | Registration date. — Example: `2019-10-25 14:10:03` |
| `order` | string |  | Number of order. — Example: `1572023402` |
| `email` | string |  | Client email. — Example: `support@youwebsite.cl` |
| `subject` | string |  | Description of the purchase order. — Example: `1572023402` |
| `amount` | string |  | Amount. — Example: `98745` |
| `payment` | object |  |  |
| ↳ `start` | string |  | Inicio de la transacción. — Example: `2020-12-16 15:10:33` |
| ↳ `end` | string |  | Fin de la transacción. — Example: `2020-12-16 15:10:36` |
| ↳ `media` | string |  | Payment method, used by the user. — Example: `VEPUY` |
| ↳ `transaction_id` | string |  | Identifier of the transaction created by payku. — Example: `107999` |
| ↳ `transaction_key` | string |  | Transaction identifier created by Payku. |
| ↳ `deposit_date` | string |  | Date on which the deposit will be made to the customer. — Example: `2023-10-05` |
| ↳ `verification_key` | string |  | Verification code generated by Payku. — Example: `666...` |
| ↳ `authorization_code` | string |  | Authorization code. — Example: `10...` |
| ↳ `last_4_digits` | string |  | Last 4 digits of the affiliated card. — Example: `0000` |
| ↳ `installments` | int |  | Installments. — Example: `0` |
| ↳ `card_type` | string |  | Card type. — Example: `VN` |
| ↳ `additional_parameters` | object |  | **Example** of additional parameters that may be sent by Payku. |
| ↳ ↳ `gateway` | string |  | Example: `CODE_GATEWAY` |
| ↳ ↳ `network` | object |  | User network data: |
| ↳ ↳ ↳ `ip_address` | string |  | **Example** of IP Address of the user: — Example: `192.0.2.123` |
| ↳ `currency` | string |  | Currency. — Example: `VES` |
| `nullify` | object |  | Objeto que contiene información de la respuesta de la anulación |
| ↳ `status` | string |  | Estatus de anulación. Los posibles estados que puede obtener son los siguientes: - pending - awaiting_funds - waiting_bank_details - complete - reverse_deleted - reverse_completed — Example: `complete` |
| `gateway_response` | object |  | Object containing transaction response information |
| ↳ `status` | string |  | Transaction status The possible statuses you can get are the following: - pending - success - rejected - refunded partial - refunded — Example: `success` |
| ↳ `message` | string |  | Message describing the status. - successful transaction - Transaction rejected. - Transaction must be retried. - Error transaction. - Rate Error Rejection. - Exceeds maximum monthly quota. - Exceeds daily limit per transaction. - unauthorized item. — Example: `successful transaction` |

*400* — Request error.

```json
{
  "status": "failed",
  "type": "Unprocessable Entity",
  "message_error": "subject:invalid,amount:is empty,email:is empty,order:invalid"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Unprocessable Entity` |
| `message_error` | string |  | Error message. — Example: `subject:invalid,amount:is empty,email:is empty,order:invalid` |

*404* — Identifier does not exist.

```json
{
  "status": "failed",
  "type": "Not Found",
  "id": "is not valid"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Not Found` |
| `id` | string |  | Id information — Example: `is not valid` |

## Wallet

### Make payments to third parties from my wallet

`POST /api/wallet/payout`

This method allows you to create a payment order to a third party using funds from your **Payku** virtual wallet.

**Note:** For testing purposes (Development environment only), specific amounts will be processed automatically:
<br>
&bull;  Amounts 1000, 2000, 3000: Will be marked as **approved** automatically.
<br>
&bull;  Amounts 1500, 2500, 3500: Will be marked as **rejected** automatically.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | ✓ | User's email — max 50 characters — Example: `payer@domain.com` |
| `phone` | string |  | User's phone number — max 20 characters — Example: `04149876543` |
| `subject` | string | ✓ | Description of the order — max 200 characters — Example: `description of the order` |
| `currency` | string | ✓ | Currency type (ISO format) — max 6 characters — Example: `VES` |
| `order` | string | ✓ | Merchant order — max 50 characters — Example: `order-commerce-999` |
| `amount` | integer | ✓ | Order amount — max 14 digits — Example: `1000` |
| `accountbank_name` | string | ✓ | Account holder's name — max 180 characters — Example: `John Doe` |
| `accountbank_rut` | string | ✓ | ID number of the account holder Format: (V/E/J) VXXXXXXXX — max 15 characters — Example: `V23654789` |
| `accountbank_sbif` | string | ✓ | Bank code of the destination account. - 0102 Banco De Venezuela - 0104 Banco Venezolano De Credito - 0105 Banco Mercantil - 0108 Banco Provincial - 0114 Banco Del Caribe - 0115 Banco Exterior - 0128 Banco Caroni - 0134 Banesco - 0137 Sofitasa - 0138 Banco Plaza - 0146 Bangente - 0151 Banco Fondo Común - 0156 100% Banco - 0157 Delsur Banco Universal - 0163 Banco Del Tesoro - 0166 Banco Agrícola De Venezuela - 0168 Bancrecer - 0169 R4 Banco Microfinanciero C.A. - 0171 Banco Activo - 0172 Bancamiga - 0173 Banco Internacional De Desarrollo - 0174 Banplus - 0175 Banco Bicentenario - 0178 N58 Banco Digital - 0191 Banco Nacional De Credito — max 4 characters — Example: `0102` |
| `accountbank_type` | string | ✓ | Type of account. - 1 Checking - 3 Savings — max 1 character — Example: `1` |
| `accountbank_num` | string | ✓ | Customer's account number in Venezuela Format: (0412 / 0414 / 0424 / 0426 / 0416) 9876543 — max 200 characters — Example: `04149876543` |
| `url_notify` | string |  | Callback where the result of the payment will be notified. - Note: After making the third-party payment, Payku will automatically respond to the URL provided in `url_notify` with the result. - **Approved example:** - { - "id": "morexzxxxx", - "identifier_payout": "morexzxxxx", - "order": "367734544", - "status": "success", - "update_at": "2023-08-24 12:29:35", - "customer": { - "name": "Jhon Doe", - "phone": "04149876543", - "document": "V23654789", - "number": "04149876543" - } - } - **Rejected example:** - { - "id": "morexzxxxx", - "identifier_payout": "morexzxxxx", - "order": "367734544", - "status": "banking_error", - "update_at": "2023-08-24 12:29:35", - "customer": { - "name": "Jhon Doe", - "phone": "04149876543", - "document": "V23654789", - "number": "04149876543" - } - } — max 600 characters — Example: `https://youwebsite.com/callback/commerce/order-commerce-999` |
| `additional_parameters` | object |  | Optional customer additional parameters. — max 4000 characters |
| ↳ `parameter_1` | string |  | Custom parameter name defined by Payku user — Example: `keyValue` |
| ↳ `parameter_2` | string |  | Custom parameter name defined by Payku user — Example: `keyValue` |

**cURL**

```bash
curl -X POST \
https://BASE-URL/api/wallet/payout \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer PUBLIC-TOKEN' \
-H 'Sign: SHA256-REQUEST-PATH-VALUE-PRIVATE-TOKEN'  \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL' \
-d '{
  "email": "payer@domain.com",
  "phone": "04149876543",
  "subject": "payOut description 9876",
  "currency": "VES",
  "order": "9876",
  "amount": 1000,
  "accountbank_name": "Jhon Doe",
  "accountbank_rut": "V23654789",
  "accountbank_sbif": "0102",
  "accountbank_type": "1",
  "accountbank_num": "04149876543",
  "url_notify": "https://youwebsite.com/urlnotify?orderClient=9876",
  "additional_parameters": {
    "custom_parameter_1": "keyValue",
    "custom_parameter_2": "SpecificValue2",
    "external_reference": "REF-777"
  }
}'
```

**PHP**

```php
$client = new \GuzzleHttp\Client();
$body = $client->request('POST', 'https://BASE_URL/api/wallet/payout', [
  'json' => [
    'email' => 'payer@domain.com',
    'phone' => '04149876543',
    'subject' => 'payOut description 9876',
    'currency' => 'VES',
    'order' => '9876',
    'amount' => 1000,
    'accountbank_name' => 'Jhon Doe',
    'accountbank_rut' => 'V23654789',
    'accountbank_sbif' => '0102',
    'accountbank_type' => '1',
    'accountbank_num' => '04149876543',
    'url_notify' => 'https://youwebsite.com/urlnotify?orderClient=9876',
    'additional_parameters' => [
      'custom_parameter_1' => 'keyValue',
      'custom_parameter_2' => 'SpecificValue2',
      'external_reference' => 'REF-777'
    ]
  ],
  'headers' => [
    'Authorization' => 'Bearer PUBLIC_TOKEN',
    'Sign' => 'SHA256-REQUEST-PATH-VALUE-PRIVATE-TOKEN'
  ]
])->getBody();
$response = json_decode($body);
```

**JS**

```js
const data = {
  "email": "payer@domain.com",
  "phone": "04149876543",
  "subject": "payOut description 9876",
  "currency": "VES",
  "order": "9876",
  "amount": 1000,
  "accountbank_name": "Jhon Doe",
  "accountbank_rut": "V23654789",
  "accountbank_sbif": "0102",
  "accountbank_type": "1",
  "accountbank_num": "04149876543",
  "url_notify": "https://youwebsite.com/urlnotify?orderClient=9876",
  "additional_parameters": {
    "custom_parameter_1": "keyValue",
    "custom_parameter_2": "SpecificValue2",
    "external_reference": "REF-777"
  }
};
const request = async (data) => {
  const response = await fetch('https://BASE_URL/api/wallet/payout', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer PUBLIC_TOKEN',
      'Sign': 'SHA256-REQUEST-PATH-VALUE-PRIVATE-TOKEN'
    },
    body: JSON.stringify(data)
  });
  const result = await response.json();
  console.log(result)
}
request(data);
```

**Responses**

*200*

```json
{
  "status": "success",
  "identifier_wallet": "wvb5f7232dafff18f9",
  "identifier_payout": "mv40746ab8eff910f41e"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Status of the load to the wallet. The possible statuses that can be obtained are the following: - success - failed — Example: `success` |
| `identifier_wallet` | string |  | payku virtual wallet movement identifier. — Example: `wvb5f7232dafff18f9` |
| `identifier_payout` | string |  | Third party payment identifier. — Example: `mv40746ab8eff910f41e` |

*400* — Request error.

```json
{
  "status": "failed",
  "type": "Unprocessable Entity",
  "message_error": "subject:invalid,amount:is empty,email:is empty,order:invalid"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Unprocessable Entity` |
| `message_error` | string |  | Error message. — Example: `subject:invalid,amount:is empty,email:is empty,order:invalid` |

### Get payout V3

`GET /api/payoutv3/{identificadorPayout}`

This method allows you to obtain a movement of payments to third parties from your **payku** virtual wallet using an identifier:

To perform the query it is necessary to add the following at the end of the endpoint /{identificadorPayout} for example: **api/payoutv3/wa24bg36767**.

**CURL**

```text
curl -X GET \
https://BASE-URL/api/payoutv3/{identificadorPayout}  \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer PUBLIC-TOKEN' \
-H 'Sign: SHA256-REQUEST-PATH-VALUE-PRIVATE-TOKEN'  \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL' \
```

**PHP**

```php
$client = new \GuzzleHttp\Client();
  $body = $client->request('GET', 'https://BASE_URL/api/payoutv3/{identificadorPayout}', [
    'headers' => [
      'Authorization' => 'Bearer PUBLIC-TOKEN',
      'Sign' => 'SHA256-REQUEST-PATH-VALUE-PRIVATE-TOKEN'
    ]
  ])->getBody();
$response = json_decode($body);
```

**JS**

```js
const request = async () => {
  const response = await fetch('https://BASE_URL/api/payoutv3/{identificadorPayout}', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer PUBLIC-TOKEN',
      'Sign': 'SHA256-REQUEST-PATH-VALUE-PRIVATE-TOKEN'
    },
  });
  const result = await response.json();
  console.log(result)
}

request();
```

**Responses**

*200*

```json
{
  "payout": {
    "id": "war3999847529816f2",
    "phone": "111111111",
    "email": "test@test.cl",
    "subject": "subject order",
    "amount": "3680",
    "accountbank_rut": "111111111",
    "accountbank_name": "test",
    "accountbank_type": 1,
    "accountbank_num": 123123123,
    "accountbank_sbif": "0001",
    "status": "pending",
    "update_at": "2022-06-09 21:10:46",
    "origin_wallet": "wa1933f37cdaf7d1c6",
    "reason_rejection": " Error CCA 51. Cuenta Beneficiario no Existe, error_creditor_account_not_found"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payout` | object |  | Destination account identifier. |
| ↳ `id` | string |  | Destination account identifier. — Example: `war3999847529816f2` |
| ↳ `phone` | string |  | Telephone of the destination account holder. — Example: `111111111` |
| ↳ `email` | string |  | Destination account holder's email. — Example: `test@test.cl` |
| ↳ `subject` | string |  | Application Status. — Example: `subject order` |
| ↳ `amount` | string |  | Amount to be deposited in the destination account. — Example: `3680` |
| ↳ `accountbank_rut` | string |  | Rut of the destination account holder. — Example: `111111111` |
| ↳ `accountbank_name` | string |  | Name of the destination account holder. — Example: `test` |
| ↳ `accountbank_type` | integer |  | Type of account of the destination bank. — Example: `1` |
| ↳ `accountbank_num` | integer |  | Destination bank account number. — Example: `123123123` |
| ↳ `accountbank_sbif` | string |  | Code of the bank to which the bank account belongs. — Example: `0001` |
| ↳ `status` | string |  | Movement status. - pending ("payout registered") - processing ("payout in payment process") - success ("payout successfully deposited") - banking_error ("payout rejected by the bank") - fraud_prevention ("payout rejected by compliance") — Example: `pending` |
| ↳ `update_at` | string |  | Date the request was made. — Example: `2022-06-09 21:10:46` |
| ↳ `origin_wallet` | string |  | Id de la wallet origen. — Example: `wa1933f37cdaf7d1c6` |
| ↳ `reason_rejection` | string |  | Reason for rejection. — Example: `Error CCA 51. Cuenta Beneficiario no Existe, error_creditor_account_not_found` |

*400* — Request failed.

```json
{
  "status": "failed",
  "type": "Unprocessable Entity",
  "message_error": "subject:invalid,amount:is empty,email:is empty,order:invalid"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Unprocessable Entity` |
| `message_error` | string |  | Error message. — Example: `subject:invalid,amount:is empty,email:is empty,order:invalid` |

*401* — Incorrect public token.

```json
{
  "type": "Unauthorized",
  "message_error": {
    "error": "waiting token public"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string |  | Request status. — Example: `Unauthorized` |
| `message_error` | object |  |  |
| ↳ `error` | string |  | Error message. — Example: `waiting token public` |

*404* — Identifier does not exist.

```json
{
  "status": "failed",
  "type": "Not Found",
  "id": "is not valid"
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Not Found` |
| `id` | string |  | Id information — Example: `is not valid` |

## Banks

Allows viewing the list of associated banks.

### Get list of banks by currency type

`GET /api/banks?currency=ves`

This method allows you to retrieve a list of associated banks filtered by currency.
To filter by currency, add the query parameter `currency` with the currency value.

**CURL**

```text
curl -X GET \
https://BASE-URL/api/banks?currency=ves  \
-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL'
```

**PHP**

```php
$client = new \GuzzleHttp\Client();
  $body = $client->request('GET', 'https://BASE_URL/api/banks?currency=ves', [
  ])->getBody();
$response = json_decode($body);
```

**JS**

```js
const request = async () => {
  const response = await fetch('https://BASE_URL/api/banks?currency=ves', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json'
    },
  });
  const result = await response.json();
  console.log(result)
}
request();
```

**Responses**

*200*

```json
{
  "status": "success",
  "banks": [
    {
      "code": "0102",
      "name": "Banco de Venezuela",
      "currency": "VES"
    }
  ]
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Status of the endpoint. The possible statuses that can be obtained are the following: - success — Example: `success` |
| `banks` | array of objects |  | Example: `[{"code":"0102","name":"Banco de Venezuela","currency":"VES"}]` |
| ↳ `code` | string |  | Bank code of the bank to which the bank account belongs. — Example: `Banco de Venezuela` |
| ↳ `name` | string |  | Name of bank. — Example: `Banco de Venezuela` |
| ↳ `currency` | string |  | Currency — Example: `VES` |

*400* — Request error.

```json
{
  "status": "failed",
  "type": "Unprocessable Entity",
  "message_error": ""
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Unprocessable Entity` |
| `message_error` | string |  | Error message — Example: `` |

## Methods of payment

Allows viewing the list of payment methods used by Payku.

### Get list of payment methods by currency type

`GET /api/paymentmethods?currency=ves`

This method allows you to get a list of payment methods in payku.
To filter by currency, you have to add the query params currency with the currency value.

**CURL**

```text
curl -X GET \
https://BASE-URL/api/paymentmethods?currency=ves  \
-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL' \
```

**PHP**

```php
$client = new \GuzzleHttp\Client();
  $body = $client->request('GET', 'https://BASE_URL/api/paymentmethods?currency=ves', [
  ])->getBody();
$response = json_decode($body);
```

**JS**

```js
const request = async () => {
  const response = await fetch('https://BASE_URL/api/paymentmethods?currency=ves', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json'
    },
  });
  const result = await response.json();
  console.log(result)
}
request();
```

**Responses**

*200*

```json
{
  "status": "success",
  "payment_methods": [
    {
      "currency": "VES",
      "payment": 17,
      "name": "VEPUY",
      "description": "Use your bank, simplify your transfers."
    }
  ]
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Status of the endpoint. The possible statuses that can be obtained are the following: - success — Example: `success` |
| `payment_methods` | array of objects |  | Example: `[{"currency":"VES","payment":17,"name":"VEPUY","description":"Use your bank, simplify your transfers."}]` |
| ↳ `code` | string |  | Code of the bank to which the bank account belongs. — Example: `Banco de Venezuela` |
| ↳ `name` | string |  | Name of bank. — Example: `Banco de Venezuela` |
| ↳ `currency` | string |  | Currency — Example: `VES` |

*400* — Request failed.

```json
{
  "status": "failed",
  "type": "Unprocessable Entity",
  "message_error": ""
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string |  | Request status. — Example: `failed` |
| `type` | string |  | Type of error. — Example: `Unprocessable Entity` |
| `message_error` | string |  | Error message — Example: `` |