openapi: 3.0.0 servers: - url: "https://app.payku.cl/" description: Production - url: "https://des.payku.cl/" description: Sandbox info: description: | ¿Necesitas ver la documentación de los otros países?: Chile | Perú | Venezuela Seleccione el idioma de la documentación: ES | EN
Nuevo: Puedes realizar pruebas en vivo de nuestra API Prueba
# Introducción Bienvenido a la API de payku. Puedes usar nuestra API para acceder a los distintos endpoints de payku, donde podrás generar y gestionar pagos mediante distintos métodos y obtener información de ellos. El API está organizado alrededor de REST. Posee URLs predecibles y orientadas a recursos, y utiliza códigos de respuesta HTTP para indicar el resultado de la llamada. Todas las respuestas de la API retornan objetos JSON, incluyendo los errores. El solicitante debe buscar un código de resultado 200. Si se recibe cualquier código de resultado distinto de 200, la solicitud o la respuesta no es válida, lo que significa que los campos no pasaron los controles de validación de parte de payku. Utilizamos características incluidas en el protocolo HTTP, como autenticación, los cuales son soportados por la gran mayoría de los clientes HTTP. **Importante — ¿Cómo saber si una operación falló?** No te fíes solo del código HTTP (por ejemplo, 200). En nuestra API, muchas respuestas con error también llegan con código HTTP 200. Esto es intencional y forma parte del diseño de la API. Siempre revisa el contenido JSON de la respuesta y busca el campo `status`: - Si `status` es `"success"`, la operación se realizó correctamente. - Si `status` es `"failed"`, hubo un error (por ejemplo, datos inválidos o una operación rechazada). Revisa también el mensaje de error que venga en la misma respuesta. # Autenticación payku utiliza Token Based Authentication sobre HTTPS para la autenticación. Para tener acceso a nuestra API, accede a tu cuenta en la sección de Integración encontrarás la opción de Tokens integración y API. Los request no autenticados o incorrectos retornarán una respuesta de token Invalido. # API Seguridad Cada solicitud es requerido tener incluido en el header: - Authorization: Bearer **TOKEN-PÚBLICO** # Firma En el caso del API de pagos a terceros (payout) se agregó una capa más de seguridad a través de una firma que se envía en el header del request, para obtener dicha firma es necesario lo siguiente: Se debe concatenar en formato para url el Request Path junto a todos los parámetros del request, los cuales deben ser ordenados alfabéticamente por key, tal que key=value. Por lo tanto, si el valor de email cliente es “example@domain.com” el formato correcto sería “example%40domain.com” y luego concatenados con el carácter ‘&’. Una vez que los sets de caracteres son ordenados y concatenados, el hash es calculado usando la función HMAC con cifrado tipo sha256, y el token privado. **Nota:** Si un elemento de la data, tiene como valor un objeto o arreglo, se excluye de la data. Esta función esta en el ejemplo de PHP y de Javascript. ### Ejemplo PHP Endpoint de la API: ```php $request_path = urlencode('/api/suclient'); ``` Ordenando los parámetros: ```php $data = [ 'email' => 'johndoe@example.com', 'name' => 'John 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); ``` Transformación de los parámetros a formato url: ```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++; } } }; ``` Concatenación de los parámetros en formato url con el endpoint de la API: ```php $concat = $request_path.'&'.$concatenar; ``` Firma: ```php $sign = hash_hmac('sha256', $concat, 'fe551abcef62fcf002dc598922e68f0a'); ``` ### Ejemplo JavaScript Importar dependencia CryptoJS: ```javascript const CryptoJS = require("crypto-js"); ``` Endpoint de la API: ```javascript const requestPath = encodeURIComponent('/api/suclient'); ``` Ordenando los parámetros: ```javascript const data = { email: "johndoe@example.com", name: "John 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]; } }); ``` Transformación de los parámetros a formato url: ```javascript const arrayConcat = new URLSearchParams(orderedData).toString(); ``` Concatenación de los parámetros en formato url con el endpoint de la API: ```javascript const concat = requestPath + "&" + arrayConcat; ``` Firma: ```javascript const sign = CryptoJS.HmacSHA256(concat, "fe551abcef62fcf002dc598922e68f0a").toString(); ``` El resultado de la firma obtenida para ambos ejemplos es: ```javascript "c9c86202b1246f6ebeb080d08b3b99a22d36d0e8cffb7fd4e65af0fea4dd12bb" ``` # Errores payku usa respuestas HTTP convencionales para indicar el éxito o fracaso de un request. En general, códigos en el rango de los 2xx indican éxito, códigos en el rango 4xx indican un error que falló debido a la información proporcionada (ej: un parámetro requerido fue omitido, un pago falló, etc.), y códigos en el rango de los 5xx indican un error con los servidores de payku (estos son raros). ## Códigos de error
400

Bad Request

 Hay un problema con tu request
401

Unauthorized

 Tu token es incorrecto o error de firma
403

Forbidden

 No tienes permiso para ver esta página
404

Not Found

 El recurso especificado no fue encontrado
405

Method Not Allowed

 Trataste de ingresar a un recurso con un método inválido
406

Not Acceptable

 Solicitaste un formato que no es json
410

Gone

 El recurso solicitado fue removido de nuestros servidores
422

Unprocessable Entity

 No podemos procesar tu solicitud, revísala.
429

Too Many Requests

 ¡Estás solicitando muchos recursos! ¡Detente!
500

Internal Server Error

 Tuvimos un problema con nuestro servidor. Inténtalo nuevamente más tarde.
503

Service Unavailable

 Estamos offline por mantenimiento. Inténtalo nuevamente más tarde
# Acceso a la API Si tienes una cuenta en payku, puedes acceder a la API REST mediante los siguientes endpoints:
Site BASE URL FOR REST ENDPOINT
Production https://app.payku.cl
Sandbox https://des.payku.cl
- **Producción**: proporciona acceso directo para generar transacciones reales. - **Sandbox**: permite probar su integración sin afectar los datos reales. version: "2.1.01" title: payku API termsOfService: "https://payku.com/legal/" contact: email: contacto@payku.com url: "http://www.apache.org/licenses/LICENSE-2.0.html" license: name: Apache 2.0 url: "http://www.apache.org/licenses/LICENSE-2.0.html" x-logo: url: "https://records.payku.com/public/img/payku2020_2.svg" tags: - name: Bancos description: | Permite ver la lista de los bancos asociados. - name: Métodos de pago description: | Permite ver la lista de los métodos de pago utilizados por payku. x-tagGroups: - name: '' tags: - Transacción - Wallet - name: Herramientas tags: - Bancos - Métodos de pago paths: /api/transaction: post: tags: - Transacción summary: Crear description: | Este método permite crear una orden de pago y recibe como respuesta la **URL** y el **TOKEN** que identifica la transacción. Parámetros adicionales: 1. **additional_parameters** = Permite enviar información adicional que será registrada con la transacción: **IMPORTANTE additional_parameters.gateway:** - Permite especificar el medio de pago final - **OBLIGATORIO** para comercios que usan método On-Site responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionRegisterResponse" "400": description: Error en la solicitud. content: application/json: schema: $ref: "#/components/schemas/Error400" x-codeSamples: - lang: "cURL" source: | 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" } }' - lang: "PHP" source: | $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_PUBLICO' ] ])->getBody(); $response = json_decode($body); - lang: "JS" source: | 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_PUBLICO' }, body: JSON.stringify(data) }); const result = await response.json(); console.log(result) } request(data); requestBody: content: application/json: schema: type: object properties: email: pattern: "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" description: Email del pagador type: string format: email example: "payer@domain.com" minLength: 20 maxLength: 100 nullable: false required: true order: pattern: "^[a-zA-Z0-9- ]{1,40}$" description: Orden del comercio type: string format: uuid example: "order-commerce-999" minLength: 20 maxLength: 40 nullable: false required: true subject: pattern: "^[a-zA-Z0-9 ]{1,200}$" description: Descripción de la orden type: string format: text example: description of the order minLength: 1 maxLength: 200 nullable: false required: true amount: pattern: "^[0-9]+$" description: Monto de la orden type: integer format: int32 example: 100 minValue: 1 maxValue: 4294967295 currency: pattern: "ISO 4217" description: VES type: string format: currency example: "VES" minLength: 3 maxLength: 3 nullable: false required: true payment: pattern: "^[0-9]{1,2}$" description: 17 type: integer format: int32 example: 17 minValue: 1 maxValue: 99 urlreturn: pattern: "^https:\\/\\/([\\w\\-]+\\.)+[\\w\\-]+(\\/[\\w\\-\\.\\/?%&=]*)?$" description: url de retorno del comercio donde se redirigirá al pagador luego de obtener el resultado de la transacción. type: string format: uri example: https://youwebsite.com/return/client/order-commerce-999 minLength: 1 maxLength: 255 urlnotify: pattern: "^https:\\/\\/([\\w\\-]+\\.)+[\\w\\-]+(\\/[\\w\\-\\.\\/?%&=]*)?$" description: | URL callback del comercio donde se notificará el resultado del pago. **Nota:** Una vez que el cliente finalice el proceso de pago, se notificará a la URL de callback (urlnotify) el resultado de la operación bancaria. **Ejemplo de respuesta exitosa:** ```json { "transaction_id": "991...", "payment_key": "trx...", "transaction_key": "991...", "verification_key": "8b3...", "order": "199...", "status": "success" } ``` **Ejemplo de respuesta rechazada:** ```json { "transaction_id": "991...", "payment_key": "trx3...", "transaction_key": "991...", "verification_key": "8b3e...", "order": "199...", "status": "failed" } ``` type: string format: uri additional_parameters: description: | Parámetros adicionales del comercio. type: object properties: gateway: description: | Seleccione el método de pago deseado: | Código | Método | Descripción | On-Site | |---------|--------|------------|--------| | VZLAVECAP2C | Pago Móvil (P2C) | PagoMóvil (Más popular) | SI | | BMIGVECAP2C | Pago Móvil (P2C) | PagoMóvil (Más popular) | | | BMIGVECAC2P | Pago Móvil (C2P) | BancAmiga (Pago instantáneo) | | | BAMRVECAC2P | Pago Móvil (C2P) | Mercantil (Pago instantáneo) | | | UNIOVECAP2C | Banesco | BotónPago (Transferencia) | | | VZLAVECABIO | Tarjetas | BDV BioPago (Débito y Crédito) | | Nota: Para métodos marcados con "On-Site: SI", la respuesta incluirá información adicional: ```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" } } } ``` Campos importantes en la respuesta On-Site: - status: Estado inicial de la transacción - id: Identificador único de la transacción - url: URL para completar el pago, ej. `/api/validonsite` - account_service: Información bancaria para mostrar en el formulario de pago - attributes_request: Datos requeridos para completar el pago type: string example: "CODE" required: - email - order - subject - amount - currency - payment - urlnotify /api/validonsite: post: tags: - Transacción summary: Confirmar On-Site description: | Este método permite confirmar el pago en el sitio web del comercio, enviando información del pagador para que pueda ser verificada. El resultado de la transacción será informado en el callback [urlnotify]. responses: "200": description: Respuesta exitosa content: application/json: schema: type: object properties: transaction: type: string description: Identificador único de la transacción example: "trx24..." status: type: string description: Estado de la transacción example: "register" message: type: string description: Mensaje descriptivo del estado example: "payment received and pending verification" gateway: type: object description: Información del gateway de pago properties: status: type: string description: Estado del gateway example: "successful" required: - transaction - status - message - gateway example: transaction: "trx24..." status: "register" message: "payment received and pending verification" gateway: status: "successful" "400": description: Error en la solicitud content: application/json: schema: type: object properties: transaction: type: string description: Identificador único de la transacción example: "trx24..." status: type: string description: Estado de la transacción example: "failed" message_error: type: string description: Mensaje descriptivo del error example: "charge already used or consumed" required: - transaction - status - message_error example: transaction: "trx24..." status: "failed" message_error: "charge already used or consumed" x-codeSamples: - lang: "cURL" source: | 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" } }' - lang: "PHP" source: | $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); - lang: "JS" source: | 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); requestBody: content: application/json: schema: type: object required: - transaction - payer properties: transaction: type: string description: Identificador único de la transacción example: "trx24..." payer: type: object description: Información del pagador required: - phone_number - payment_reference - id_number - bank_code properties: phone_number: type: string description: Número de teléfono del pagador example: "04129874563" payment_reference: type: string description: Referencia del pago emitido por la entidad bancaria example: "12345600" id_number: type: string description: Número de identificación del pagador example: "V12987456" bank_code: type: string description: Código del banco del pagador example: "0102" payment_date: type: string description: Fecha del pago (opcional) example: "2026-08-25" /api/transaction/{id}: get: tags: - Transacción summary: Obtener description: "Este método permite obtener la información de una transacción" operationId: getTransactionById parameters: - name: id in: path description: | Identificador único de la transacción - id: Identificador de la transacción (Transaccion/POST) required: true schema: type: string pattern: " máximo 40 caracteres" responses: "200": content: application/json: schema: $ref: "#/components/schemas/IdentifierResponse" "400": description: Error en la solicitud. content: application/json: schema: $ref: "#/components/schemas/Error400get" "404": description: Identificador no existe. content: application/json: schema: $ref: "#/components/schemas/Error404" /api/transaction?success=true: get: tags: - Transacción summary: Listar description: | Este método permite obtener la información de las transacciones realizados en payku, permite una paginación con un máximo de 4000 registros por página. | Parámetro | Descripción | Ejemplo | |-----------|-------------|---------| | date_init | Fecha inicial para la búsqueda de transacciones. Si no se especifica, se usa la fecha actual | date_init=2025-01-01 | | date_end | Fecha final para la búsqueda de transacciones. Si no se especifica, se usa la fecha actual | date_end=2025-12-31 | | success | Filtra transacciones exitosas | success=true | | pending | Filtra transacciones pendientes | pending=true | | rejected | Filtra transacciones rechazadas | rejected=true | | page | Número de página para paginación | page=1 | | per_page | Cantidad de registros por página (máximo 4000) | per_page=100 | **Ejemplo de URL completa:** ``` https://[URL_BASE]/api/transaction?date_init=2025-01-01&date_end=2025-12-31&success=true&page=1&per_page=100 ``` operationId: getTransactionList responses: "200": content: application/json: schema: $ref: "#/components/schemas/IdentifierResponse" "400": description: Error en la solicitud. content: application/json: schema: $ref: "#/components/schemas/Error400get" "404": description: Identificador no existe. content: application/json: schema: $ref: "#/components/schemas/Error404" /api/wallet/payout: post: operationId: payout tags: - Wallet summary: Realizar pagos a terceros desde mi wallet description: | Este método permite crear una orden de pago a un tercero utilizando los fondos de tu billetera virtual **payku**. **Nota:** Para fines de prueba (Solo ambiente desarrollo), los montos específicos se procesarán automáticamente:
• Montos 1000, 2000, 3000: Se marcarán como **aprobados** automáticamente.
• Montos 1500, 2500, 3500: Se marcarán como **rechazados** automáticamente. responses: "200": content: application/json: schema: $ref: "#/components/schemas/WalletResponseThird" "400": description: Error en la solicitud. content: application/json: schema: $ref: "#/components/schemas/Error400" x-codeSamples: - lang: "cURL" source: | curl -X POST \ https://BASE-URL/api/wallet/payout \ -H 'Accept: application/json, text/plain, */*' \ -H 'Authorization: Bearer TOKEN-PUBLICO' \ -H 'Sign: SHA256-REQUEST-PATH-VALUE-TOKEN-PRIVADO' \ -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" } }' - lang: "PHP" source: | $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 TOKEN_PUBLICO', 'Sign' => 'SHA256-REQUEST-PATH-VALUE-TOKEN-PRIVADO' ] ])->getBody(); $response = json_decode($body); - lang: "JS" source: | 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 TOKEN_PUBLICO', 'Sign': 'SHA256-REQUEST-PATH-VALUE-TOKEN-PRIVADO' }, body: JSON.stringify(data) }); const result = await response.json(); console.log(result) } request(data); requestBody: content: application/json: schema: type: object properties: email: pattern: " máximo 50 caracteres" description: Email del usuario type: string format: email example: "payer@domain.com" phone: pattern: " máximo 20 caracteres" description: Télefono del usuario type: string example: "04149876543" subject: pattern: " máximo 200 caracteres" description: Descripción de la orden type: string example: description of the order currency: pattern: " máximo 6 caracteres" description: Tipo de moneda (Formato ISO) type: string example: "VES" order: pattern: " máximo 50 caracteres" description: Orden del comercio type: string example: "order-commerce-999" amount: pattern: " máximo 14 dígitos" description: Monto de la orden type: integer example: 1000 accountbank_name: pattern: " máximo 180 caracteres" description: Nombre del titular de la cuenta type: string example: John Doe accountbank_rut: pattern: " máximo 15 caracteres" description: | Cédula de identidad del titular Formato: (V/E/J) VXXXXXXXX type: string example: "V23654789" accountbank_sbif: pattern: " máximo 4 caracteres" description: | Código del banco al que pertenece la cuenta bancaria. - 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 type: string example: "0102" accountbank_type: pattern: " máximo 1 caracter" description: | Tipo de cuenta. - 1 Corriente - 3 Ahorro type: string example: "1" accountbank_num: pattern: " máximo 200 caracteres" description: | Número de cuenta del cliente en Venezuela Formato: (0412 / 0414 / 0424 / 0426 / 0416) 9876543 type: string example: "04149876543" url_notify: pattern: " máximo 600 caracteres" description: | Callback donde se notificará el resultado del pago. - Nota: Luego de realizar el pago a terceros payku respondera de forma automática al endpoint ingresado en urlnotify el resultado de la operación. - **Ejemplo Aprobado:** - { - "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" - } - } - **Ejemplo Rechazado:** - { - "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" - } - } type: string example: "https://youwebsite.com/callback/commerce/order-commerce-999" additional_parameters: pattern: " máximo 4000 caracteres" description: Parámetros adicionales del cliente (Opcional). type: object properties: parameter_1: description: Nombre del parámetro dado por el usuario payku type: string example: "keyValue" parameter_2: description: Nombre del parámetro dado por el usuario payku type: string example: "keyValue" required: - email - subject - currency - order - amount - accountbank_name - accountbank_rut - accountbank_sbif - accountbank_type - accountbank_num /api/banks?currency=ves: get: tags: - Bancos summary: "Obtener lista de bancos por el tipo de moneda" description: | Este método permite obtener una lista de los bancos asociados filtrados por la moneda. Para filtrar por la moneda, hay que agregar el query params currency con el valor de la moneda. responses: "200": content: application/json: schema: $ref: "#/components/schemas/BanksCurrencyResponse" "400": description: Error en la solicitud. content: application/json: schema: $ref: "#/components/schemas/ErrorBanks400get" x-codeSamples: - lang: "CURL" source: | 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' \ - lang: "PHP" source: | $client = new \GuzzleHttp\Client(); $body = $client->request('GET', 'https://BASE_URL/api/banks?currency=ves', [ ])->getBody(); $response = json_decode($body); - lang: "JS" source: | 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(); /api/paymentmethods?currency=ves: get: tags: - Métodos de pago summary: "Obtener lista de métodos de pago por el tipo de moneda" description: | Este método permite obtener una lista de los métodos de pago en payku. Para filtrar por la moneda, hay que agregar el query params currency con el valor de la moneda. responses: "200": content: application/json: schema: $ref: "#/components/schemas/MethodsPaymentCurrencyResponse" "400": description: Error en la solicitud. content: application/json: schema: $ref: "#/components/schemas/ErrorBanks400get" x-codeSamples: - lang: "CURL" source: | 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' \ - lang: "PHP" source: | $client = new \GuzzleHttp\Client(); $body = $client->request('GET', 'https://BASE_URL/api/paymentmethods?currency=ves', [ ])->getBody(); $response = json_decode($body); - lang: "JS" source: | 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(); /api/payoutv3/{identificadorPayout}: get: tags: - Wallet summary: "Obtener payout V3" description: | Este método permite obtener un movimiento de pagos a terceros de su billetera virtual **payku** mediante un identificador: Para realizar la consulta es necesario agregar al final del endpoint lo siguiente /{identificadorPayout} como por ejemplo: **api/payoutv3/wa24bg36767**. responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayoutResponseGetv3" "400": description: Error en la solicitud. content: application/json: schema: $ref: "#/components/schemas/Error400get" "404": description: Identificador no existe. content: application/json: schema: $ref: "#/components/schemas/Error404" x-codeSamples: - lang: "CURL" source: | curl -X GET \ https://BASE-URL/api/payoutv3/{identificadorPayout} \ -H 'Accept: application/json, text/plain, */*' \ -H 'Authorization: Bearer TOKEN-PUBLICO' \ -H 'Sign: SHA256-REQUEST-PATH-VALUE-TOKEN-PRIVADO' \ -H 'Content-Type: application/json' \ -H 'Host: BASE-URL' \ - lang: "PHP" source: | $client = new \GuzzleHttp\Client(); $body = $client->request('GET', 'https://BASE_URL/api/payoutv3/{identificadorPayout}', [ 'headers' => [ 'Authorization' => 'Bearer TOKEN_PUBLICO', 'Sign' => 'SHA256-REQUEST-PATH-VALUE-TOKEN-PRIVADO' ] ])->getBody(); $response = json_decode($body); - lang: "JS" source: | const request = async () => { const response = await fetch('https://BASE_URL/api/payoutv3/{identificadorPayout}', { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer TOKEN-PUBLICO', 'Sign': 'SHA256-REQUEST-PATH-VALUE-TOKEN-PRIVADO' }, }); const result = await response.json(); console.log(result) } request(); components: schemas: BanksResponse: description: "Datos de retorno de la creación de la lista de bancos" type: object properties: status: type: string description: | Estatus del endpoint. Los posibles estados que puede obtener son los siguientes: - success example: "success" banks: type: array items: description: "Datos de retorno de la lista de bancos" type: object properties: code: type: string description: | Código del banco al que pertenece la cuenta bancaria. example: Banco de Venezuela name: type: string description: Nombre de la entidad bancaria. example: Banco de Venezuela currency: type: string description: Moneda example: VES example: - { code: "0102", name: "Banco de Venezuela", currency: "VES" } BanksCurrencyResponse: description: "Datos de retorno de la lista de bancos" type: object properties: status: type: string description: | Estatus del endpoint. Los posibles estados que puede obtener son los siguientes: - success example: "success" banks: type: array items: description: "Datos de retorno de estado de la lista de bancos" type: object properties: code: type: string description: | Código del banco al que pertenece la cuenta bancaria. example: Banco de Venezuela name: type: string description: Nombre de la entidad bancaria. example: Banco de Venezuela currency: type: string description: Moneda example: VES example: - { code: "0102", name: "Banco de Venezuela", currency: "VES" } MethodsPaymentCurrencyResponse: description: "Datos de retorno de la creación de la lista de métodos de pago" type: object properties: status: type: string description: | Estatus del endpoint. Los posibles estados que puede obtener son los siguientes: - success example: "success" payment_methods: type: array items: description: "Datos de retorno de estado de la lista de métodos de pago" type: object properties: code: type: string description: | Código del banco al que pertenece la cuenta bancaria. example: Banco de Venezuela name: type: string description: Nombre de la entidad bancaria. example: Banco de Venezuela currency: type: string description: Moneda example: VES example: - { currency: "VES", payment: 17, name: "Vepuy", description: "Utiliza tu banco, simplifica tus transferencias." } TransactionResponse: description: "Datos de retorno de la creación de una transacción" type: object properties: status: type: string description: | Estatus de transacción.Los posibles estados que puede obtener son los siguientes: - pending - success - rejected example: "pending" id: type: string description: Identificador único de la transacción example: "trx3..." url: type: string description: URL a redireccionar al usuario. example: "https://BASE_URL/url_de_pago" TransactionRegisterResponse: type: object properties: status: type: string description: | Estatus de transacción. Los posibles estados que puede obtener son los siguientes: - register - success example: "register" id: type: string description: Identificador único de la transacción example: "trx6..." url: type: string description: URL para redireccionar al usuario. example: "https://[BASE_URL]/path?id=trx...&valid=e3c4..." account_service: type: object description: "**[!SOLO PARA MÉTODOS ON-SITE!]** Información del servicio bancario que debe ser utilizado para el pago." properties: bank_method: type: string description: Método de pago bancario example: "PA.." bank_number: type: string description: Número de teléfono para pago móvil example: "04..." bank_document: type: string description: Documento de identificación bancaria example: "J..." bank_name: type: string description: Nombre completo del banco example: "Ban..." bank_nameshort: type: string description: Nombre corto del banco example: "Ve..." bank_code: type: string description: Código del banco example: "01..." bank_linkqr: type: string description: URL del código QR para el pago example: "ht..." attributes_request: type: object description: "**[!SOLO PARA MÉTODOS ON-SITE!]** Datos requeridos para completar para informar el pago." properties: transaction: type: string description: Identificador de la transacción example: "tr..." payer: type: object description: Información requerida del pagador properties: phone_number: type: string description: Número de teléfono del pagador payment_reference: type: string description: Referencia del pago example: "required" IdentifierResponse: description: "Datos de retorno de estado de una transacción" type: object properties: status: type: string description: | Estatus de transacción.Los posibles estados que puede obtener son los siguientes: - register - pending - success - rejected example: "success" id: type: string description: Identificador único de la transacción example: "trx3b..." created_at: type: string description: Fecha de registro. example: "2025-10-25 14:10:03" order: type: string description: Número de orden. example: "157..." email: type: string description: Email del usuario example: "payer@domain.com" subject: type: string description: Descripción de la orden de compra. example: "description of the order" amount: type: string description: Monto. example: 100 payment: type: object properties: start: type: string description: Inicio de la transacción. example: "2025-12-16 15:10:33" end: type: string description: Fin de la transacción. example: "2025-12-16 15:10:36" media: type: string description: Medio de pago, utilizado por el usuario. example: "VEPUY" transaction_id: type: int description: Identificador único de la transacción example: 107999 payment_key: type: string description: Identificador del cobro creado por payku. example: "pr..." transaction_key: type: string description: Identificador único de la transacción example: null deposit_date: type: string description: Fecha el cual se realizará el depósito al cliente. example: "2023-10-05" verification_key: type: string description: Código de verificación creado por payku. example: "666..." authorization_code: type: string description: Código de autorización. example: "10..." last_4_digits: type: string description: Últimos 4 dígitos de la tarjeta afiliada. example: "0000" installments: type: int description: Cuotas. example: 0 card_type: type: string description: Tipo de tarjeta. example: "VN" additional_parameters: type: object description: | **Ejemplo** de parámetros adicionales que puede enviar payku. properties: gateway: type: string description: "" example: "CODE_GATEWAY" network: type: object description: | Datos de la red del usuario: properties: ip_address: type: string description: | **Ejemplo** de IP Address del usuario: example: "192.0.2.123" currency: type: string description: Moneda. example: "VES" nullify: description: "Objeto que contiene información de la respuesta de la anulación" type: object properties: status: type: string description: | 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: description: "Objeto que contiene información de la respuesta de la transacción" type: object properties: status: type: string description: | Estatus de transacción.Los posibles estados que puede obtener son los siguientes: - pending - success - rejected - refunded partial - refunded example: "success" message: type: string description: | Mensaje que describe el estado. - successful transaction - Rechazo de transacción. - Transacción debe reintentarse. - Error en transacción. - Rechazo por error de tasa. - Excede cupo máximo mensual. - Excede límite diario por transacción. - Rubro no autorizado. example: "successful transaction" Error: type: object properties: status: type: string description: Estatus de la solicitud. example: failed type: type: string description: Tipo de error ocurrido. example: Unprocessable Entity message_error: type: string description: Mensaje de error example: subject:invalid,amount:is empty,email:is empty,order:invalid Error400: type: object properties: status: type: string description: Estatus de la solicitud. example: failed type: type: string description: Tipo de error ocurrido. example: Unprocessable Entity message_error: type: string description: Mensaje de error example: subject:invalid,amount:is empty,email:is empty,order:invalid Error400get: type: object properties: status: type: string description: Estatus de la solicitud. example: failed type: type: string description: Tipo de error ocurrido. example: Unprocessable Entity message_error: type: string description: Mensaje de error example: subject:invalid,amount:is empty,email:is empty,order:invalid ErrorBanks400get: type: object properties: status: type: string description: Estatus de la solicitud. example: failed type: type: string description: Tipo de error ocurrido. example: Unprocessable Entity message_error: type: string description: Mensaje de error example: "Hay un problema con tu request" Error404: type: object properties: status: type: string description: Estatus de la solicitud. example: failed type: type: string description: Tipo de error ocurrido. example: Not Found id: type: string description: Información de id example: is not valid WalletResponseThird: description: "Datos de retorno de la carga a la wallet" type: object properties: status: type: string description: | Estado de la carga a la wallet. Los posibles estados son: - success: exitosa - failed: fallida example: "success" identifier_wallet: type: string description: Identificador del movimiento de la billetera virtual de payku. example: "wvb5f7232dafff18f9" identifier_payout: type: string description: Identificador del pago a tercero. example: "mv40746ab8eff910f41e" PayoutResponseGetv3: description: "Datos de retorno de la carga del payout" type: object properties: payout: type: object description: Datos cuenta destino. properties: id: type: string description: Identificador de la cuenta destino. example: "war3999847529816f2" phone: type: string description: Teléfono del titular de cuenta destino. example: "111111111" email: type: string description: Correo del titular de cuenta destino. example: "test@test.com" subject: type: string description: Estatus de la solicitud. example: "subject order" amount: type: string description: Monto a depositado en la cuenta destino. example: "3680" accountbank_rut: type: string description: Rut del titular de la cuenta destino. example: "V23654789" accountbank_name: type: string description: Nombre del titular de la cuenta destino. example: "test" accountbank_type: type: integer description: Tipo de cuenta del banco destino. example: 1 accountbank_num: type: integer description: Número de cuenta del banco destino. example: 123123123 accountbank_sbif: type: string description: Código del banco al que pertenece la cuenta bancaria. example: "0102" status: type: string description: | Estatus del movimiento. - pending ("payout registrado") - processing ("payout en proceso de pago") - success ("payout depositado exitosamente") - banking_error ("payout rechazado por el banco") - fraud_prevention ("payout rechazado por compliance") example: "pending" update_at: type: string description: Fecha que se realizo la solicitud. example: "2023-06-09 21:10:46" origin_wallet: type: string description: Id de la wallet origen. example: "wa1933f37cdaf7d1c6" reason_rejection: type: string description: Motivo del rechazo. example: " Error CCA 51. Cuenta Beneficiario no Existe, error_creditor_account_not_found"