1. One-time payments
Español
  • Español
  • English
  • Back to home
  • Perú 🇵🇪
  • Bienvenidos
  • ONLINE PAYMENTS
    • CARD
      • 1. Request a card token
      • 2. Make a charge or deferred charge
      • 3. Void a transaction
      • 4. Refund a transaction
      • 5. Request deferred options
      • 6. Authorize payments
      • 7. Capture an authorized payment
      • 8. Bin Info
      • 9. Bin Info V2
      • 10. Validate OTP
      • 5. Request deferred options
      • 2. Make a charge or deferred charge
      • 1. Request a card token
      • 8. Bin Info
      • 7. Capture an authorized payment
      • 10. Validate OTP
      • 4. Refund a transaction
      • 9. Bin Info V2
      • 6. Authorize payments
      • 3. Void a transaction
    • ONE-CLICK & SCHEDULED PAYMENTS
      • 1. Request a recurring charge token
      • 2. Create a recurring charge
      • 3. Update recurring charge card data
      • 4. Make an One-click payment
      • 5. Cancel a recurring charge
      • 6. Update a recurring charge
      • 7. Add a temporary charge or discount
      • 8. Authorize payments
      • 9. Capture an authorized payment
      • 10. Get recurring charge Info
      • 9. Capture an authorized payment
      • 7. Add a temporary charge or discount
      • 8. Authorize payments
      • 5. Cancel a recurring charge
      • 4. Make an One-click payment
      • 1. Request a recurring charge token
      • 2. Create a recurring charge
      • 10. Get recurring charge Info
      • 6. Update a recurring charge
      • 3. Update recurring charge card data
    • TRANSFER IN
      • 2. Request a Transfer In token
      • 3. Init Transaction
      • 4. Get Status
      • 2. Request a Transfer In token
      • 4. Get Status
      • 3. Init Transaction
    • CASH IN
      • 1. Request a cash in token
      • 2. Init Transaction
      • 3. Transaction Status
      • 2. Init Transaction
      • 1. Request a cash in token
      • 3. Transaction Status
    • SMARTLINKS V2
      • 1. Create a Smartlink
      • 2. Get a Smartlink
      • 3. Delete a Smartlink
      • 4. Update a Smartlink
      • 4. Update a Smartlink
      • 2. Get a Smartlink
      • 3. Delete a Smartlink
      • 1. Create a Smartlink
    • ANALYTICS
      • 1. Get transactions list
      • 1. Get transactions list
    • GATEWAY STATUS
      • 1. Get gateway status
      • 1. Get gateway status
    • COMMISSIONS
      • 1. Get Commission Configuration
      • 1. Get Commission Configuration
    • PAYMENT CREDENTIALS
      • 1. Create a credential
      • 2. Search credentials
      • 3. Advanced search
      • 4. Activate or deactivate
      • 5. Delete credential
      • 6. Update credential
      • 7. Regenerate a credential
      • 6. Update credential
      • 7. Regenerate a credential
      • 2. Search credentials
      • 4. Activate or deactivate
      • 3. Advanced search
      • 1. Create a credential
      • 5. Delete credential
    • PAYMENT BUTTON
      • 1. Create a payment button
      • 1. Create a payment button
    • Request deferred options
  • CARD PRESENT PAYMENTS (API RAW)
    • Test data
    • error-catalog
    • One-time payments
      • Single payment
        POST
    • Two-step-payments
      • Authorization and capture
    • Voids & Refunds
      • Void & Reverse
      • Refund a transaction
    • Card information
      • Balance inquiries
      • Get BIN Info
      • BIN info V2
      • Request deferred options
    • Query Transactions
      • Transaction Search
  1. One-time payments

Single payment

POST
/pos/v1/transaction
With this endpoint you can:
Take payments
Make deferred charges
Take payments with tips
Make payments with cashback

Supported Reading Channels#

We support the following reading channels. The fields you send to us to process a charge may differ depending on the reading type.
ICC = Integrated Circuit Card
MCR = Magnetic Card reader
NFC = Near Field Communication

Take payments#

You can make card present payments in different currencies by adding taxes, deferring a transaction, or making a cashback by reading a physical card with a terminal.

Structure#

Single charge#

To make a charge, send charge in the transaction_type field and Authorization in the transaction_mode field as part of the body of your request.

Deferred charges#

To defer a payment, if your customer requests to defer the charge of the transaction made at your store, you need to consume the endpoint pos/v1/transaction in the request body, include charge in the transaction_type field and Authorization in the transaction_mode field. Also, include the value of is_deferred as true, send the deferred object and in months, include the total number of months for which your customer’s payment will be deferred.

Deferred charges in Peru#

For deferred charges, simply include the months parameter within the deferred object.
Review the complete request example in the top right corner of the screen.
"deferred": {
    "months": "10"
}

Accepting payments with tips#

You can accept payments with tips by adding an additional field with the tip information.
To accept this type of service, you need to consume the endpoint /pos/v1/transaction and include the tip amount in the tip field. Send Authorization in the transaction_mode field and charge in the transaction_type as part of the request body.
Note
The tip amount is in addition to the total amount of the transaction sent in the fields subtotal_iva or subtotal_iva0.

Accepting payments with cashback (Perú 🇵🇪)#

Kushki allows you to make a cashback at the time of a physical card payment. To accept this type of service, you need to consume the endpoint /pos/v1/transaction and send the value of the is_cashback parameter as true and specify the cashback amount in cashback_amount.
WARNING
Please note that cashback only works with local cards.
Cashback is not supported for contactless transactions. Ensure the reading_type is not set to NFC.

Request

Header Params

Body Params application/json

Examples

Responses

🟢200
application/json
OK
Body

🟠400
🟠401
🔴500
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST 'https://api-uat.kushkipagos.com/pos/v1/transaction' \
--header 'Private-Credential-Id;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": {
        "currency": "CLP",
        "iva": 0,
        "subtotal_iva": 0,
        "subtotal_iva0": 20000,
        "tip": 0,
        "extra_taxes": {
            "airport_tax": 0,
            "iac": 0,
            "ice": 0,
            "travel_agency": 0
        }
    },
    "card_details": {
        "pin_ksn": "FFFF4357486333600002",
        "reading_type": "MCR",
        "tracks": {
            "enc_track1": "06056D9EE9D77E4D846912F77C0B37C5FC6A95D1DF21DD502D3A08E8141CF82818F5DC4FA7637F400EA488D388F2B70F8A22EAEFBBEEDDE93A118BFB789BD8C0",
            "enc_track2": "FD580B3BBFCCB821EAB4AB64947C4632C0BE6C70AB4ECDE4",
            "track_ksn": "FFFF4357486333600002"
        }
    },
    "contact_details": {
        "document_number": "123666",
        "document_type": "0",
        "email": "",
        "first_name": "",
        "last_name": "",
        "second_last_name": "",
        "phone_number": ""
    },
    "card": {
        "card_holder_name": "John Doe"
    },
    "pos_details": {
        "terminal_id": "PB04209860189",
        "brand": "SUNMI",
        "location": {
            "latitude": -0.1848534,
            "longitude": -78.4769761
        },
        "model": "P2-EU",
        "version": "Kushki SunmiV1.1.13",
        "has_print": true
    },
    "country": "CLP",
    "client_transaction_id": "ae6dd91a-9173-4ec7-8934-3178454ef341",
    "transaction_type": "charge",
    "transaction_mode": "Authorization",
    "cvm_type": "chip"
}'
Response Response Example
200 - Approved charge transaction
{
    "additional_amounts": {
        "account_type": "",
        "amount": 0,
        "amount_type": "",
        "card_type": "",
        "currency_code": ""
    },
    "authorized_amount": 611,
    "card_type": "credit",
    "cvm_type": "none",
    "F11": "101619",
    "franchise": "MASTERCARD",
    "kushki_response": {
        "code": "000",
        "message": "Transacción Aprobada."
    },
    "message_fields": {
        "F38": "121866",
        "F39": "00"
    },
    "transaction_reference": "fb1d8f34-31fc-4d9d-ab7e-375d7f0801a5",
    "transaction_status": "APPROVAL",
    "transaction_type": "charge",
    "ticket_number": "111727462978861299"
}
Modified at 2026-03-13 14:08:16
Previous
One-time payments
Next
Two-step-payments
Built with