Smartlinks

Smartlinks V2 lets you generate a hosted payment URL that you share with your customers in Mexico 🇲🇽. No frontend integration required — Kushki hosts the payment form. Customers open the link, fill in any custom fields, select a payment method, and pay.

Smartlinks support:

Fixed amounts — you set the price, the customer pays that exact amount

Open amounts — the customer enters the amount at checkout (useful for donations, invoices, top-ups)

Payment types — one-time, subscription, or mixed (one-time + subscription option)

Payment methods — credit card, bank transfer, and cash

How it works

Create a Smartlink

Call POST /smartlink/v2/smart-link with your configuration. Returns a smartLinkUrl ready to share.

Fixed amount — one-time payment:

{
  "publicMerchantId": "20000000103802320000",
  "merchantName": "mi-comercio-mexico",
  "paymentConfigType": "fixed",
  "paymentConfig": {
    "paymentType": "unique",
    "paymentMethod": ["credit-card", "transfer", "cash"],
    "amount": {
      "subtotalIva": 0,
      "subtotalIva0": 500,
      "iva": 0,
      "currency": "MXN"
    }
  },
  "generalConfig": {
    "productName": "Producto de ejemplo",
    "description": "Descripción del producto",
    "productImage": "https://yoursite.com/product.jpg",
    "brandLogo": "https://yoursite.com/logo.png",
    "executionLimit": 100,
    "showTimer": false,
    "enabled": true,
    "termsAndConditions": "https://yoursite.com/terms"
  },
  "styleAndStructure": {
    "structure": "checkout",
    "buttonStyle": "round",
    "primaryColor": "#1A4CFF"
  },
  "contact": {
    "email": "user@example.com",
    "phoneNumber": "+525512345678"
  },
  "formConfig": [
    {
      "name": "nombres",
      "label": "Nombre completo",
      "type": "input",
      "required": true,
      "selected": true
    }
  ],
  "language": "es"
}

Response:

{
  "smartLinkUrl": "https://pay.kushkipagos.com/smartlink/abc123xyz"
}

Share the URL with your customer

Send the smartLinkUrl via email, SMS, WhatsApp, or embed it as a button on your site. The customer opens it in their browser — no app or SDK required.

Customer completes payment

The customer fills in any custom form fields, selects their payment method, and completes the transaction. Kushki handles the entire payment flow.

Get, update, or delete the Smartlink

Use GET /smartlink/v2/smart-link/{smartlinkId} to retrieve the current configuration, PATCH to update fields (e.g., disable the link or change the execution limit), and DELETE to permanently remove it.

Payment configuration types

`paymentConfigType`	Description
`fixed`	You define the amount — customer pays exactly that
`open`	Customer enters the amount at checkout

Payment methods

Value	Description
`credit-card`	Credit or debit card
`transfer`	Bank transfer
`cash`	Cash at partner collection points
`subscription`	Recurring card payments

Payment types

Value	Description
`unique`	Single one-time payment
`subscription`	Recurring subscription payments
`mixed`	Offers both one-time and subscription options to the customer

Form field types

Custom fields in formConfig can be any of these types:

Type	Description
`input`	Free-text input (name, email, etc.)
`select`	Dropdown list of options
`date`	Date picker
`area`	Multi-line text area
`checkbox`	Multi-select checkboxes
`radio`	Single-choice radio buttons

Open amount configuration

For paymentConfigType: "open", use the paymentConfig object (note the trailing space — this is a separate property from paymentConfig):

{
  "paymentConfigType": "open",
  "paymentConfig ": {
    "paymentType": "unique",
    "paymentMethod": ["credit-card", "transfer"],
    "currency": "MXN",
    "taxEnabled": false,
    "minAmount": 100,
    "maxAmount": 10000
  }
}

Field	Description
`currency`	`MXN`
`taxEnabled`	Whether to apply tax at checkout
`taxPercentage`	Tax rate (if `taxEnabled: true`)
`defaultAmount`	Pre-filled amount suggestion
`minAmount`	Minimum amount the customer can enter
`maxAmount`	Maximum amount the customer can enter

General configuration fields

Field	Required	Description
`productName`	✅	Product or service name
`description`	✅	Short description shown at checkout
`productImage`	✅	URL of the product image
`brandLogo`	✅	URL of your brand logo
`executionLimit`	✅	Max number of times this link can be used
`showTimer`	✅	Show a countdown timer on the payment page
`enabled`	✅	`true` to activate the link
`termsAndConditions`	✅	URL to your T&C page
`expirationDate`	Optional	Unix timestamp — link expires after this date
`buyButtonText`	Optional	Custom text for the pay button

Style and structure

Field	Options	Description
`structure`	`checkout`, `cover`	Page layout
`coverModel`	`left`, `center`, `right`	Image position (cover layout only)
`buttonStyle`	`square`, `semi`, `round`	Pay button corner style
`primaryColor`	Hex color	Main brand color
`secondaryColor`	Hex color	Secondary brand color

Currency

Currency	Code	Notes
Mexican Peso	`MXN`	Two decimal places — amounts use cents (e.g., `500.00`)

Language

Set the checkout page language with the language field:

Value	Language
`es`	Spanish
`en`	English
`br`	Portuguese

Authentication

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Create Smartlink

Generate a hosted payment URL with your product config, branding, form fields, and payment methods.

Get Smartlink

Retrieve the current configuration and status of a Smartlink by its ID.

Update Smartlink

Modify an existing Smartlink — enable/disable it, update the execution limit, or change config fields.

Delete Smartlink

Permanently remove a Smartlink. This action cannot be undone.

Got a suggestion on this documentation? Contact us.

How it works#

Payment configuration types#

Payment methods#

Payment types#

Form field types#

Open amount configuration#

General configuration fields#

Style and structure#

Currency#

Language#

Authentication#

Using the API#

Available Endpoints#