1. Two-step-payments
English
  • Español
  • English
  • 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
      • 11. Voucher
      • 5. Request deferred options
      • 8. Bin Info
      • 10. Validate OTP
      • 3. Void a transaction
      • 4. Refund a transaction
      • 6. Authorize payments
      • 1. Request a card token
      • 7. Capture an authorized payment
      • 11. Voucher
      • 2. Make a charge or deferred charge
      • 9. Bin Info V2
    • CASH IN
      • 1. Request a cash in token
      • 2. Init Transaction
      • 3. Transaction Status
      • 1. Request a cash in token
      • 2. Init Transaction
      • 3. Transaction Status
    • TRANSFER IN
      • 1. Get Bank List
      • 2. Request a Transfer In token
      • 3. Init Transaction
      • 4. Get Status
      • 1. Get Bank List
      • 4. Get Status
      • 2. Request a Transfer In token
      • 3. Init Transaction
    • TRANSFER OUT
      • 1. Get Bank List
      • 2. Request a Transfer Out token
      • 3. Init Transaction
      • 4. Get Status
      • 5. Wallet Balance
      • 2. Request a Transfer Out token
      • 1. Get Bank List
      • 5. Wallet Balance
      • 3. Init Transaction
      • 4. Get Status
    • 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
      • 3. Update recurring charge card data
      • 7. Add a temporary charge or discount
      • 10. Get recurring charge Info
      • 5. Cancel a recurring charge
      • 6. Update a recurring charge
      • 4. Make an One-click payment
      • 9. Capture an authorized payment
      • 8. Authorize payments
      • 2. Create a recurring charge
      • 1. Request a recurring charge token
    • PAYMENT BUTTON
      • 1. Create a payment button
      • 1. Create a payment button
    • SMARTLINKS V2
      • 1. Create a Smartlink
      • 2. Get a Smartlink
      • 3. Delete a Smartlink
      • 4. Update a Smartlink
      • 3. Delete a Smartlink
      • 4. Update a Smartlink
      • 1. Create a Smartlink
      • 2. Get a Smartlink
    • 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
      • 5. Delete credential
      • 4. Activate or deactivate
      • 2. Search credentials
      • 1. Create a credential
      • 3. Advanced search
      • 7. Regenerate a credential
    • COMMISSIONS
      • 1. Get Commission Configuration
      • 1. Get Commission Configuration
    • GATEWAY STATUS
      • 1. Get gateway status
      • 1. Get gateway status
    • ANALYTICS
      • 1. Get transactions list
      • 1. Get transactions list
    • ASYNC CARD RECURRING CHARGES
      • 1. Request a token
      • 2. Init an async card recurring charge
      • 3. Authorize payments
      • 4. Capture an authorized payment
      • 2. Init an async card recurring charge
      • 4. Capture an authorized payment
      • 1. Request a token
      • 3. Authorize payments
    • CARD ASYNC
      • 1. Request a card async token
      • 2. Init Transaction
      • 3. Authorize payments Copy
      • 4. Capture an authorized payment Copy
      • 5. Get Status
      • 4. Capture an authorized payment Copy
      • 5. Get Status
      • 3. Authorize payments Copy
      • 2. Init Transaction
      • 1. Request a card async token
  • CARD PRESENT PAYMENTS (API RAW) Copy
    • error-catalog
    • Test data
    • One-time payments
      • Single payment
    • Two-step-payments
      • Authorization and capture
        POST
    • Voids & Refunds
      • Void & Reverse
      • Refund a transaction
    • Card information
      • Balance inquiries
      • Get BIN Info
      • BIN info V2
      • Request deferred options
    • Query Transactions
      • Transaction Search
Perú 🇵🇪APPIAN-SUBMERCHANT-REGISTERMéxico 🇲🇽Ecuador 🇪🇨Chile 🇨🇱
Perú 🇵🇪APPIAN-SUBMERCHANT-REGISTERMéxico 🇲🇽Ecuador 🇪🇨Chile 🇨🇱
  1. Two-step-payments

Authorization and capture

POST
/pos/v1/transaction
With this endpoint you can:
Carry out preauthorizations
Make reauthorizations
Make captures
Void preauthorizations

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 (Chip)
MCR = Magnetic Card reader (Stripe)
NFC = Near Field Communication

Make preauthorizations (Place a hold on card payment)#

You can retain the balance of a card to withhold a certain amount of the account.

Structure#

To make authorizations, send preAuth in the transaction_type field and Authorization in the transaction_mode field as part of the body of your request. (See full example on the right side of the screen).

Make reauthorizations#

You can extend the amount or effect of the authorization.
The currency must be the same as the authorization.
An amount of 0 can be sent in the reauthorization to extend the date of capture.
The reauthorization can be for an amount greater than the authorization.
Note
A reauthorization can be canceled. After performing the cancellation, no reauthorizations can be made on the canceled transaction.

Structure#

To make reauthorizations, send reAuthorization in the transaction_type field and Authorization in the transaction_mode field as part of the body of your request. (See full example on the right side of the screen).
Discover how to perform a cardless reauthorization.

Capture a payment#

Once you are required to collect the funds from the card, capture the amount you define.
The capture must be the sum of the authorization and all reauthorizations made that have not been canceled. The amount to be captured can be equal or lower than the amount authorized or reauthorized.

Structure#

To capture send capture in the transaction_type field, Authorization in the transaction_mode field and the transaction_reference of the transaction to capture as part of the body of your request (transaction_reference must be from an authorization, not from a reauthorization). (See full example on the right side of the screen).
Discover how to perform a cardless capture.

Cardless operations#

You can perform a reauthorization, capture or void without requiring the reading of the card. Below you will find out how you can carry out a cardless operation:
Note
You can also check the information for a cardless refund.
To perform an operation without a card it is required to send the omit_card field with the value of true in the request. The fields required for a cardless operation are the following:
PropertyTypeAllowed values
amountObject
transaction_modeStringAuthorization, Void
transaction_typeStringcharge, reAuthorization, capture
client_transaction_idString
transaction_referenceString
omit_cardBooleantrue
Note
Cardless operations are available for Visa and Mastercard credit and debit cards, and are currently in Beta phase in Peru.

Example of a cardless operation#

To perform a cardless operation, the omit_card field is sent with the value of true and then the other non-required fields are omitted:
Reauthorization
Capture
Void
{
    "amount": {
        "currency": "PEN",
        "iva": 0.0,
        "subtotal_iva": 0.0,
        "subtotal_iva0": 600
    },
    "transaction_mode": "Authorization",
    "transaction_type": "reAuthorization",
    "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a",
    "transaction_reference": "f2f29080-0214-42c0-95a5-77ecf3434cd7",
    "omit_card": true
}

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 '{
    "card": {
        "card_holder_name": "John Doe"
    },
    "amount": {
        "iva": 0,
        "tip": 0,
        "currency": "MXN",
        "extra_taxes": {
            "iac": 0,
            "ice": 0,
            "airport_tax": 0,
            "travel_agency": 0
        },
        "subtotal_iva": 0,
        "subtotal_iva0": 600
    },
    "country": "MEX",
    "cvm_type": "none",
    "is_cashback": false,
    "pos_details": {
        "brand": "SUNMI",
        "model": "P2-EU",
        "version": "Kushki SunmiV1.1.26",
        "location": {
            "latitude": -0.22480833333333333,
            "longitude": -78.487955
        },
        "has_print": true,
        "terminal_id": "PB04216R20537"
    },
    "card_details": {
        "tracks": {
            "track_ksn": "FFFF4357486333600002",
            "enc_track2": "283587285CE10278E7FA50AD5C97CFFE87F472C9FE6406F8"
        },
        "enc_tlv": "CE447A062C49774934E42A7F826668C0C478E38402C158062EE794C0E471B43EA8CE49C256C2C8B157526B0B2BE74FC23F65E18D4F52B99A1A0910E6CCD9B11A32D6D537E2B6E2B011C89569DE6A3D53318080BC77E0E70B398ED3083FD7366CCF8FB4DBF34A116E6D52CFBEF26371878D842034E5029EF62DF235D2C427F04102E451773D9E8975978917E3BC531327702967052E239F8C592734AE14688E603C52B858FC1D97B763AE623603F1475FFFB065EC07AF7A29",
        "pin_ksn": "FFFF4357486333600002",
        "reading_type": "ICC"
    },
    "contact_details": {
        "email": "",
        "last_name": "",
        "first_name": "",
        "phone_number": "",
        "document_type": "-1",
        "document_number": "",
        "second_last_name": ""
    },
    "transaction_mode": "Authorization",
    "transaction_type": "preAuth",
    "client_transaction_id": "6680eadc-6c8d-44aa-8ca0-18e061c1472a"
}'
Response Response Example
200 - Approved preAuth transaction
{
    "additional_amounts": {
        "account_type": "",
        "amount": 0,
        "amount_type": "",
        "card_type": "",
        "currency_code": ""
    },
    "authorized_amount": 601,
    "card_type": "credit",
    "cvm_type": "none",
    "F11": "101658",
    "franchise": "MASTERCARD",
    "kushki_response": {
        "code": "000",
        "message": "Transacción Aprobada."
    },
    "message_fields": {
        "F38": "890862",
        "F39": "00"
    },
    "transaction_reference": "2aa48997-a545-4bdb-8e1c-a57546f03e5f",
    "transaction_status": "APPROVAL",
    "transaction_type": "preAuth",
    "ticket_number": "111727462978861299"
}
Modified at 2026-04-16 14:01:17
Previous
Two-step-payments
Next
Voids & Refunds
Built with