1. Two-step-payments
English
  • 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)
    • 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
      • Get BIN Info
      • Balance inquiries
      • 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-03-09 19:19:46
Previous
Two-step-payments
Next
Voids & Refunds
Built with