Cómo crear un enlace de pago

Un enlace de pago es una URL compartible vinculada a un catálogo de productos y una configuración de pago. Esta guía muestra cómo crear un enlace usando el endpoint POST /payment-links.

Cómo funciona

Características clave:

Una sola llamada de creación: defines la identificación del enlace, el catálogo de productos y los métodos de pago aceptados en una sola solicitud; la respuesta devuelve el link_id y un short_id.
URL compartible: el short_id devuelto es el identificador público usado en la URL del enlace compartible.
Catálogo de productos: un enlace custom (el tipo por defecto) incluye productos predefinidos con montos fijos, por lo que el arreglo products es obligatorio.
Métodos de pago configurables: habilitas los métodos por enlace (crédito, débito, Boleto, Pix), y se requiere al menos uno entre credit, debit, bankslip o instant_payment.
Límites opcionales: puedes establecer una expiration (máximo 1 año) y un tope max_orders para la cantidad de ventas antes de que el enlace expire.
Entrega opcional: cuando request_delivery_address es true, se solicita al comprador una dirección de entrega y shipping_amount pasa a ser obligatorio.

Antes de empezar

Obtén un token de acceso. Consulta Autenticación.
Ten a mano el x-seller-id del comercio.
Si el enlace usa imágenes de productos, carga las imágenes primero y guarda el image_id. Consulta Configura el enlace de pago.

Construye la solicitud

Endpoint
`POST /payment-links`

Campos obligatorios

Campo	Tipo	Descripción	Ejemplo
`label`	string	Etiqueta de identificación (6–36 caracteres)	`black-friday-2026`
`payment`	object	Configuración de pago	---
`currency`	string	Moneda del país	`BRL`, `CLP` o `MXN`
`products.product_type`	string	Consulta los valores válidos en el modelo de datos del producto	`physical_goods`
`products.title`	string	Título del producto (máx.: 128)	`Camiseta Oficial Getnet`
`products.amount`	integer	Monto de compra (ver nota sobre montos arriba)	`15000`

Campos condicionales

Campo	Tipo	Descripción	Ejemplo
`shipping_amount`	integer	Obligatorio cuando `request_delivery_address=true`. Valor en formato entero (consulta la nota en la sección Reglas de completado de campos)	`500`
`products`	array	Catálogo de productos. Obligatorio para `custom`	---
`payment.credit.brands.brand`	Marca de tarjeta. Obligatorio cuando `payment.credit.enabled=true`.	`VISA`

Campos opcionales

Campo	Tipo	Descripción	Ejemplo
`expiration`	string	Fecha de expiración. Máximo 1 año	`2026-12-31T23:59:59`
`max_orders`	integer	Cantidad máxima de ventas antes de la expiración (mín.: 1)	`100`
`type`	string	Tipo de enlace	`custom`
`request_delivery_address`	boolean	Solicitar dirección de entrega	`true` o `false`
`products.description`	string	Descripción del producto (máx.: 1024)	`Camiseta 100% algodão, tamanho M`
`products.order_prefix`	string	Prefijo del ID de la orden (máx.: 10)	`BF2026`
`products.quantity`	integer	Cantidad (por defecto: 1)	`2`
`products.image_id`	string	Referencia a la imagen cargada mediante `POST /payment-links/products/images`	`6697e354-ab4a-11eb-bcbc-0242ac130002`
`payment.credit`	object	Configuración de crédito	---
`payment.debit`	object	Configuración de débito con	---
`payment.bankslip`	object	Boleto (solo Brasil)	---
`payment.instant_payment`	object	Pix (solo Brasil)	---

Valores de campo

Campo	Valor
`product_type`	`cash_carry`, `digital_content`, `digital_goods`, `digital_physical`, `gift_card`, `physical_goods`, `renew_subs`, `shareware` o `service`
`brand`	`VISA`, `MASTERCARD`, `AMEX`, `ELO`, `HIPERCARD` o `CARNET`

Reglas de completado de campos:

Montos: proporciona el valor en formato entero, donde los últimos 2 dígitos representan los centavos. Para países donde los centavos no aplican, completa el valor con 2 ceros al final (por ejemplo, $150 → envía 15000).
Debe estar presente al menos uno entre credit, debit, bankslip o instant_payment.

Para la estructura detallada de crédito, débito, marcas de tarjeta y cuotas, consulta Configura el enlace de pago.

Ejemplo de solicitud

curl -X POST "${API_URL}/payment-links" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "x-seller-id: ${SELLER_ID}" \
    -H "country: BR" \
    -H "tenant: santander" \
    -H "Content-Type: application/json" \
    -d '{
    "label": "black-friday-2026",
    "expiration": "2026-12-31T23:59:59",
    "max_orders": 100,
    "type": "custom",
    "request_delivery_address": false,
    "products": [
       {
          "product_type": "physical_goods",
          "title": "Camiseta Oficial Getnet",
          "description": "Camiseta 100% algodão",
          "order_prefix": "BF2026",
          "amount": 9990,
          "quantity": 1,
          "image_id": "6697e354-ab4a-11eb-bcbc-0242ac130002"
       }
    ],
    "payment": {
       "credit": {
          "enabled": true,
          "brands": [
             {
                "enabled": true,
                "brand": "VISA",
                "currencies": ["BRL"],
                "threeds": true,
                "supported_installments": [
                   {
                      "schema": "plan_lojista",
                      "schema_name": "Plan Lojista",
                      "installments": [2,3,4,5,6,7,8,9,10,11,12],
                      "installments_with_interest": [6,9,12]
                   }
                ]
             },
             {
                "enabled": true,
                "brand": "MASTERCARD",
                "currencies": ["BRL"],
                "threeds": true,
                "supported_installments": [
                   {
                      "schema": "plan_lojista",
                      "schema_name": "Plan Lojista",
                      "installments": [2,3,6],
                      "installments_with_interest": []
                   }
                ]
             }
          ]
       },
       "debit": {
          "enabled": true,
          "brands": [
             { "enabled": true, "brand": "VISA", "currencies": ["BRL"], "threeds": true },
             { "enabled": true, "brand": "MASTERCARD", "currencies": ["BRL"], "threeds": true }
          ]
       },
       "bankslip": { "enabled": true },
       "instant_payment": { "enabled": true }
    },
    "currency": "BRL"
 }'

Ejemplo de respuesta

El short_id devuelto es el identificador público usado en la URL del enlace compartible.

{
  "link_id": "76c3caa9-4c5b-243b-8fc5-a73381fcdf9b",
  "short_id": "ZDdlNmM1YTg",
  "seller_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": "black-friday-2026",
  "expiration": "2026-12-31T23:59:59.000Z",
  "max_orders": 100,
  "type": "custom",
  "successful_sales": 0,
  "request_delivery_address": false,
  "shipping_amount": 0,
  "products": [
    {
      "product_type": "physical_goods",
      "title": "Camiseta Oficial Getnet",
      "description": "Camiseta 100% algodão",
      "order_prefix": "BF2026",
      "amount": 9990,
      "quantity": 1,
      "image_id": "6697e354-ab4a-11eb-bcbc-0242ac130002"
    }
  ],
  "payment": {
    "credit": {
      "enabled": true,
      "brands": [
        {
          "enabled": true,
          "brand": "VISA",
          "currencies": ["BRL"],
          "threeds": true,
          "supported_installments": [
            {
              "schema": "plan_lojista",
              "schema_name": "Plan Lojista",
              "installments": [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
              "installments_with_interest": [6, 9, 12]
            }
          ]
        },
        {
          "enabled": true,
          "brand": "MASTERCARD",
          "currencies": ["BRL"],
          "threeds": true,
          "supported_installments": [
            {
              "schema": "plan_lojista",
              "schema_name": "Plan Lojista",
              "installments": [2, 3, 6],
              "installments_with_interest": []
            }
          ]
        }
      ]
    },
    "debit": {
      "enabled": true,
      "brands": [
        {
          "enabled": true,
          "brand": "VISA",
          "currencies": ["BRL"],
          "threeds": true
        },
        {
          "enabled": true,
          "brand": "MASTERCARD",
          "currencies": ["BRL"],
          "threeds": true
        }
      ]
    },
    "bankslip": {
      "enabled": true
    },
    "instant_payment": {
      "enabled": true
    }
  },
  "status": "ACTIVE",
  "created_at": "2026-06-04T12:00:00.000Z",
  "updated_at": "2026-06-04T12:00:00.000Z",
  "currency": "BRL"
}