# Como criar um payment link Um payment link é uma URL compartilhável vinculada a um catálogo de produtos e a uma configuração de pagamento. Este guia mostra como criar um link usando o endpoint `POST /payment-links`. ## Como funciona Principais características: - **Chamada única de criação**: você define a identificação do link, o catálogo de produtos e os métodos de pagamento aceitos em uma única requisição; a resposta retorna o `link_id` e um `short_id`. - **URL compartilhável**: o `short_id` retornado é o identificador público usado na URL do link compartilhável. - **Catálogo de produtos**: um link `custom` (o tipo padrão) contém produtos predefinidos com valores fixos, portanto o array `products` é obrigatório. - **Métodos de pagamento configuráveis**: você habilita os métodos por link (crédito, débito, Boleto, Pix), sendo obrigatório pelo menos um entre `credit`, `debit`, `bankslip` ou `instant_payment`. - **Limites opcionais**: você pode definir uma `expiration` (máx. 1 ano) e um limite `max_orders` para o número de vendas antes da expiração do link. - **Entrega opcional**: quando `request_delivery_address` é `true`, o comprador é solicitado a informar um endereço de entrega, e `shipping_amount` passa a ser obrigatório. ## Antes de começar - Obtenha um token de acesso. Veja [Authentication](/pt/payment-link-api/first-step-plk/authentication-token-plk). - Tenha em mãos o `x-seller-id` do estabelecimento. - Se o link usar imagens de produto, faça o upload das imagens primeiro e guarde o `image_id`. Veja [Configure o payment link](/pt/payment-link-api/first-step-plk/configure-link-plk). ## Monte a requisição Endpoint| ---| `POST /payment-links` **Campos obrigatórios** | Campo | Tipo | Descrição | Exemplo | | --- | --- | --- | --- | | `label` | string | Tag de identificação (6–36 caracteres) | `black-friday-2026`| | `payment` | object | Configuração de pagamento | --- | | `currency` | string | Moeda do país | `BRL`, `CLP` ou `MXN` | | `products.product_type` | string | Veja os valores válidos no modelo de dados de produtos | `physical_goods` | | `products.title` | string | Título do produto (máx: 128) | `Camiseta Oficial Getnet`| | `products.amount` | integer | Valor da compra (veja a nota sobre valores acima) | `15000`| **Campos condicionais** | Campo | Tipo | Descrição | Exemplo | | --- | --- | --- | --- | | `shipping_amount` | integer | Obrigatório quando `request_delivery_address=true`. Valor em formato inteiro (veja a nota na seção **Regras de preenchimento de campos**) | `500`| | `products` | array | Catálogo de produtos. Obrigatório para `custom` | --- | | `payment.credit.brands.brand`| Bandeira do cartão. Obrigatório quando `payment.credit.enabled=true`. | `VISA` | **Campos opcionais** | Campo | Tipo | Descrição | Exemplo | | --- | --- | --- | --- | | `expiration` | string | Data de expiração. Máximo 1 ano | `2026-12-31T23:59:59` | | `max_orders` | integer | Número máximo de vendas antes da expiração (mín: 1) | `100`| | `type` | string | Tipo de link | `custom` | | `request_delivery_address` | boolean | Solicitar endereço de entrega | `true`ou `false`| | `products.description` | string | Descrição do produto (máx: 1024) | `Camiseta 100% algodão, tamanho M`| | `products.order_prefix` | string | Prefixo do ID do pedido (máx: 10) | `BF2026`| | `products.quantity` | integer | Quantidade (padrão: 1) | `2`| | `products.image_id` | string | Referência da imagem enviada via `POST /payment-links/products/images` | `6697e354-ab4a-11eb-bcbc-0242ac130002`| | `payment.credit` | object | Configuração de crédito | --- | | `payment.debit` | object | Configuração de débito com | --- | | `payment.bankslip` | object | Boleto (somente Brasil) | --- | | `payment.instant_payment` | object | Pix (somente Brasil) | --- | **Valores dos campos** | Campo | Valor | ---|---| `product_type`| `cash_carry`, `digital_content`, `digital_goods`, `digital_physical`, `gift_card`, `physical_goods`, `renew_subs`, `shareware` ou `service`| `brand` | `VISA`, `MASTERCARD`, `AMEX`, `ELO`, `HIPERCARD` ou `CARNET`| #### Regras de preenchimento de campos: * **Valores:** informe o valor em formato inteiro, em que os últimos 2 dígitos representam os centavos. Para países em que os centavos não se aplicam, preencha o valor com 2 zeros à direita (ex.: \$150 → envie `15000`). * Pelo menos um dos campos `credit`, `debit`, `bankslip` ou `instant_payment` deve estar presente. Para a estrutura detalhada de crédito, débito, bandeiras de cartão e parcelas, veja [Configure o payment link](/pt/payment-link-api/first-step-plk/configure-link-plk). #### Exemplo de requisição ```json 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" }' ``` #### Exemplo de resposta O `short_id` retornado é o identificador público usado na URL do link compartilhável. ```json { "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" } ``` ## Próximos passos - [Como gerenciar o ciclo de vida de um link](/pt/payment-link-api/payment-guides-plk/howto-manage-life-cicle-plk) - [Como consultar e listar ordens de pagamento](/pt/payment-link-api/payment-guides-plk/howto-retrieve-list-payment-orders-plk)