Smartlinks let you generate a shareable payment URL that opens a Kushki-hosted checkout form. Share the link via email, WhatsApp, or any channel — your customer clicks it, fills in the form, and pays. No frontend integration needed.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.
Key Concepts#
Payment config types#
| Type | Description |
|---|
fixed | The amount is set by you — the customer cannot change it. |
open | The customer enters the amount within a defined range (minAmount / maxAmount). |
Payment types (within fixed)#
| Value | Description |
|---|
unique | One-time payment |
subscription | Recurring charge — customer is enrolled in a subscription |
mixed | One-time charge + subscription enrollment in a single flow |
| Value | Description |
|---|
checkout | Standard inline checkout layout |
cover | Full-page cover layout with a hero image and a call-to-action button |
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 |
subscription | Use this value when paymentType is subscription |
Creating a Smartlink#
Call Create a Smartlink from your backend with your publicMerchantId and the configuration objects. The response returns a ready-to-share smartLinkUrl.Required objects#
| Object | Description |
|---|
publicMerchantId | Your Public Merchant ID |
merchantName | Name shown in the smartlink URL slug |
paymentConfig | Amount, payment type, and accepted methods — see below |
generalConfig | Product info, expiration, usage limits, and UI copy |
styleAndStructure | Layout structure and brand colors |
contact | Support email and phone shown on the checkout page |
paymentConfig — fixed amount#
{
"paymentConfigType": "fixed",
"paymentConfig": {
"paymentType": "unique",
"amount": {
"subtotalIva": 0,
"subtotalIva0": 50000,
"iva": 0,
"currency": "COP"
},
"paymentMethod": ["credit-card", "cash", "transfer"]
}
}
paymentConfig — open amount#
{
"paymentConfigType": "open",
"paymentConfig": {
"paymentType": "unique",
"paymentMethod": ["credit-card", "transfer"],
"currency": "COP",
"minAmount": 10000,
"maxAmount": 500000,
"defaultAmount": 50000,
"taxEnabled": false
}
}
generalConfig fields#
| Field | Description |
|---|
productName | Product or service name shown on the form |
description | Description in HTML format |
productImage | URL of the product image |
brandLogo | URL of your brand logo |
executionLimit | Max number of times the link can be used. 0 = unlimited. |
expirationDate | UTC timestamp (Epoch) — link expires after this date |
enabled | Whether the link is active |
termsAndConditions | URL to your T&C page |
showTimer | Show a countdown timer on the form |
buyButtonText | CTA button text (required if structure is cover) |
payButtonText | Pay button text override |
hidePayButtonAmount | Hide the amount from the pay button |
styleAndStructure fields#
| Field | Description |
|---|
structure | "checkout" or "cover" |
primaryColor | Brand primary color in hex (e.g. "#E83D42") |
secondaryColor | Brand secondary color in hex |
coverModel | Cover layout variant (required if structure is cover) |
buttonStyle | Button style (required if structure is cover) |
You can add custom input fields to your Smartlink form using the formConfig array. Six field types are supported:| Type | Description |
|---|
input | Free-text field (name, email, reference number, etc.) |
select | Dropdown with a list of options |
date | Date picker calendar |
checkbox | True/false toggle (e.g. terms acceptance) |
file | File upload field |
disclaimer | Read-only text block (no customer input) |
Each item in formConfig includes label, type, name, placeholder, required, and disabled. For input fields, set validateEmail: true to enforce email format validation.
Subscription Smartlinks#
When paymentType is subscription, include a subscriptionOptions object:{
"paymentConfig": {
"paymentType": "subscription",
"paymentMethod": ["subscription"],
"amount": {
"subtotalIva0": 50000,
"subtotalIva": 0,
"iva": 0,
"currency": "COP"
},
"subscriptionOptions": {
"periodicity": "monthly",
"planName": "Plan mensual",
"startDate": "2025-06-01",
"terms": "https://micomercio.com/terminos"
}
}
}
mixed type (one-time charge + subscription enrollment), also include mixedOptions with numberOfFees, periodicity, and subscriptionDay.
Managing Smartlinks#
| Operation | When to use |
|---|
| Get | Retrieve full Smartlink configuration by smartlinkId |
| Update | Modify an existing Smartlink — amount, methods, copy, style |
| Delete | Permanently disable a Smartlink. Once deleted, the URL stops working. |
Authentication#
Using the API#
https://api.kushkipagos.com/
Available Endpoints#
Create a Smartlink
Generates a hosted payment URL with your product, amount, and branding configuration.
Get a Smartlink
Retrieves the full configuration of an existing Smartlink by its ID.
Update a Smartlink
Modifies an existing Smartlink — amount, payment methods, copy, or styling.
Delete a Smartlink
Permanently disables a Smartlink. The URL stops working immediately.
Got a suggestion on this documentation? Contact us.
