Skip to content
Payku Docs

Transaction

It allows the creation of transactions and later check their status.

Avatar
View
Base URL: https://app.payku.cl/ (Default server) · https://des.payku.cl/ (Sandbox server)

Generate a transaction

Section titled “Generate a transaction”
POST/api/transaction

This method allows to create a payment order to Payku and receives as a response the URL to redirect the payer's browser and the token that identifies the transaction. Once the payer makes the successful payment, Payku will notify the result to the page of the business that was sent in the urlnotify parameter.

additional_parameters = allows sending additional information to be registered in payku associated with the transaction order_ext within additional_parameters, it is a reserved word, and it is useful to associate the transaction to a unique merchant identifier

Request body

ParameterTypeDescription
emailrequired string <email>

Client email.

maximum 100 characters
Example: [email protected]
orderrequired string

Trade order.

maximum 40 characters
Example: 987450011
subjectrequired string

Description of the order.

maximum 2000 characters
Example: Test subject
amountrequired float

Order amount.

Important: if the amount includes decimals, it must be sent as a quoted string (for example, "150.50" instead of 150.50).

maximum 14 digits
Example: 150.50
currency string

Currency.

maximum 6 characters
Example: PEN
payment integer

Identifier of the payment method. If the identifier is sent, the payer will be redirected directly to the indicated means of payment.

  • 21 QR Interoperable (Yape, Plin and Others; PEN Currency)
  • 25 Débito, Crédito, Mastercard, Visa y Diners Club
maximum 2 characters
Example: 21
expired string

Date on which the transaction expires

This field is not required.

Allowed format (year-month-day hour:minute:second) Example: 2022-10-18 23:59:59

In case of being sent, it must comply with the following rules:

  • - It must be greater than 5 minutes from the current date (Santiago time).
  • - urlreturn is required, it will be attached as parameters GET /?message_error=expired&id=trx60dc327d9e4c094

Example: 2022-10-19 13:05:10
urlreturn string <url>

return url of the merchant where payku will redirect the payer after 3 seconds of obtaining the result of the transaction.

maximum 200 characters
Example: https://youwebsite.com/urlreturn?orderClient=123
urlnotify string <url>

Callback url of the business where payku will notify the payment.

  • Note: After the client completes the payment process at their bank, payku will automatically respond to the endpoint entered in urlnotify the result of the banking operation.
    • Approved Example:
    • {
      • "transaction_id": "9916587765599311",
      • "payment_key" : "trx32cb779c0a777fc68",
      • "transaction_key" : "9916581777599311",
      • "verification_key": "8b3e2202fb086a7de93777ae34d5e18c",
      • "order": "199",
      • "status": "success"
    • }
    • Rejected Example:
    • {
      • "transaction_id": "9916587765599311",
      • "payment_key" : "trx32cb779c0a777fc68",
      • "transaction_key" : "9916581777599311",
      • "verification_key": "8b3e2202fb086a7de93777ae34d5e18c",
      • "order": "199",
      • "status": "failed"
    • }
maximum 600 characters
Example: https://youwebsite.com/urlnotify?orderClient=123
additional_parameters object

Additional client parameters (Optional).

maximum 4000 characters
parameters1 string

Name of the parameter given by the user payku

Example: keyValue
parameters2 string

Name of the parameter given by the user payku

Example: keyValue2
order_ext string

Unique identifier provided by the merchant, which allows the transaction to be associated with an external identifier

Example: fff-777
Ventana de terminal
curl -X POST \
https://BASE-URL/api/transaction \
-H 'Accept: application/json, text/plain, */*' \
-H 'Authorization: Bearer PUBLIC-TOKEN' \
-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"
  }
}'

Responses

200
{
  "status": "pending",
  "id": "trx32cb779c0a777fc68",
  "url": "https://BASE-URL/payment_url",
  "hash": "00020000000000000111111222233339030226304E245",
  "qr_image": "data:image/png;base64,......"
}
Response fields
ParameterTypeDescription
status string

Transaction status. The possible statuses you can get are the following:

  • register
  • pending
  • success
  • rejected
  • refunded partial
  • refunded
Example: pending
id string

Transaction identifier created by payku.

Example: trx32cb779c0a777fc68
url string

URL to redirect the user.

Example: https://BASE-URL/payment_url
hash string

Hash of the transaction to generate the QR.

Example: 00020000000000000111111222233339030226304E245
qr_image string

QR image.

Example: data:image/png;base64,......

Get the status of multiple payments

Section titled “Get the status of multiple payments”
GET/api/transaction

you can filter the search for transactions depending on their status. for example. /api/transaction?success=true or to fetch multiple status /api/transaction?pending=true&rejected=true.

  • date_init: indicates the date from which you want to start the transaction search, if this parameter is not sent the search will start with the current date.
  • date_end: indicates the date where you want the transaction search to end, if this parameter is not sent, the search will have the current date as the end date.
  • estatus: you can filter the search for transactions depending on their status. for example: /api/transaction?success=true or to bring multiple statuses /api/transaction?pending=true&rejected=true.

For pagination it is necessary to add the following at the end of the endpoint ?page=1&per_page=100 the first parameter being the page number and the second the number of records per page. In case you want to search for the transactions between the dates 01-09-2021 y 15-09-2021, also that they are only success status transactions, the url to use would be the following: https://[URL_BASE]/api/transaction?date_init=2021-09-01&date_end=2021-09-15&success=true.

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

Responses

200
{
  "transaction": [
    {
      "id": "10ac494c1d8da71d98ea",
      "status": "success",
      "created_at": "2019-10-25 14:10:03",
      "email": "[email protected]",
      "amount": "98745",
      "order": "1572023402",
      "subject": "1572023402",
      "payment": {
        "start": "2020-12-16 15:10:33",
        "end": "2020-12-16 15:10:36",
        "media": "QR Interoperable",
        "transaction_id": "107999",
        "transaction_key": null,
        "deposit_date": "2022-10-05",
        "verification_key": "6669cbd982ef54c28f2f15fb9dc5262d",
        "authorization_code": "107742",
        "last_4_digits": "1233",
        "installments": 0,
        "card_type": "",
        "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"
      }
    }
  ]
}
Response fields
ParameterTypeDescription
transaction array of objects
id string

Identifier of the transaction created by Payku.

Example: 10ac494c1d8da71d98ea
status string

Transaction status The possible statuses you can get are the following:

  • register
  • pending
  • success
  • rejected
Example: success
created_at string

Registration date.

Example: 2019-10-25 14:10:03
email string

User email.

Example: [email protected]
amount string

Amount.

Example: 98745
order string

Order number.

Example: 1572023402
subject string

Description of the purchase order.

Example: 1572023402
payment object
start string

Start transaction.

Example: 2020-12-16 15:10:33
end string

End transaction.

Example: 2020-12-16 15:10:36
media string

Payment method, used by the user.

Example: QR Interoperable
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 client.

Example: 2022-10-05
verification_key string

Verification code created by Payku.

Example: 6669cbd982ef54c28f2f15fb9dc5262d
authorization_code string

Authorization code.

Example: 107742
last_4_digits string

Last 4 digits of the affiliated card.

Example: 1233
installments int

installments.

Example: 0
card_type string

Card type.

Example:
additional_parameters object

Example of additional parameters that Payku can send.
identificador string

Example of transaction identifier:

Example: 11.111.111-1
banco string

Example of bank where the transaction was made:

Example: Banco Estado
numero_cuenta string

Example of account number in which the transaction was made:

Example: 00126544977
currency string

Currency.

Example: PEN
nullify object

Object containing abort response information
status string

Cancellation status. The possible statuses you can get are as follows:

  • pending
  • awaiting_funds
  • waiting_bank_details
  • complete
  • reverse_deleted
  • reverse_completed
  • reverse_deleted
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

Get status of a payment

Section titled “Get status of a payment”
GET/api/transaction/{idTransaction}

This method allows you to obtain the information of a payment made in Payku

Path parameters

ParameterTypeDescription
idrequired string

id of the transaction to request

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

Responses

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": "QR Interoperable",
    "transaction_id": "107999",
    "transaction_key": null,
    "deposit_date": "2022-10-05",
    "verification_key": "6669cbd982ef54c28f2f15fb9dc5262d",
    "authorization_code": "107742",
    "last_4_digits": "1233",
    "installments": 0,
    "card_type": "",
    "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"
  }
}
Response fields
ParameterTypeDescription
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

Start of the transaction.

Example: 2020-12-16 15:10:33
end string

End of transaction.

Example: 2020-12-16 15:10:36
media string

Payment method, used by the user.

Example: QR Interoperable
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 client.

Example: 2022-10-05
verification_key string

Verification code created by Payku.

Example: 6669cbd982ef54c28f2f15fb9dc5262d
authorization_code string

Authorization code.

Example: 107742
last_4_digits string

Last 4 digits of the affiliated card.

Example: 1233
installments int

installments.

Example: 0
card_type string

Card type.

Example:
additional_parameters object

Example of additional parameters that Payku can send.
identificador string

Example of transaction identifier:

Example: 11.111.111-1
banco string

Example of bank where the transaction was made:

Example: Banco Estado
numero_cuenta string

Example of account number in which the transaction was made:

Example: 00126544977
network object

User network data:
ip_address string

Example of IP Address of the user:

Example: 192.0.2.123
currency string

Currency.

Example: 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
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
2016 - 2026 | Payku SpA