Como gerenciar o ciclo de vida de um link

Um payment link possui três status possíveis: ACTIVE, INACTIVE e EXPIRED. Este guia mostra como transitar entre eles e como atualizar um link existente.

Transições de status

De	Para	Gatilho
—	`ACTIVE`	Link de pagamento criado
`ACTIVE`	`INACTIVE`	Seller desativa via PATCH
`ACTIVE`	`EXPIRED`	Data de expiração atingida (automático)
`ACTIVE`	`EXPIRED`	Limite de `max_orders` atingido (esgotado)
`INACTIVE`	`ACTIVE`	Seller reativa via PATCH
`EXPIRED`	—	Terminal pela transição automática — ver nota abaixo

Reativando um link expirado: um link em EXPIRED pode voltar a ficar ativo atualizando a data de expiração para uma data futura e definindo o status como ativo. Isso pode ser feito tanto pela rota PUT quanto pela rota PATCH.

Como funciona

Principais características:

Três status: um link fica ACTIVE quando é criado, INACTIVE quando o seller o desativa, e EXPIRED quando sua data de expiração é atingida ou seu limite de max_orders é atingido (esgotado).
PATCH para status ou expiração: use PATCH /payment-links/{link_id} para desativar, reativar ou alterar a data de expiração sem reenviar o link inteiro.
PUT para substituição completa: use PUT /payment-links/{link_id} para substituir o link inteiro; todos os campos do body são substituídos, usando a mesma estrutura do POST /payment-links.
GET para inspecionar: consulte o estado atual de um link a qualquer momento; um link inexistente retorna 404 (payment_link_not_found).
Reativando um link expirado: um link EXPIRED pode voltar a ficar ativo atualizando a expiração para uma data futura e definindo o status como ativo, via PUT ou PATCH.

Antes de começar

Obtenha um token de acesso. Veja Authentication.
Tenha o link_id do link que deseja gerenciar.

Desativar ou reativar um link (PATCH)

Use PATCH para atualizar o status ou a expiração de um link.

Endpoint
`PATCH /payment-links/{link_id}`

Campo	Tipo	Obrigatório	Descrição
`status`	string	Não	Novo status: `ACTIVE` ou `INACTIVE`
`expiration`	string	Não	Nova data de expiração

Exemplo de requisição — desativar

curl -X PATCH "${API_URL}/payment-links/${LINK_ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "x-seller-id: ${SELLER_ID}" \
    -H "country: BR" \
    -H "tenant: santander" \
    -H "Content-Type: application/json" \
    -d '{ "status": "INACTIVE" }'

Exemplo de requisição — reativar

curl -X PATCH "${API_URL}/payment-links/${LINK_ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "x-seller-id: ${SELLER_ID}" \
    -H "country: BR" \
    -H "tenant: santander" \
    -H "Content-Type: application/json" \
    -d '{ "status": "ACTIVE" }'

Uma resposta bem-sucedida retorna 200 OK com o link completo atualizado.

Atualizar um link por completo (PUT)

Use PUT para uma substituição completa do link.

Endpoint
`PUT /payment-links/{link_id}`

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` ou `MXN`
`products.product_type`	string	Ver 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 (ver nota sobre valores acima)	`15000`

Campos opcionais

Campo	Tipo	Descrição	Exemplo
`status`	string	Status do link	`ACTIVE` ou `INACTIVE`
`expiration`	string	Nova data de expiração	`2026-12-31T23:59:59`

Exemplo de requisição

curl https://api-sbx.pre.globalgetnet.com/dpy/payment-link/v1/payment-links/9e5dcedc-1e5f-4e85-9b64-4d0b43d98c82 \
  --request PUT \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
  "label": "black-friday-2026",
  "expiration": "2026-12-31T23:59:59",
  "max_orders": 100,
  "type": "custom",
  "request_delivery_address": false,
  "shipping_amount": 500,
  "products": [
    {
      "product_type": "physical_goods",
      "title": "Camiseta Oficial Getnet",
      "image_id": "6697e354-ab4a-11eb-bcbc-0242ac130002",
      "description": "Camiseta 100% algodão, tamanho M",
      "quantity": 2,
      "order_prefix": "BF2026",
      "amount": 9990,
      "propertyName*": "anything"
    }
  ],
  "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,6,9,12],
              "installments_with_interest": [6,9,12],
              "installments_with_increase": [
                {
                  "installments": [3,6,12],
                  "rate": 1.5,
                  "propertyName*": "anything"
                }
              ],
              "propertyName*": "anything"
            }
          ],
          "propertyName*": "anything"
        }
      ],
      "propertyName*": "anything"
    },
    "debit": {
      "enabled": true,
      "brands": [
        {
          "enabled": true,
          "brand": "VISA",
          "currencies": [
            "BRL"
          ],
          "threeds": true,
          "propertyName*": "anything"
        }
      ],
      "propertyName*": "anything"
    },
    "bankslip": {
      "enabled": true,
      "propertyName*": "anything"
    },
    "instant_payment": {
      "enabled": true,
      "propertyName*": "anything"
    },
    "google_pay": {
      "enabled": true,
      "propertyName*": "anything"
    },
    "apple_pay": {
      "enabled": true,
      "propertyName*": "anything"
    },
    "c2p_master": {
      "enabled": false,
      "propertyName*": "anything"
    },
    "propertyName*": "anything"
  },
  "currency": "BRL",
  "propertyName*": "anything",
  "status": "ACTIVE"
}'

O corpo da requisição usa a mesma estrutura do POST /payment-links. Todos os campos do body são substituídos.

Veja Como criar um payment link para a estrutura dos campos.

Uma resposta bem-sucedida retorna 200 OK com o link completo atualizado.

Consultar um link existente

Para ver o estado atual de um link:

curl -X GET "${API_URL}/payment-links/${LINK_ID}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "x-seller-id: ${SELLER_ID}" \
    -H "country: BR" \
    -H "tenant: santander"

Retorna 200 OK com o link completo. Um link inexistente retorna 404 (payment_link_not_found).

Próximos passos

Como consultar e listar ordens de pagamento