Transaction

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

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
• REQUIRED for merchants using the On-Site method

Request body

Parameter	Type	Description
emailrequired	string <email>	Payer's email ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ [ 20 .. 100 ] characters Example: [email protected]
orderrequired	string <uuid>	Merchant's order ^[a-zA-Z0-9- ]{1,40}$ [ 20 .. 40 ] characters Example: order-commerce-999
subjectrequired	string <text>	Order description ^[a-zA-Z0-9 ]{1,200}$ [ 1 .. 200 ] characters Example: description of the order
amountrequired	integer <int32>	Order amount ^[0-9]+$ Example: 100
currencyrequired	string <currency>	VES ISO 4217 [ 3 .. 3 ] characters Example: VES
paymentrequired	integer <int32>	17 ^[0-9]{1,2}$ Example: 17
urlreturn	string <uri>	Merchant return URL where the payer will be redirected after the transaction result is obtained. ^https:\/\/([\w\-]+\.)+[\w\-]+(\/[\w\-\.\/?%&=]*)?$ [ 1 .. 255 ] characters Example: https://youwebsite.com/return/client/order-commerce-999
urlnotifyrequired	string <uri>	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: { "transaction_id": "991...", "payment_key": "trx...", "transaction_key": "991...", "verification_key": "8b3...", "order": "199...", "status": "success" } Example of a failed response: { "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: { "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

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_PUBLIC'
  ]
])->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_PUBLIC'
    },
    body: JSON.stringify(data)
  });
  const result = await response.json();
  console.log(result)
}
request(data);

Responses

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

Response fields

Parameter	Type	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

400

Bad request.

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

Response fields

Parameter	Type	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

Parameter	Type	Description
transactionrequired	string	Unique transaction identifier Example: trx24...
payerrequired	object	Payer information
phone_numberrequired	string	Payer's phone number Example: 04129874563
payment_referencerequired	string	Payment reference issued by the banking entity Example: 12345600
id_numberrequired	string	Payer's ID number Example: V12987456
bank_coderequired	string	Payer's bank code Example: 0102
payment_date	string	Payment date (optional) Example: 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);

Responses

200

200

Successful response

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

Response fields

Parameter	Type	Description
transactionrequired	string	Unique transaction identifier Example: trx24...
statusrequired	string	Transaction status Example: register
messagerequired	string	Descriptive status message Example: payment received and pending verification
gatewayrequired	object	Payment gateway information
status	string	Gateway status Example: successful

400

400

Bad request

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

Response fields

Parameter	Type	Description
transactionrequired	string	Unique transaction identifier Example: trx24...
statusrequired	string	Transaction status Example: failed
message_errorrequired	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

Parameter	Type	Description
idrequired	string	Unique transaction identifier id: Identifier of the transaction (Transaction/POST) maximum 40 characters

Responses

200

200

{
  "status": "success",
  "id": "10ac494c1d8da71d98ea",
  "created_at": "2019-10-25 14:10:03",
  "order": "1572023402",
  "email": "[email protected]",
  "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"
  }
}

Response fields

Parameter	Type	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: [email protected]
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

400

Request failed.

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

Response fields

Parameter	Type	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

404

Identifier does not exist.

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

Response fields

Parameter	Type	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

200

{
  "status": "success",
  "id": "10ac494c1d8da71d98ea",
  "created_at": "2019-10-25 14:10:03",
  "order": "1572023402",
  "email": "[email protected]",
  "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"
  }
}

Response fields

Parameter	Type	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: [email protected]
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

400

Request error.

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

Response fields

Parameter	Type	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

404

Identifier does not exist.

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

Response fields

Parameter	Type	Description
status	string	Request status. Example: failed
type	string	Type of error. Example: Not Found
id	string	Id information Example: is not valid