Transacción

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

Crear

POST/api/transaction

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

Cuerpo de la solicitud

Parámetro	Tipo	Descripción
emailrequerido	string <email>	Email del pagador ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ [ 20 .. 100 ] caracteres Ejemplo: [email protected]
orderrequerido	string <uuid>	Orden del comercio ^[a-zA-Z0-9- ]{1,40}$ [ 20 .. 40 ] caracteres Ejemplo: order-commerce-999
subjectrequerido	string <text>	Descripción de la orden ^[a-zA-Z0-9 ]{1,200}$ [ 1 .. 200 ] caracteres Ejemplo: description of the order
amountrequerido	integer <int32>	Monto de la orden ^[0-9]+$ Ejemplo: 100
currencyrequerido	string <currency>	VES ISO 4217 [ 3 .. 3 ] caracteres Ejemplo: VES
paymentrequerido	integer <int32>	17 ^[0-9]{1,2}$ Ejemplo: 17
urlreturn	string <uri>	url de retorno del comercio donde se redirigirá al pagador luego de obtener el resultado de la transacción. ^https:\/\/([\w\-]+\.)+[\w\-]+(\/[\w\-\.\/?%&=]*)?$ [ 1 .. 255 ] caracteres Ejemplo: https://youwebsite.com/return/client/order-commerce-999
urlnotifyrequerido	string <uri>	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: { "transaction_id": "991...", "payment_key": "trx...", "transaction_key": "991...", "verification_key": "8b3...", "order": "199...", "status": "success" } Ejemplo de respuesta rechazada: { "transaction_id": "991...", "payment_key": "trx3...", "transaction_key": "991...", "verification_key": "8b3e...", "order": "199...", "status": "failed" } ^https:\/\/([\w\-]+\.)+[\w\-]+(\/[\w\-\.\/?%&=]*)?$
additional_parameters	object	Parámetros adicionales del comercio.
gateway	string	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: { "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 Ejemplo: CODE

cURL

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": "[email protected]",
  "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

$client = new \GuzzleHttp\Client();
  $body = $client->request('POST', 'https://BASE_URL/api/transaction', [
    'json' => [
      'email' => '[email protected]',
      '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);

JS

const data = {
  "email": "[email protected]",
  "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);

Respuestas

200

200

{
  "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"
    }
  }
}

Campos de la respuesta

Parámetro	Tipo	Descripción
status	string	Estatus de transacción. Los posibles estados que puede obtener son los siguientes: register success Ejemplo: register
id	string	Identificador único de la transacción Ejemplo: trx6...
url	string	URL para redireccionar al usuario. Ejemplo: https://[BASE_URL]/path?id=trx...&valid=e3c4...
account_service	object	[!SOLO PARA MÉTODOS ON-SITE!] Información del servicio bancario que debe ser utilizado para el pago.
bank_method	string	Método de pago bancario Ejemplo: PA..
bank_number	string	Número de teléfono para pago móvil Ejemplo: 04...
bank_document	string	Documento de identificación bancaria Ejemplo: J...
bank_name	string	Nombre completo del banco Ejemplo: Ban...
bank_nameshort	string	Nombre corto del banco Ejemplo: Ve...
bank_code	string	Código del banco Ejemplo: 01...
bank_linkqr	string	URL del código QR para el pago Ejemplo: ht...
attributes_request	object	[!SOLO PARA MÉTODOS ON-SITE!] Datos requeridos para completar para informar el pago.
transaction	string	Identificador de la transacción Ejemplo: tr...
payer	object	Información requerida del pagador
phone_number	string	Número de teléfono del pagador
payment_reference	string	Referencia del pago Ejemplo: required

400

400

Error en la solicitud.

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

Campos de la respuesta

Parámetro	Tipo	Descripción
status	string	Estatus de la solicitud. Ejemplo: failed
type	string	Tipo de error ocurrido. Ejemplo: Unprocessable Entity
message_error	string	Mensaje de error Ejemplo: subject:invalid,amount:is empty,email:is empty,order:invalid

Confirmar On-Site

POST/api/validonsite

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].

Cuerpo de la solicitud

Parámetro	Tipo	Descripción
transactionrequerido	string	Identificador único de la transacción Ejemplo: trx24...
payerrequerido	object	Información del pagador
phone_numberrequerido	string	Número de teléfono del pagador Ejemplo: 04129874563
payment_referencerequerido	string	Referencia del pago emitido por la entidad bancaria Ejemplo: 12345600
id_numberrequerido	string	Número de identificación del pagador Ejemplo: V12987456
bank_coderequerido	string	Código del banco del pagador Ejemplo: 0102
payment_date	string	Fecha del pago (opcional) Ejemplo: 2026-08-25

cURL

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

$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

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);

Respuestas

200

200

Respuesta exitosa

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

Campos de la respuesta

Parámetro	Tipo	Descripción
transactionrequerido	string	Identificador único de la transacción Ejemplo: trx24...
statusrequerido	string	Estado de la transacción Ejemplo: register
messagerequerido	string	Mensaje descriptivo del estado Ejemplo: payment received and pending verification
gatewayrequerido	object	Información del gateway de pago
status	string	Estado del gateway Ejemplo: successful

400

400

Error en la solicitud

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

Campos de la respuesta

Parámetro	Tipo	Descripción
transactionrequerido	string	Identificador único de la transacción Ejemplo: trx24...
statusrequerido	string	Estado de la transacción Ejemplo: failed
message_errorrequerido	string	Mensaje descriptivo del error Ejemplo: charge already used or consumed

Obtener

GET/api/transaction/{id}

Este método permite obtener la información de una transacción

Parámetros de ruta

Parámetro	Tipo	Descripción
idrequerido	string	Identificador único de la transacción id: Identificador de la transacción (Transaccion/POST) máximo 40 caracteres

Respuestas

200

200

{
  "status": "success",
  "id": "trx3b...",
  "created_at": "2025-10-25 14:10:03",
  "order": "157...",
  "email": "[email protected]",
  "subject": "description of the order",
  "amount": 100,
  "payment": {
    "start": "2025-12-16 15:10:33",
    "end": "2025-12-16 15:10:36",
    "media": "VEPUY",
    "transaction_id": 107999,
    "payment_key": "pr...",
    "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"
  }
}

Campos de la respuesta

Parámetro	Tipo	Descripción
status	string	Estatus de transacción.Los posibles estados que puede obtener son los siguientes: register pending success rejected Ejemplo: success
id	string	Identificador único de la transacción Ejemplo: trx3b...
created_at	string	Fecha de registro. Ejemplo: 2025-10-25 14:10:03
order	string	Número de orden. Ejemplo: 157...
email	string	Email del usuario Ejemplo: [email protected]
subject	string	Descripción de la orden de compra. Ejemplo: description of the order
amount	string	Monto. Ejemplo: 100
payment	object
start	string	Inicio de la transacción. Ejemplo: 2025-12-16 15:10:33
end	string	Fin de la transacción. Ejemplo: 2025-12-16 15:10:36
media	string	Medio de pago, utilizado por el usuario. Ejemplo: VEPUY
transaction_id	int	Identificador único de la transacción Ejemplo: 107999
payment_key	string	Identificador del cobro creado por payku. Ejemplo: pr...
transaction_key	string	Identificador único de la transacción
deposit_date	string	Fecha el cual se realizará el depósito al cliente. Ejemplo: 2023-10-05
verification_key	string	Código de verificación creado por payku. Ejemplo: 666...
authorization_code	string	Código de autorización. Ejemplo: 10...
last_4_digits	string	Últimos 4 dígitos de la tarjeta afiliada. Ejemplo: 0000
installments	int	Cuotas. Ejemplo: 0
card_type	string	Tipo de tarjeta. Ejemplo: VN
additional_parameters	object	Ejemplo de parámetros adicionales que puede enviar payku.
gateway	string	Ejemplo: CODE_GATEWAY
network	object	Datos de la red del usuario:
ip_address	string	Ejemplo de IP Address del usuario: Ejemplo: 192.0.2.123
currency	string	Moneda. Ejemplo: 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 Ejemplo: complete
gateway_response	object	Objeto que contiene información de la respuesta de la transacción
status	string	Estatus de transacción.Los posibles estados que puede obtener son los siguientes: pending success rejected refunded partial refunded Ejemplo: success
message	string	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. Ejemplo: successful transaction

400

400

Error en la solicitud.

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

Campos de la respuesta

Parámetro	Tipo	Descripción
status	string	Estatus de la solicitud. Ejemplo: failed
type	string	Tipo de error ocurrido. Ejemplo: Unprocessable Entity
message_error	string	Mensaje de error Ejemplo: subject:invalid,amount:is empty,email:is empty,order:invalid

404

404

Identificador no existe.

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

Campos de la respuesta

Parámetro	Tipo	Descripción
status	string	Estatus de la solicitud. Ejemplo: failed
type	string	Tipo de error ocurrido. Ejemplo: Not Found
id	string	Información de id Ejemplo: is not valid

Listar

GET/api/transaction?success=true

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

Respuestas

200

200

{
  "status": "success",
  "id": "trx3b...",
  "created_at": "2025-10-25 14:10:03",
  "order": "157...",
  "email": "[email protected]",
  "subject": "description of the order",
  "amount": 100,
  "payment": {
    "start": "2025-12-16 15:10:33",
    "end": "2025-12-16 15:10:36",
    "media": "VEPUY",
    "transaction_id": 107999,
    "payment_key": "pr...",
    "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"
  }
}

Campos de la respuesta

Parámetro	Tipo	Descripción
status	string	Estatus de transacción.Los posibles estados que puede obtener son los siguientes: register pending success rejected Ejemplo: success
id	string	Identificador único de la transacción Ejemplo: trx3b...
created_at	string	Fecha de registro. Ejemplo: 2025-10-25 14:10:03
order	string	Número de orden. Ejemplo: 157...
email	string	Email del usuario Ejemplo: [email protected]
subject	string	Descripción de la orden de compra. Ejemplo: description of the order
amount	string	Monto. Ejemplo: 100
payment	object
start	string	Inicio de la transacción. Ejemplo: 2025-12-16 15:10:33
end	string	Fin de la transacción. Ejemplo: 2025-12-16 15:10:36
media	string	Medio de pago, utilizado por el usuario. Ejemplo: VEPUY
transaction_id	int	Identificador único de la transacción Ejemplo: 107999
payment_key	string	Identificador del cobro creado por payku. Ejemplo: pr...
transaction_key	string	Identificador único de la transacción
deposit_date	string	Fecha el cual se realizará el depósito al cliente. Ejemplo: 2023-10-05
verification_key	string	Código de verificación creado por payku. Ejemplo: 666...
authorization_code	string	Código de autorización. Ejemplo: 10...
last_4_digits	string	Últimos 4 dígitos de la tarjeta afiliada. Ejemplo: 0000
installments	int	Cuotas. Ejemplo: 0
card_type	string	Tipo de tarjeta. Ejemplo: VN
additional_parameters	object	Ejemplo de parámetros adicionales que puede enviar payku.
gateway	string	Ejemplo: CODE_GATEWAY
network	object	Datos de la red del usuario:
ip_address	string	Ejemplo de IP Address del usuario: Ejemplo: 192.0.2.123
currency	string	Moneda. Ejemplo: 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 Ejemplo: complete
gateway_response	object	Objeto que contiene información de la respuesta de la transacción
status	string	Estatus de transacción.Los posibles estados que puede obtener son los siguientes: pending success rejected refunded partial refunded Ejemplo: success
message	string	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. Ejemplo: successful transaction

400

400

Error en la solicitud.

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

Campos de la respuesta

Parámetro	Tipo	Descripción
status	string	Estatus de la solicitud. Ejemplo: failed
type	string	Tipo de error ocurrido. Ejemplo: Unprocessable Entity
message_error	string	Mensaje de error Ejemplo: subject:invalid,amount:is empty,email:is empty,order:invalid

404

404

Identificador no existe.

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

Campos de la respuesta

Parámetro	Tipo	Descripción
status	string	Estatus de la solicitud. Ejemplo: failed
type	string	Tipo de error ocurrido. Ejemplo: Not Found
id	string	Información de id Ejemplo: is not valid