Payment Button - Kushki Developer Portal

The Payment Button (Webcheckout) lets you create a hosted payment page with a single API call. Instead of building and maintaining your own payment form, Kushki generates a URL you redirect your customer to — they select their preferred payment method and complete the transaction on a Kushki-hosted page.

Keep in mind!

Due to our risk policies, the available payment methods and the integration type may vary once you complete the affiliation. We will tell you how to proceed if this process applies to your merchant.

How It Works

Create a Webcheckout

Call the Create a payment button endpoint from your backend using your Private Merchant ID. Pass the order details — products, amount, accepted payment methods, and a redirect URL.

Kushki returns a webcheckoutUrl — a unique, ready-to-use hosted checkout page.

Redirect the Customer

Redirect your customer to the webcheckoutUrl. They will see a Kushki-hosted checkout page pre-loaded with your order summary, and can pay using any of the payment methods you configured.

Accepted payment methods in Colombia 🇨🇴:

Value	Method
`credit-card`	Credit and debit card
`cash`	Cash at payment points (Baloto, Efecty, Bancolombia, etc.)
`transfer`	PSE bank transfer

Customer Completes Payment

After the customer finishes (or abandons) the checkout, Kushki redirects them to your redirectURL. Use the webcheckoutId returned at creation to query the transaction status if needed.

Request Fields

Field	Required	Description
`kind`	✅	Always `"webcheckout"`
`redirectURL`	✅	URL where the customer is sent after completing or abandoning checkout
`products`	✅	Array of product objects — shown in the order summary
`paymentConfig`	✅	Payment configuration including amount and accepted methods
`contactDetail`		Customer's `name` and `email` — pre-fills the checkout form
`transactionType`		Set to `"PRE_AUTH"` to create a pre-authorization (authorization and capture flow)
`additionalInformation`		Extra key-value fields shown in the purchase summary on the checkout page

`products` array

Each item in products describes a line item shown in the checkout summary:

Field	Required	Description
`name`	✅	Product name
`description`	✅	Product description
`quantity`	✅	Quantity
`unitPrice`	✅	Unit price in COP

`paymentConfig` object

Field	Required	Description
`amount`	✅	Amount breakdown — see Amount Object below
`paymentMethod`		Array of accepted payment methods. If omitted, all methods available to your merchant are shown.

Amount Object

{
  "paymentConfig": {
    "amount": {
      "subtotalIva": 42017,
      "subtotalIva0": 0,
      "iva": 7983,
      "currency": "COP"
    }
  }
}

Field	Description
`subtotalIva`	Taxable base amount (before IVA)
`subtotalIva0`	Non-taxable amount (IVA = 0)
`iva`	IVA tax value
`currency`	Always `COP` for Colombia

The total displayed on the checkout page is subtotalIva + subtotalIva0 + iva.

Example Request

{
  "kind": "webcheckout",
  "contactDetail": {
    "email": "user@example.com",
    "name": "Andrés Martínez"
  },
  "redirectURL": "https://www.micomercio.com/gracias",
  "products": [
    {
      "name": "Tenis Trekking Pro",
      "description": "Talla 42, color negro",
      "quantity": 1,
      "unitPrice": 250000
    }
  ],
  "paymentConfig": {
    "amount": {
      "subtotalIva": 0,
      "subtotalIva0": 250000,
      "iva": 0,
      "currency": "COP"
    },
    "paymentMethod": ["credit-card", "cash", "transfer"]
  }
}

Example Response

{
  "webcheckoutId": "T3iDy0G4I",
  "webcheckoutUrl": "https://webcheckout.kushkipagos.com/webcheckout/T3iDy0G4I"
}

Redirect the customer immediately to webcheckoutUrl — links are single-use and expire after the session.

Pre-Authorization Flow

To create a pre-authorization (reserve funds without capturing), set transactionType: "PRE_AUTH" in paymentConfig. After the customer authorizes the payment on the checkout page, you capture the funds separately via the Card API.

{
  "paymentConfig": {
    "transactionType": "PRE_AUTH",
    "amount": { ... }
  }
}

Authentication

This endpoint requires your Private Key. Never expose it in client-side or frontend code.

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Create a Payment Button

Generates a hosted Webcheckout URL pre-loaded with your order details and accepted payment methods. Returns a webcheckoutUrl to redirect the customer to.

Got a suggestion on this documentation? Contact us.

PAYMENT-BUTTON

How It Works#

Request Fields#

products array#

paymentConfig object#

Amount Object#

Example Request#

Example Response#

Pre-Authorization Flow#

Authentication#

Using the API#

Available Endpoints#

How It Works

Request Fields

`products` array

`paymentConfig` object

Amount Object

Example Request

Example Response

Pre-Authorization Flow

Authentication

Using the API

Available Endpoints