1. CARD
Español
  • Español
  • English
  • Kushki Docs Colombia
  • Online Payments
    • CARD
      • Request a card token
        POST
      • Make a charge or deferred charge
        POST
      • Void a transaction
        DELETE
      • Create payment (tokenless)
        POST
      • Authorize payments
        POST
      • Capture an authorized payment
        POST
      • Bin Info V2
        GET
      • Verify Account
        POST
      • Reauthorize payments
        POST
      • Preauthorization (tokenless)
        POST
      • Validate OTP
        POST
      • Request deferred options
        GET
      • Bin Info
        GET
      • Refund a transaction
        DELETE
    • ANALYTICS
      • Get transactions list v1
      • Get transactions list v2
    • CARD-OUTS
      • Request a cash out token
      • Init Transaction
      • Update a cash out transaction
      • Delete a cash out transaction
      • Transaction Status
    • TRANSFER IN
      • Get Bank List
      • Request a Transfer In token
      • Init Transaction
      • Get Status
    • TRANSFER OUT
      • Get Bank List
      • Get Bank List V2
      • Request a Transfer Out token
      • Init Transaction
      • Get Status
      • Void a transaction
      • Balance for Payouts
    • CASH-IN
      • Request a cash in token
      • Init Transaction
      • Update a cash in transaction
      • Delete a cash in transaction
      • Transaction Status
    • CASH-OUT
      • Request a cash out token
      • Init Transaction
      • Update a cash out transaction
      • Delete a cash out transaction
      • Transaction Status
    • COMMISSIONS
      • Get Commission Configuration
    • PAYMENT-BUTTON
      • Create a payment button
    • PAYMENT-CREDENTIALS
      • Advanced search
      • Delete credential
      • Regenerate a credential
      • Search credentials
      • Activate or deactivate
      • Update credential
      • Create a credential
    • SMARTLINKS-V2
      • Create a Smartlink
      • Get a Smartlink
      • Update a Smartlink
      • Delete a smartlink
    • TRANSFER-OUT
      • Balance for Payouts
      • Get Bank List
      • Get Bank List V2
      • Request a Transfer Out token
      • Init Transaction
      • Get Status
      • Void a transaction
    • TRANSFER-IN
      • Get Bank List
      • Request a Transfer In token
      • Init Transaction
      • Get Status
    • ONE-CLICK & SCHEDULED PAYMENTS
      • Request a recurring charge token
      • Update recurring charge card data
      • Update a recurring charge
      • Add a temporary charge or discount
      • Get recurring charge Info
      • Create a recurring charge
      • Make an One-click payment
      • Cancel a recurring charge
      • Authorize payments
      • Capture an authorized payment
      • Get subscription transactions
    • GATEWAY-STATUS
      • Get gateway status
      • Get platform status
  • Schemas
    • SubscriptionTransactionsResponse
    • Card
    • SubscriptionTransaction
    • currency
    • ErrorResponse
    • Amount
    • extraTaxes
    • Deferred
    • Metadata
    • ContactDetails
    • documentType
    • orderDetails
    • Shipping Address
    • Billing-Address
    • product
    • threeDomainSecure
    • webhooks
    • headers
    • webhooksChargeback
    • citMit
    • network
    • binInfo
    • messageFields
    • UnexpectedErrorResponse
    • transactionType
BienvenidaPerú 🇵🇪México 🇲🇽Ecuador 🇪🇨Colombia 🇨🇴
Chile 🇨🇱
BienvenidaPerú 🇵🇪México 🇲🇽Ecuador 🇪🇨Colombia 🇨🇴
Chile 🇨🇱
  1. CARD

Preauthorization (tokenless)

POST
/card/v2/preAuthorization
Make a preauthorization (two-step payment) without the need for a card token.
DANGER

This is an On-demand service only available for PCI DSS compliance companies.#

You preauthorize a card payment when you want to verify that sufficient credit exists on a customer's credit card before processing a sale. The cardholder's credit limit will be reduced by the amount of the authorization until the authorization is captured or expires.
In Colombia, Perú, México and Chile, the authorization will expire after 28 days for credit cards and after 7 days for debit cards from the time of request.

This functionality is available for the following models:#

☑ Acquirer
☐ Aggregator

Limitations#

Only available for the Acquirer model in Colombia 🇨🇴.
Only available for Visa and Mastercard.
Not compatible with Siftscience nor TransUnion antifraud tools.
Not compatible with Kushki 3DS authentication tool (Use instead your own 3DS authentication engine).
Not compatible with Kushki OTP authentication.
NOTE: An authorization can be canceled through the Void a transaction endpoint. After performing the cancellation, no reauthorizations can be made on the canceled transaction.

Do you have your own 3DS authentication engine?*#

Make sure you include the threeDomainSecure object in your request.

Do you have your own subscriptions engine?*#

In case you have your own subscriptions engine (only PCI Compliance merchants), you can follow the steps below to process recurring charges:
1.
Send initialRecurrence in the transactionMode parameter and process the preauthorization. For this initial transaction, you must send the CVV.
2.
Make sure you save the transactionReference number of the charge completed in step 1.
3.
For the subsequent transactions, send subsequentRecurrence in the transactionMode parameter and include the transactionReference number in the initialRecurrenceReference field. Now you can omit the CVV.
An alternative option to process external subscriptions is by sending the parameter externalSubscriptionID. Click here for more information.
Got a suggestion on this documentation? Contact Us.

Request

Header Params

Body Params application/json

Examples

Responses

🟢201
application/json
Created
Body

🟠400
🟠403
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST 'https://api-uat.kushkipagos.com/card/v2/preAuthorization' \
--header 'Private-Merchant-Id;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "card": {
        "name": "John Doe",
        "number": "4259078012341233",
        "expiryMonth": "12",
        "expiryYear": "25",
        "cvv": "123"
    },
    "amount": {
        "subtotalIva": 0,
        "subtotalIva0": 20000,
        "ice": 0,
        "iva": 0,
        "currency": "COP"
    },
    "metadata": {
        "Referencia": "99999"
    },
    "contactDetails": {
        "documentType": "CC",
        "documentNumber": "1009283738",
        "email": "user@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "phoneNumber": "+573012345678"
    },
    "orderDetails": {
        "siteDomain": "example.com",
        "shippingDetails": {
            "name": "John Doe",
            "phone": "+573012345678",
            "address1": "Eloy Alfaro 139 y Catalina Aldaz",
            "address2": "centro 123",
            "city": "Bogotá",
            "region": "Cundinamarca",
            "country": "Colombia",
            "address": "Calle 100 # 10-20",
            "zipCode": "110111"
        },
        "billingDetails": {
            "name": "John Doe",
            "phone": "+573012345678",
            "address1": "Eloy Alfaro 139 y Catalina Aldaz",
            "address2": "centro 123",
            "city": "Bogotá",
            "region": "Cundinamarca",
            "country": "Colombia",
            "address": "Calle 100 # 10-20",
            "zipCode": "110111"
        }
    },
    "productDetails": {
        "product": [
            {
                "id": "198952AB",
                "title": "eBook Digital Services",
                "price": 10000,
                "sku": "10101042",
                "quantity": 1
            }
        ]
    },
    "fullResponse": "v2"
}'
Response Response Example
201 - fullResponse v2
{
    "details": {
        "amount": {
            "subtotalIva": 0,
            "subtotalIva0": 4000,
            "ice": 0,
            "iva": 0,
            "currency": "COP",
            "isDeferred": false
        },
        "approvalCode": "123456",
        "approvedTransactionAmount": 4000,
        "binInfo": {
            "bank": "BANCOLOMBIA",
            "binCard": "425907",
            "cardCountry": "Colombia",
            "lastFourDigits": "1233",
            "type": "credit"
        },
        "cardHolderName": "John Doe",
        "created": 1712159361000,
        "merchantId": "20000000105929933000",
        "merchantName": "Tu comercio Colombia",
        "messageFields": {
            "f38": "123456",
            "f39": "00"
        },
        "paymentBrand": "Visa",
        "processorBankName": "Kushki",
        "recap": "409415159483",
        "requestAmount": 4000,
        "responseCode": "000",
        "responseText": "Approval and completed successfully Accepted and processed.",
        "transactionId": "821712159361453407367",
        "transactionReference": "ba48f90b-43ef-4cff-b842-7bc34c41f78e",
        "transactionStatus": "APPROVAL",
        "transactionType": "PREAUTHORIZATION"
    },
    "ticketNumber": "821712159361453410",
    "transactionReference": "ba48f90b-43ef-4cff-b842-7bc34c41f78e"
}
Modified at 2026-04-16 23:06:30
Previous
Reauthorize payments
Next
Validate OTP
Built with