Transacción

Permite la creación de transacciones y posteriormente consultar su estado.

Ver diagrama

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

Crear transacción

POST/api/transaction

Este método permite crear una orden de pago a payku y recibe como respuesta la URL para redirigir el browser del pagador y el token que identifica la transacción. Una vez que el pagador efectúe el pago exitoso, payku notificará el resultado a la página del comercio que se envió en el parámetro urlnotify.

additional_parameters = permite enviar información adicional para ser registrada en payku asociada a la transacción order_ext dentro de additional_parameters, es una palabra reservada, y es útil para asociar la transacción a un identificador único del comercio

Cuerpo de la solicitud

Parámetro	Tipo	Descripción
emailrequerido	string <email>	Email del usuario máximo 100 caracteres Ejemplo: [email protected]
orderrequerido	string	Orden del comercio máximo 40 caracteres Ejemplo: 987450011
subjectrequerido	string	Descripción de la orden máximo 2000 caracteres Ejemplo: test subject
amountrequerido	float	Monto de la orden. Importante: si el monto incluye decimales, debe enviarse como texto entre comillas (por ejemplo, "150.50" en vez de 150.50). máximo 14 dígitos Ejemplo: 150.50
currency	string	Moneda. máximo 6 caracteres Ejemplo: PEN
payment	integer	Identificador del medio de pago. Si se envía el identificador, el pagador será redireccionado directamente al medio de pago que se indique. 21 QR Interoperable (Yape, Plin y Otros; Moneda PEN) 25 Débito, Crédito, Mastercard, Visa y Diners Club máximo 2 caracteres Ejemplo: 21
expired	string	Fecha en la cual expira la transacción Este campo no es requerido. Formato permitido (Año-mes-día hora:minuto:segundo) Ejemplo: 2023-10-18 23:59:59 En caso de ser enviado, debe cumplir con las siguiente reglas: - Debe ser mayor a 5 minutos de la fecha actual (hora Santiago). - Se requiere urlreturn, se adjuntará como parámetros GET /?message_error=expired&id=trx60dc327d9e4c094 Ejemplo: 2023-10-19 13:05:10
urlreturn	string <url>	url de retorno del comercio donde payku redirigirá al pagador luego de 3 segundos de obtener el resultado de la transacción. máximo 200 caracteres Ejemplo: https://youwebsite.com/urlreturn?orderClient=98745
urlnotify	string <url>	url callback del comercio donde payku notificara el pago. Nota: Luego de que el cliente finalice el proceso de pago en su entidad bancaria payku respondera de forma automática al endpoint ingresado en urlnotify el resultado de la operación bancaria. Ejemplo Aprobado: { "transaction_id": "9916587765599311", "payment_key" : "trx32cb779c0a777fc68", "transaction_key" : "9916581777599311", "verification_key": "8b3e2202fb086a7de93777ae34d5e18c", "order": "199", "status": "success" } Ejemplo Rechazado: { "transaction_id": "9916587765599311", "payment_key" : "trx32cb779c0a777fc68", "transaction_key" : "9916581777599311", "verification_key": "8b3e2202fb086a7de93777ae34d5e18c", "order": "199", "status": "failed" } máximo 600 caracteres Ejemplo: https://www.youwebsite.com/urlnotify?orderClient=98745
additional_parameters	object	Parámetros adicionales del cliente (Opcional). máximo 4000 caracteres
parameters1	string	Nombre del parámetro dado por el usuario payku Ejemplo: keyValue
parameters2	string	Nombre del parámetro dado por el usuario payku Ejemplo: keyValue
order_ext	string	Identificador único proporcionado por el comercio, que permita a asociar la transacción a un identificador externo Ejemplo: fff-777

cURL

curl -X POST \
https://BASE-URL/api/transaction \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer TOKEN-PUBLICO' \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL' \
-d '{
  "email": "[email protected]",
  "order": "987450011",
  "subject": "test subject",
  "amount": "150.50",
  "currency": "PEN",
  "payment": 21,
  "expired": "2023-10-19 13:05:10",
  "urlreturn": "https://youwebsite.com/urlreturn?orderClient=98745",
  "urlnotify": "https://www.youwebsite.com/urlnotify?orderClient=98745",
  "additional_parameters": {
    "parameters1": "keyValue",
    "parameters2": "keyValue",
    "order_ext": "fff-777"
  }
}'

PHP

$client = new \GuzzleHttp\Client();
  $body = $client->request('POST', 'https://BASE_URL/api/transaction', [
    'json' => [
      'email' => '[email protected]',
      'order' => "987450011",
      'subject' => 'test subject',
      'amount' => '150.50',
      'currency'=> "PEN",
      'payment' => 21,
      'expired' => '2022-10-19 13:05:10',
      'urlreturn' => 'https://youwebsite.com/urlreturn?orderClient=123',
      'urlnotify' => 'https://youwebsite.com/urlnotify?orderClient=123',
        'additional_parameters' => [
          'parameters1'=>'keyValue',
          'parameters2'=>'keyValue2',
          'order_ext'=>'fff-777'
        ]
      ],
    'headers' => [
      'Authorization' => 'Bearer PUBLIC-TOKEN'
    ]
  ])->getBody();
$response = json_decode($body);

JS

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

let data = {
  email: "[email protected]",
  order: "987450011",
  subject: "test subject",
  amount: "150.50",
  currency: "PEN",
  payment: 21,
  expired: "2022-10-19 13:05:10",
  urlreturn: "https://youwebsite.com/urlreturn?orderClient=123",
  urlnotify: "https://youwebsite.com/urlnotify?orderClient=123",
  additional_parameters: {
    parameters1:"keyValue",
    parameters2:"keyValue2",
    order_ext:"fff-777"
  }
};

request(data);

Respuestas

200

200

{
  "status": "pending",
  "id": "trx3b4d77b43acd9a720",
  "url": "https://BASE_URL/url_de_pago",
  "hash": "00020000000000000111111222233339030226304E245",
  "qr_image": "data:image/png;base64,......"
}

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: pending
id	string	Identificador de la transacción creado por payku. Ejemplo: trx3b4d77b43acd9a720
url	string	URL a redireccionar al usuario. Ejemplo: https://BASE_URL/url_de_pago
hash	string	Hash de la transacción para generar el QR. Ejemplo: 00020000000000000111111222233339030226304E245
qr_image	string	Imagen del QR. Ejemplo: data:image/png;base64,......

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

401

401

Token Público incorrecto.

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

Campos de la respuesta

Parámetro	Tipo	Descripción
type	string	Tipo de error ocurrido. Ejemplo: Unauthorized
message_error	object
error	string	Mensaje de error Ejemplo: waiting token public

Obtener múltiples transacciones

GET/api/transaction

Este método permite obtener la información de las transacciones realizados en payku, este método permite una paginación con un máximo de 4000 registros por página, además, posee los siguientes filtros:

• date_init: indica la fecha desde donde se desea comenzar la búsqueda de transacciones, si este parámetro no es enviado la busqueda iniciara la fecha actual .
• date_end: indica la fecha donde se desea que termine la búsqueda de transacciones, si este parámetro no es enviado la busque tendrá como fecha final la fecha actual.
• estatus: se puede filtrar la búsqueda de las transacciones dependiendo del estatus en la que se encuentra. por ejemplo. /api/transaction?success=true ó para traer multiples estatus /api/transaction?pending=true&rejected=true.

para la paginación es necesario agregar al final del endpoint lo siguiente ?page=1&per_page=100 siendo el primer parámetro el número de la página y el segundo el número de registros por página. En caso de querer buscar las transacciones entre las fechas 01-09-2021 y 15-09-2021, además que solo sean las transacciones de estado success, la url a utilizar seria la siguiente: https://[URL_BASE]/api/transaction?date_init=2021-09-01&date_end=2021-09-15&success=true.

CURL

curl -X GET \
https://BASE-URL/api/transaction  \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer TOKEN-PUBLICO' \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL' \

PHP

$client = new \GuzzleHttp\Client();
  $body = $client->request('GET', 'https://BASE_URL/api/transaction', [
    'headers' => [
      'Authorization' => 'Bearer TOKEN_PUBLICO'
    ]
  ])->getBody();
$response = json_decode($body);

JS

const request = async () => {
  const response = await fetch('https://BASE_URL/api/transaction', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer TOKEN-PUBLICO'
    },
  });
  const result = await response.json();
  console.log(result)
}

request();

Respuestas

200

200

{
  "transaction": [
    {
      "id": "107999",
      "status": "success",
      "created_at": "2019-10-25 14:10:03",
      "email": "[email protected]",
      "amount": 98745,
      "order": "1572023402",
      "subject": "Description",
      "payment": {
        "start": "2023-12-16 15:10:33",
        "end": "2023-12-16 15:10:36",
        "media": "QR Interoperable",
        "transaction_id": 107999,
        "payment_key": "pra934939d607922f9e",
        "transaction_key": null,
        "deposit_date": "2023-10-05",
        "verification_key": "6669cbd982ef54c28f2f15fb9dc5262d",
        "authorization_code": "107742",
        "last_4_digits": "1233",
        "installments": 0,
        "card_type": "VN",
        "additional_parameters": {
          "identificador": "11.111.111-1",
          "banco": "Banco Estado",
          "numero_cuenta": "00126544977"
        },
        "currency": "PEN"
      },
      "nullify": {
        "status": "complete"
      },
      "gateway_response": {
        "status": "success",
        "message": "successful transaction"
      }
    }
  ]
}

Campos de la respuesta

Parámetro	Tipo	Descripción
transaction	array of objects
id	string	Identificador de la transacción creado por payku. Ejemplo: 107999
status	string	Estatus de transacción. Los posibles estados que puede obtener son los siguientes: register pending success rejected Ejemplo: success
created_at	string	Fecha de registro. Ejemplo: 2019-10-25 14:10:03
email	string	Email del usuario Ejemplo: [email protected]
amount	int	Monto. Ejemplo: 98745
order	string	Número de orden. Ejemplo: 1572023402
subject	string	Descripción de la orden de compra. Ejemplo: Description
payment	object
start	string	Inicio de la transacción. Ejemplo: 2023-12-16 15:10:33
end	string	Fin de la transacción. Ejemplo: 2023-12-16 15:10:36
media	string	Medio de pago, utilizado por el usuario. Ejemplo: QR Interoperable
transaction_id	int	Identificador de la transacción creado por payku. Ejemplo: 107999
payment_key	string	Identificador del cobro creado por payku. Ejemplo: pra934939d607922f9e
transaction_key	string	Identificador de la transacción creado por payku.
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: 6669cbd982ef54c28f2f15fb9dc5262d
authorization_code	string	Código de autorización. Ejemplo: 107742
last_4_digits	string	Últimos 4 dígitos de la tarjeta afiliada. Ejemplo: 1233
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.
identificador	string	Ejemplo del Identificador de la transacción: Ejemplo: 11.111.111-1
banco	string	Ejemplo del banco el cual se realizo la transacción: Ejemplo: Banco Estado
numero_cuenta	string	Ejemplo del número de cuenta el cual se realizo la transacción: Ejemplo: 00126544977
currency	string	Moneda. Ejemplo: PEN
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 reverse_deleted 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

401

401

Token Público incorrecto.

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

Campos de la respuesta

Parámetro	Tipo	Descripción
type	string	Tipo de error ocurrido. Ejemplo: Unauthorized
message_error	object
error	string	Mensaje de error Ejemplo: waiting token public

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

Obtener transacción

GET/api/transaction/{identificador}

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

Parámetros de ruta

Parámetro	Tipo	Descripción
idrequerido	string	ID de la transacción a solicitar, payku puede recibir como id tanto el identificador de la transacción como el identificador de cobro: payment_key transaction_key máximo 30 caracteres

CURL

curl -X GET \
https://BASE-URL/api/transaction/ID-IDENTIFICADOR  \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer TOKEN-PUBLICO' \
-H 'Content-Type: application/json' \
-H 'Host: BASE-URL' \

PHP

$client = new \GuzzleHttp\Client();
  $body = $client->request('GET', 'https://BASE_URL/api/transaction/trx3b4d77b43acd9a720', [
    'headers' => [
      'Authorization' => 'Bearer TOKEN_PUBLICO'
    ]
  ])->getBody();
$response = json_decode($body);

JS

const request = async () => {
  const response = await fetch('https://BASE_URL/api/transaction/trx3b4d77b43acd9a720', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer TOKEN-PUBLICO'
    },
  });
  const result = await response.json();
  console.log(result)
}

request();

Respuestas

200

200

{
  "status": "success",
  "id": "trx3b4d77b43acd9a720",
  "created_at": "2019-10-25 14:10:03",
  "order": "1572023402",
  "email": "[email protected]",
  "subject": "Description",
  "amount": "98745",
  "payment": {
    "start": "2023-12-16 15:10:33",
    "end": "2023-12-16 15:10:36",
    "media": "QR Interoperable",
    "transaction_id": 107999,
    "payment_key": "pra934939d607922f9e",
    "transaction_key": null,
    "deposit_date": "2023-10-05",
    "verification_key": "6669cbd982ef54c28f2f15fb9dc5262d",
    "authorization_code": "107742",
    "last_4_digits": "1233",
    "installments": 0,
    "card_type": "VN",
    "additional_parameters": {
      "identificador": "11.111.111-1",
      "banco": "Banco Estado",
      "numero_cuenta": "00126544977",
      "network": {
        "ip_address": "192.0.2.123"
      }
    },
    "currency": "PEN"
  },
  "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 de la transacción creado por payku. Ejemplo: trx3b4d77b43acd9a720
created_at	string	Fecha de registro. Ejemplo: 2019-10-25 14:10:03
order	string	Número de orden. Ejemplo: 1572023402
email	string	Email del usuario Ejemplo: [email protected]
subject	string	Descripción de la orden de compra. Ejemplo: Description
amount	string	Monto. Ejemplo: 98745
payment	object
start	string	Inicio de la transacción. Ejemplo: 2023-12-16 15:10:33
end	string	Fin de la transacción. Ejemplo: 2023-12-16 15:10:36
media	string	Medio de pago, utilizado por el usuario. Ejemplo: QR Interoperable
transaction_id	int	Identificador de la transacción creado por payku. Ejemplo: 107999
payment_key	string	Identificador del cobro creado por payku. Ejemplo: pra934939d607922f9e
transaction_key	string	Identificador de la transacción creado por payku.
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: 6669cbd982ef54c28f2f15fb9dc5262d
authorization_code	string	Código de autorización. Ejemplo: 107742
last_4_digits	string	Últimos 4 dígitos de la tarjeta afiliada. Ejemplo: 1233
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.
identificador	string	Ejemplo del Identificador de la transacción: Ejemplo: 11.111.111-1
banco	string	Ejemplo del banco el cual se realizo la transacción: Ejemplo: Banco Estado
numero_cuenta	string	Ejemplo del número de cuenta el cual se realizo la transacción: Ejemplo: 00126544977
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: PEN
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

401

401

Token Público incorrecto.

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

Campos de la respuesta

Parámetro	Tipo	Descripción
type	string	Tipo de error ocurrido. Ejemplo: Unauthorized
message_error	object
error	string	Mensaje de error Ejemplo: waiting token public

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