Atualizar checkout link

curl --request PATCH \
  --url https://api.sandbox.z2pay.com/v1/checkout/links/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "slug": "<string>",
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "items": [],
  "paymentMethods": {},
  "splits": [
    {
      "recipientId": "<string>",
      "percentage": 50.005,
      "liable": true
    }
  ],
  "branding": {
    "primaryColor": "<string>",
    "logoUrl": "<string>",
    "merchantName": "<string>",
    "faviconUrl": "<string>",
    "coverUrl": "<string>"
  },
  "subscription": {
    "planId": "<string>",
    "currency": "BRL",
    "trialDays": 182,
    "maxCycles": 1,
    "collectionTiming": "prepaid",
    "metadata": {},
    "itemCovers": {},
    "maxEnrollmentInstallments": 1
  },
  "requiredFields": [],
  "customFields": [
    {
      "key": "<string>",
      "label": "<string>",
      "options": [
        "<string>"
      ],
      "required": true
    }
  ],
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "metadata": {},
  "expirationMinutes": 21602
}
'

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    slug: '<string>',
    mode: 'payment',
    currency: 'BRL',
    locale: 'pt-BR',
    items: [],
    paymentMethods: {},
    splits: [{recipientId: '<string>', percentage: 50.005, liable: true}],
    branding: {
      primaryColor: '<string>',
      logoUrl: '<string>',
      merchantName: '<string>',
      faviconUrl: '<string>',
      coverUrl: '<string>'
    },
    subscription: {
      planId: '<string>',
      currency: 'BRL',
      trialDays: 182,
      maxCycles: 1,
      collectionTiming: 'prepaid',
      metadata: {},
      itemCovers: {},
      maxEnrollmentInstallments: 1
    },
    requiredFields: [],
    customFields: [{key: '<string>', label: '<string>', options: ['<string>'], required: true}],
    successUrl: '<string>',
    cancelUrl: '<string>',
    metadata: {},
    expirationMinutes: 21602
  })
};

fetch('https://api.sandbox.z2pay.com/v1/checkout/links/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.z2pay.com/v1/checkout/links/{id}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "slug": "<string>",
    "mode": "payment",
    "currency": "BRL",
    "locale": "pt-BR",
    "items": [],
    "paymentMethods": {},
    "splits": [
        {
            "recipientId": "<string>",
            "percentage": 50.005,
            "liable": True
        }
    ],
    "branding": {
        "primaryColor": "<string>",
        "logoUrl": "<string>",
        "merchantName": "<string>",
        "faviconUrl": "<string>",
        "coverUrl": "<string>"
    },
    "subscription": {
        "planId": "<string>",
        "currency": "BRL",
        "trialDays": 182,
        "maxCycles": 1,
        "collectionTiming": "prepaid",
        "metadata": {},
        "itemCovers": {},
        "maxEnrollmentInstallments": 1
    },
    "requiredFields": [],
    "customFields": [
        {
            "key": "<string>",
            "label": "<string>",
            "options": ["<string>"],
            "required": True
        }
    ],
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "metadata": {},
    "expirationMinutes": 21602
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

{
  "id": "chk_byd8p3p79re859jpkmr0j65n3",
  "slug": "plano-pro-mensal",
  "status": "active",
  "mode": "subscription",
  "currency": "BRL",
  "locale": "pt-BR",
  "name": "Plano Pro Mensal",
  "description": "Assinatura mensal do plano Pro",
  "sellable": true,
  "config": {
    "items": [
      {
        "name": "Plano Pro",
        "quantity": 1,
        "unitAmount": 9900,
        "chargeType": "recurring"
      }
    ],
    "paymentMethods": {
      "card": {
        "enabled": true
      },
      "pix": {
        "enabled": true
      }
    },
    "subscription": {
      "planId": "plan_edz8m3vbxbvobrom0qlxbq68h",
      "recurrence": {
        "interval": 1,
        "unit": "month"
      },
      "currency": "BRL",
      "trialDays": 7,
      "collectionTiming": "prepaid"
    }
  },
  "requiredFields": [
    "email",
    "document",
    "phone"
  ],
  "customFields": null,
  "successUrl": "https://app.com/welcome",
  "cancelUrl": null,
  "metadata": null,
  "expirationMinutes": 1440,
  "createdAt": "2025-06-20T09:00:00.000Z",
  "updatedAt": "2025-06-29T13:45:30.000Z",
  "url": "https://pay.z2pay.com/c/plano-pro-mensal"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      {
        "path": "status",
        "message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
      },
      {
        "path": "startDate",
        "message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Forbidden — insufficient permissions"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Checkout link not found"
  }
}

{
  "error": "A request with this idempotency key is already being processed"
}

{
  "error": "Idempotency key already used with a different request body"
}

PATCH

checkout

links

{id}

Atualizar checkout link

curl --request PATCH \
  --url https://api.sandbox.z2pay.com/v1/checkout/links/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "slug": "<string>",
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "items": [],
  "paymentMethods": {},
  "splits": [
    {
      "recipientId": "<string>",
      "percentage": 50.005,
      "liable": true
    }
  ],
  "branding": {
    "primaryColor": "<string>",
    "logoUrl": "<string>",
    "merchantName": "<string>",
    "faviconUrl": "<string>",
    "coverUrl": "<string>"
  },
  "subscription": {
    "planId": "<string>",
    "currency": "BRL",
    "trialDays": 182,
    "maxCycles": 1,
    "collectionTiming": "prepaid",
    "metadata": {},
    "itemCovers": {},
    "maxEnrollmentInstallments": 1
  },
  "requiredFields": [],
  "customFields": [
    {
      "key": "<string>",
      "label": "<string>",
      "options": [
        "<string>"
      ],
      "required": true
    }
  ],
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "metadata": {},
  "expirationMinutes": 21602
}
'

const options = {
  method: 'PATCH',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    description: '<string>',
    slug: '<string>',
    mode: 'payment',
    currency: 'BRL',
    locale: 'pt-BR',
    items: [],
    paymentMethods: {},
    splits: [{recipientId: '<string>', percentage: 50.005, liable: true}],
    branding: {
      primaryColor: '<string>',
      logoUrl: '<string>',
      merchantName: '<string>',
      faviconUrl: '<string>',
      coverUrl: '<string>'
    },
    subscription: {
      planId: '<string>',
      currency: 'BRL',
      trialDays: 182,
      maxCycles: 1,
      collectionTiming: 'prepaid',
      metadata: {},
      itemCovers: {},
      maxEnrollmentInstallments: 1
    },
    requiredFields: [],
    customFields: [{key: '<string>', label: '<string>', options: ['<string>'], required: true}],
    successUrl: '<string>',
    cancelUrl: '<string>',
    metadata: {},
    expirationMinutes: 21602
  })
};

fetch('https://api.sandbox.z2pay.com/v1/checkout/links/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.z2pay.com/v1/checkout/links/{id}"

payload = {
    "name": "<string>",
    "description": "<string>",
    "slug": "<string>",
    "mode": "payment",
    "currency": "BRL",
    "locale": "pt-BR",
    "items": [],
    "paymentMethods": {},
    "splits": [
        {
            "recipientId": "<string>",
            "percentage": 50.005,
            "liable": True
        }
    ],
    "branding": {
        "primaryColor": "<string>",
        "logoUrl": "<string>",
        "merchantName": "<string>",
        "faviconUrl": "<string>",
        "coverUrl": "<string>"
    },
    "subscription": {
        "planId": "<string>",
        "currency": "BRL",
        "trialDays": 182,
        "maxCycles": 1,
        "collectionTiming": "prepaid",
        "metadata": {},
        "itemCovers": {},
        "maxEnrollmentInstallments": 1
    },
    "requiredFields": [],
    "customFields": [
        {
            "key": "<string>",
            "label": "<string>",
            "options": ["<string>"],
            "required": True
        }
    ],
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "metadata": {},
    "expirationMinutes": 21602
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

{
  "id": "chk_byd8p3p79re859jpkmr0j65n3",
  "slug": "plano-pro-mensal",
  "status": "active",
  "mode": "subscription",
  "currency": "BRL",
  "locale": "pt-BR",
  "name": "Plano Pro Mensal",
  "description": "Assinatura mensal do plano Pro",
  "sellable": true,
  "config": {
    "items": [
      {
        "name": "Plano Pro",
        "quantity": 1,
        "unitAmount": 9900,
        "chargeType": "recurring"
      }
    ],
    "paymentMethods": {
      "card": {
        "enabled": true
      },
      "pix": {
        "enabled": true
      }
    },
    "subscription": {
      "planId": "plan_edz8m3vbxbvobrom0qlxbq68h",
      "recurrence": {
        "interval": 1,
        "unit": "month"
      },
      "currency": "BRL",
      "trialDays": 7,
      "collectionTiming": "prepaid"
    }
  },
  "requiredFields": [
    "email",
    "document",
    "phone"
  ],
  "customFields": null,
  "successUrl": "https://app.com/welcome",
  "cancelUrl": null,
  "metadata": null,
  "expirationMinutes": 1440,
  "createdAt": "2025-06-20T09:00:00.000Z",
  "updatedAt": "2025-06-29T13:45:30.000Z",
  "url": "https://pay.z2pay.com/c/plano-pro-mensal"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      {
        "path": "status",
        "message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
      },
      {
        "path": "startDate",
        "message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Forbidden — insufficient permissions"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Checkout link not found"
  }
}

{
  "error": "A request with this idempotency key is already being processed"
}

{
  "error": "Idempotency key already used with a different request body"
}

PATCH /checkout/links/{id} Faz parte do recurso Links — o conceito e os estados estão lá. Todos os campos são opcionais: só o que você envia muda. A resposta é 200 com o Link inteiro, já atualizado.

A mudança não alcança Sessions já materializadas. Elas guardam o snapshot do momento em que nasceram — quem abriu a página antes da sua edição paga o preço antigo, e isso é intencional. O novo valor só vale para Sessions futuras.

Não dá para reativar um Link arquivado por aqui. O corpo não aceita status; pelo painel dá, pela integração não. Veja Arquivar.

Omitir e enviar null são coisas diferentes. Campo ausente fica como está; null explícito apaga. É a única forma de remover um slug, um successUrl ou uma description já gravados. Vale para name, description, slug, successUrl, cancelUrl, metadata, requiredFields, customFields e expirationMinutes.

Trocar o slug revalida a unicidade global. Se o novo já pertence a outro Link — de qualquer conta —, a resposta é 409 com key: "errors.checkout.slug_taken". Reenviar o mesmo slug não dispara a checagem.

Endpoint idempotente. Veja Convenções.

Exemplo

curl -X PATCH https://api.sandbox.z2pay.com/v1/checkout/links/chk_byd8p3p79re859jpkmr0j65n3 \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "name": "Curso de Backend — vitalício", "quantity": 1, "unitAmount": 39900 }]
  }'

Resposta 200

{
  "id": "chk_byd8p3p79re859jpkmr0j65n3",
  "name": "Curso de Backend",
  "status": "active",
  "sellable": true,
  "config": {
    "items": [
      { "name": "Curso de Backend — vitalício", "quantity": 1, "unitAmount": 39900 }
    ],
    "...": "..."
  },
  "updatedAt": "2026-06-25T09:14:00.000Z",
  "url": "https://pay.sandbox.z2pay.com/c/chk_byd8p3p79re859jpkmr0j65n3"
}

Authorizations

x-api-key

string

header

required

API key unificada (z2_{live|test}{sk|pk}...) — secret (sk) para integração backend, publishable (pk) para uso no frontend público

Path Parameters

string

required

ID do CheckoutLink

Body

application/json

name

string | null

Nome do link de checkout.

Maximum string length: 255

description

string | null

Descrição exibida no checkout.

Maximum string length: 2000

slug

string | null

Slug único global usado na URL pública /c/{slug} (a-z, 0-9 e hífen).

Required string length: 3 - 100

Pattern: ^[a-z0-9-]+$

mode

enum<string>

default:payment

'payment' (default) para pagamento único; 'subscription' exige o objeto subscription populado.

Available options:

payment,

subscription

currency

enum<string>

default:BRL

Moeda da cobrança. Só BRL — os gateways liquidam em real.

Available options:

BRL

locale

enum<string>

default:pt-BR

Idioma do checkout (default 'pt-BR').

Available options:

pt-BR,

en-US,

es-ES

items

object[]

Itens do carrinho (unitAmount em centavos); ao menos 1 quando mode=payment.

Show child attributes

paymentMethods

object

Métodos de pagamento habilitados (card/pix/boleto/combined); ao menos um enabled.

Show child attributes

splits

object[] | null

Divisão de receita por percentual; a soma deve ser exatamente 100.

Show child attributes

branding

object | null

Customização visual do checkout.

Show child attributes

subscription

object | null

Configuração de recorrência; obrigatória (e exclusiva) quando mode=subscription.

Show child attributes

requiredFields

enum<string>[] | null

Campos do comprador exigidos no checkout (email, document, phone, address).

Available options:

email,

document,

phone,

address

customFields

object[] | null

Campos customizados do formulário (máx. 20).

Maximum array length: 20

Show child attributes

successUrl

string<uri> | null

URL de redirecionamento após pagamento aprovado.

Maximum string length: 2000

cancelUrl

string<uri> | null

URL de redirecionamento quando o comprador cancela.

Maximum string length: 2000

metadata

object | null

Metadados do seller (string → string), consultáveis no próprio link. Não são propagados à Transaction; para correlacionar vendas ao link nos webhooks, use o additionalInfo.checkoutLinkId da Transaction.

Show child attributes

expirationMinutes

integer | null

Expiração da sessão em minutos (5 a 43200 = 30 dias).

Required range: 5 <= x <= 43200

Response

Link atualizado

string

Identificador único do registro.

slug

string | null

Slug único global usado na URL pública /c/{slug}.

status

string

Estado atual do registro.

mode

string

Modo do checkout: 'payment' (pagamento único) ou 'subscription' (assinatura).

currency

string

Moeda no padrão ISO 4217 (ex.: BRL).

locale

string

Idioma do checkout (ex.: pt-BR, en-US, es-ES).

name

string | null

Nome de exibição do registro.

description

string | null

Descrição exibida no checkout.

sellable

boolean

Se o Link pode vender agora. É false quando um recebedor do splits, ou o dono da conta, não está ativo no PSP — o comprador vê uma página de indisponível. Independente do status.

config

object

Snapshot da configuração do checkout (formas de pagamento, itens e personalização visual).

requiredFields

string[] | null

Campos do comprador exigidos no checkout (ex.: email, document, phone, address).

customFields

object[] | null

Definições dos campos personalizados solicitados no checkout.

successUrl

string | null

URL de redirecionamento após o pagamento ser concluído com sucesso.

cancelUrl

string | null

URL de redirecionamento quando o comprador cancela o checkout.

metadata

object | null

Metadados livres (pares chave-valor) para uso do integrador; não afeta o processamento.

expirationMinutes

integer | null

Tempo de validade da sessão de checkout, em minutos.

createdAt

string<date-time>

Data e hora de criação do registro (ISO 8601).

updatedAt

string<date-time>

Data e hora da última atualização do registro (ISO 8601).

url

string

URL pública do checkout para o comprador finalizar o pagamento.

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Atualizar checkout link

Exemplo

Authorizations

Path Parameters

Body

Response

​Exemplo

Authorizations

Path Parameters

Body

Response

Exemplo