Smartlinks

Receive payments through channels such as chats and social media without writing a single line of code.

Smartlinks are shareable payment links that allow you to sell online without a website. Create one in seconds and share it via WhatsApp, email, Instagram, Facebook, or any other channel — your customers get a hosted payment page powered by Kushki.

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.

What You Can Do with Smartlinks

All Payment Methods

Accept credit or debit cards, bank transfer, and cash — all from a single link.

One-Time or Recurring

Configure one-time payments, recurring subscriptions, or both (mixed) in the same link.

Fixed or Open Amount

Set a predefined price (fixed) or let the customer enter any amount within a range (open).

Fully Customizable

Add your brand logo, product image, colors, and custom button text to match your brand.

Usage Controls

Limit how many times a link can be used, set an expiration date, or disable it at any time.

Custom Form Fields

Collect additional data from customers — name, email, dates, selections, and more — via configurable form fields.

Smartlink ID

When you create a Smartlink, Kushki returns a smartLinkUrl. The smartlinkId is the last segment of that URL and is used as a path parameter in all other operations (Get, Update, Delete).

https://uat.kshk.co/global/u2Ab4qE_b
                            └─────────┘
                            smartlinkId = u2Ab4qE_b

Request Structure

Creating a Smartlink requires six top-level objects. All are required:

Object	Purpose
`publicMerchantId`	Your Public Key
`merchantName`	Name shown in the Smartlink URL
`paymentConfig`	Payment amount, method, and type
`generalConfig`	Product details, limits, and expiration
`styleAndStructure`	Visual layout and brand colors
`contact`	Support contact for the payer
`formConfig`	Custom fields shown in the payment form
`language`	Form language: `es` (default), `en`, `br`

Payment Configuration

Amount Type

The paymentConfigType field controls how the amount is set:

fixed — Predefined amount

open — Customer-defined amount

You define the exact amount. The customer cannot change it. Use paymentConfig (no trailing space).

Required fields:

Field	Description
`paymentType`	`unique`, `subscription`, or `mixed`
`amount`	Amount object (see below)
`paymentMethod`	Array: `cash`, `credit-card`, `transfer`, `subscription`

Use subscription in paymentMethod when paymentType is subscription.

Payment Type

When using paymentConfigType: fixed, the paymentType field controls the billing model:

unique — One-time payment

subscription — Recurring only

mixed — One-time + Recurring

A single charge. No recurring configuration needed.

General Configuration

The generalConfig object controls the product presentation and link behavior:

Field	Required	Description
`productName`	✅	Name of the product or service
`description`	✅	Product description in HTML format (e.g., `<p>Description</p>`)
`productImage`	✅	URL of the product image
`brandLogo`	✅	URL of your brand logo
`executionLimit`	✅	Max number of uses. Use `0` for no limit — the link is disabled after reaching the limit if set.
`showTimer`	✅	Show a countdown timer on the payment page
`enabled`	✅	Whether the Smartlink is active
`termsAndConditions`	✅	Terms and conditions text
`promotionalText`	❌	Promotional message displayed on the payment page
`expirationDate`	❌	Expiration date as a UTC Epoch timestamp (e.g., `1585717199999`)
`buyButtonText`	❌	Required if `structure` is `cover`
`payButtonText`	❌	Custom pay button text. Max 20 characters.
`hidePayButtonAmount`	❌	Hide the amount from the pay button. Default: `false`

Style and Structure

The styleAndStructure object controls the visual layout of the payment page:

Field	Required	Values	Description
`structure`	✅	`checkout`, `cover`	Layout type. `checkout` is a standard form; `cover` adds a visual cover section.
`coverModel`	❌*	`left`, `center`, `right`	Cover image alignment. *Required when `structure` is `cover`.
`buttonStyle`	❌*	`square`, `semi`, `round`	Pay button shape. *Required when `structure` is `cover`.
`primaryColor`	❌	Hex (e.g., `#00E6B2`)	Primary brand color
`secondaryColor`	❌	Hex (e.g., `#023366`)	Secondary brand color

Form Fields

The formConfig array defines the custom fields shown in the payment form. You can include up to 6 different field types. Each item shares these common fields:

Field	Description
`label`	Display label shown to the customer
`type`	Field type (see below)
`name`	Internal identifier for the field
`split`	`true` = half-width field · `false` = full-width field
`required`	Whether the field is mandatory

input

select

date

area

checkbox

radio

Single-line text field. Useful for name, email, and other short text.

Additional fields: placeholder, disabled, value (required if disabled: true), validateEmail

Set validateEmail: true on any input field where you expect the customer to enter an email address. Apidog validates the format before the form is submitted.

Managing Smartlinks

Once a Smartlink is created, you can retrieve, update, or permanently delete it using the smartlinkId.

Deleting a Smartlink is permanent. The link will no longer be accessible once deleted.

Error Codes

Code	Message	Cause
`WCH001`	El cuerpo de la petición es inválido	Malformed or missing required fields
`WCH002`	Ha ocurrido un error inesperado	Unexpected server-side error
`WCH003`	Smartlink no encontrado, no disponible o expirado	Invalid `smartlinkId`, disabled link, or expired link
`WCH009`	Credenciales inválidas	Invalid `Private-Merchant-Id`
`WCH012`	Moneda del smartlink inválida	Currency not supported for this merchant's country

Authentication

All Smartlink endpoints use your Private Merchant ID:

The publicMerchantId is sent in the request body (not as a header) when creating a Smartlink.

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Create a Smartlink

Creates a new payment link and returns the smartLinkUrl to share with customers.

Get a Smartlink

Retrieves the full configuration of an existing Smartlink by smartlinkId.

Update a Smartlink

Updates any configuration field of an existing Smartlink by smartlinkId.

Delete a Smartlink

Permanently deletes a Smartlink. This action cannot be undone.

Got a suggestion on this documentation? Contact us.

What You Can Do with Smartlinks#

Smartlink ID#

Request Structure#

Payment Configuration#

Amount Type#

Payment Type#

General Configuration#

Style and Structure#

Form Fields#

Managing Smartlinks#

Error Codes#

Authentication#

Using the API#

Available Endpoints#

What You Can Do with Smartlinks

Smartlink ID

Request Structure

Payment Configuration

Amount Type

Payment Type

General Configuration

Style and Structure

Form Fields

Managing Smartlinks

Error Codes

Authentication

Using the API

Available Endpoints