Smartlinks V2

Smartlinks are hosted payment pages generated by Kushki. You create a link, share it with your customer (via email, WhatsApp, SMS, or any channel), and the customer completes payment in a Kushki-hosted form — no frontend integration required on your end.

Payment configuration types

Type	Description
`fixed`	You define the amount when creating the link. The customer pays exactly that amount. Supports one-time, subscription, and mixed flows.
`open`	The customer enters the amount at checkout. Useful for donations, invoices with variable totals, or tip flows.

Supported payment methods

Method	fixed	open
`credit-card`	✅	✅
`cash`	✅	✅
`transfer`	✅	✅
`subscription`	✅	—

Create a Smartlink

Call POST /smartlink/v2/smart-link. Kushki returns a smartLinkUrl ready to share.

{
  "publicMerchantId": "20000000103802320000",
  "merchantName": "Mi Comercio Perú",
  "paymentConfigType": "fixed",
  "paymentConfig": {
    "paymentType": "unique",
    "amount": {
      "currency": "PEN",
      "subtotalIva": 0,
      "subtotalIva0": 250,
      "iva": 0,
      "ice": 0
    },
    "paymentMethod": ["credit-card", "transfer"]
  },
  "generalConfig": {
    "productName": "Consulta médica",
    "description": "Pago por consulta médica online",
    "productImage": "https://yoursite.com/img/product.png",
    "brandLogo": "https://yoursite.com/img/logo.png",
    "executionLimit": 1,
    "showTimer": false,
    "enabled": true,
    "termsAndConditions": "https://yoursite.com/terms"
  },
  "styleAndStructure": {
    "structure": "checkout"
  },
  "contact": {
    "email": "soporte@micomercio.pe"
  },
  "formConfig": [],
  "language": "es"
}

Response:

{
  "smartLinkUrl": "https://pay.kushkipagos.com/global/4RUvloWDA"
}

Request fields

Top-level

Field	Required	Description
`publicMerchantId`	Yes	Your Kushki Public Key.
`merchantName`	Yes	Name shown in the Smartlink URL.
`paymentConfigType`	No	`fixed` (predefined amount) or `open` (customer enters amount).
`paymentConfig`	No	Payment settings for `fixed` type — see below.
`paymentConfig`	No	Payment settings for `open` type — see below.
`generalConfig`	Yes	Product info, display settings, execution limits — see below.
`styleAndStructure`	Yes	Layout and visual style — see below.
`contact`	Yes	Support contact details.
`formConfig`	Yes	Array of custom form fields shown at checkout (can be empty `[]`).
`language`	No	Checkout language: `es` (Spanish), `en` (English), `br` (Portuguese).

`paymentConfig` — fixed amount

Field	Required	Description
`paymentType`	Yes	`unique` (one-time), `subscription` (recurring), or `mixed` (both options).
`amount`	Yes	Amount object: `currency`, `subtotalIva`, `subtotalIva0`, `iva`, `ice`.
`paymentMethod`	Yes	Array of enabled methods: `cash`, `credit-card`, `transfer`, `subscription`.
`subscriptionOptions`	No	Required when `paymentType` is `subscription` or `mixed`.
`mixedOptions`	No	Required when `paymentType` is `mixed`.
`fastPayments`	No	Fast payment methods to enable (e.g., `"APPLE_PAY"`).

`paymentConfig` — open amount

Field	Required	Description
`paymentType`	Yes	Always `unique`.
`paymentMethod`	Yes	Array of enabled methods: `cash`, `credit-card`, `transfer`.
`currency`	Yes	`PEN` or `USD`.
`taxEnabled`	Yes	`true` to apply taxes.
`taxPercentage`	No	Tax percentage. Required if `taxEnabled` is `true`.
`defaultAmount`	No	Pre-filled amount (must be between `minAmount` and `maxAmount`).
`minAmount`	No	Minimum amount the customer can enter.
`maxAmount`	No	Maximum amount the customer can enter.

`generalConfig`

Field	Required	Description
`productName`	Yes	Product or service name shown at checkout.
`description`	Yes	Description (HTML supported).
`productImage`	Yes	URL of the product image.
`brandLogo`	Yes	URL of your brand logo.
`executionLimit`	Yes	How many times the link can be used. Set to `0` for unlimited.
`showTimer`	Yes	Show a countdown timer on the checkout page.
`enabled`	Yes	`true` to activate the link immediately.
`termsAndConditions`	Yes	URL to your terms and conditions.
`expirationDate`	No	Expiration timestamp (UTC epoch).
`promotionalText`	No	Promotional message shown at checkout.
`buyButtonText`	No	Custom buy button label. Required if `structure` is `cover`.
`payButtonText`	No	Custom pay button label.
`hidePayButtonAmount`	No	`true` to hide the amount on the pay button.

`styleAndStructure`

Field	Required	Description
`structure`	Yes	`checkout` (standard form) or `cover` (full-page cover design).
`coverModel`	No	Image alignment for cover: `left`, `center`, or `right`. Required for `cover`.
`buttonStyle`	No	Button shape: `square`, `semi`, or `round`. Required for `cover`.
`primaryColor`	No	Primary brand color in hexadecimal.
`secondaryColor`	No	Secondary brand color in hexadecimal.

Custom form fields (`formConfig`)

Add up to 6 types of custom fields to collect information from your customer at checkout:

Type	Description
`Input`	Single-line text field (e.g., name, order ID).
`Select`	Dropdown with predefined options.
`Date`	Date picker calendar.
`Area`	Multi-line text area.
`Checkbox`	Multiple-selection from a list.
`Radio`	Single-selection from a list.

Other operations

Method	Endpoint	Description
`GET`	`/smartlink/v2/smart-link/{smartlinkId}`	Retrieve a Smartlink's current configuration and usage stats.
`PATCH`	`/smartlink/v2/smart-link/{smartlinkId}`	Update an existing Smartlink's configuration.
`DELETE`	`/smartlink/v2/smart-link/{smartlinkId}`	Permanently delete a Smartlink. Deleted links are immediately unavailable.

Authentication

All endpoints require your Private Key:

Using the API

🟢 Production

🧪 Sandbox (UAT)

https://api.kushkipagos.com/

Available Endpoints

Create Smartlink

Generate a hosted payment page URL. Configure amount type, payment methods, layout, and custom form fields.

Get Smartlink

Retrieve the full configuration and usage count for an existing Smartlink.

Update Smartlink

Modify an existing Smartlink's settings without deleting and recreating it.

Delete Smartlink

Permanently remove a Smartlink. Customers who try to use the URL will see it as unavailable.

Got a suggestion on this documentation? Contact us.

Payment configuration types#

Supported payment methods#

Create a Smartlink#

Request fields#

Top-level#

paymentConfig — fixed amount#

paymentConfig — open amount#

generalConfig#

styleAndStructure#

Custom form fields (formConfig)#

Other operations#

Authentication#

Using the API#

Available Endpoints#