Criar venda rápida

curl --request POST \
  --url https://api.sandbox.z2pay.com/v1/checkout/charges \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "items": [
    {
      "name": "<string>",
      "quantity": 2,
      "unitAmount": 2,
      "description": "<string>",
      "imageUrl": "<string>",
      "metadata": {}
    }
  ],
  "paymentMethods": {},
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "splits": [
    {
      "recipientId": "<string>",
      "percentage": 50.005,
      "liable": true
    }
  ],
  "branding": {
    "primaryColor": "<string>",
    "logoUrl": "<string>",
    "merchantName": "<string>",
    "faviconUrl": "<string>",
    "coverUrl": "<string>"
  },
  "customer": {
    "name": "<string>",
    "email": "jsmith@example.com",
    "document": "<string>",
    "phone": "<string>",
    "address": {
      "zipCode": "<string>",
      "street": "<string>",
      "number": "<string>",
      "complement": "<string>",
      "neighborhood": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "BR"
    }
  },
  "requiredFields": [],
  "customFields": [
    {
      "key": "<string>",
      "label": "<string>",
      "options": [
        "<string>"
      ],
      "required": true
    }
  ],
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "description": "<string>",
  "metadata": {},
  "expirationMinutes": 21602
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        name: '<string>',
        quantity: 2,
        unitAmount: 2,
        description: '<string>',
        imageUrl: '<string>',
        metadata: {}
      }
    ],
    paymentMethods: {},
    mode: 'payment',
    currency: 'BRL',
    locale: 'pt-BR',
    splits: [{recipientId: '<string>', percentage: 50.005, liable: true}],
    branding: {
      primaryColor: '<string>',
      logoUrl: '<string>',
      merchantName: '<string>',
      faviconUrl: '<string>',
      coverUrl: '<string>'
    },
    customer: {
      name: '<string>',
      email: 'jsmith@example.com',
      document: '<string>',
      phone: '<string>',
      address: {
        zipCode: '<string>',
        street: '<string>',
        number: '<string>',
        complement: '<string>',
        neighborhood: '<string>',
        city: '<string>',
        state: '<string>',
        country: 'BR'
      }
    },
    requiredFields: [],
    customFields: [{key: '<string>', label: '<string>', options: ['<string>'], required: true}],
    successUrl: '<string>',
    cancelUrl: '<string>',
    description: '<string>',
    metadata: {},
    expirationMinutes: 21602
  })
};

fetch('https://api.sandbox.z2pay.com/v1/checkout/charges', 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/charges"

payload = {
    "items": [
        {
            "name": "<string>",
            "quantity": 2,
            "unitAmount": 2,
            "description": "<string>",
            "imageUrl": "<string>",
            "metadata": {}
        }
    ],
    "paymentMethods": {},
    "mode": "payment",
    "currency": "BRL",
    "locale": "pt-BR",
    "splits": [
        {
            "recipientId": "<string>",
            "percentage": 50.005,
            "liable": True
        }
    ],
    "branding": {
        "primaryColor": "<string>",
        "logoUrl": "<string>",
        "merchantName": "<string>",
        "faviconUrl": "<string>",
        "coverUrl": "<string>"
    },
    "customer": {
        "name": "<string>",
        "email": "jsmith@example.com",
        "document": "<string>",
        "phone": "<string>",
        "address": {
            "zipCode": "<string>",
            "street": "<string>",
            "number": "<string>",
            "complement": "<string>",
            "neighborhood": "<string>",
            "city": "<string>",
            "state": "<string>",
            "country": "BR"
        }
    },
    "requiredFields": [],
    "customFields": [
        {
            "key": "<string>",
            "label": "<string>",
            "options": ["<string>"],
            "required": True
        }
    ],
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "description": "<string>",
    "metadata": {},
    "expirationMinutes": 21602
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "cs_02f232c4dcf8eec4c29e0f3748476d1339b63c0e7ffab1dc",
  "linkId": null,
  "status": "created",
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "config": {
    "paymentMethods": {
      "card": {
        "enabled": true,
        "installments": {
          "maxInstallments": 12
        }
      },
      "pix": {
        "enabled": true,
        "expiresIn": 3600
      },
      "boleto": {
        "enabled": false
      }
    },
    "description": "Consultoria avulsa"
  },
  "customer": {
    "name": "Maria Souza",
    "email": "maria.souza@example.com",
    "document": "12345678909",
    "documentType": "cpf"
  },
  "customFieldValues": null,
  "paymentMethodSelected": null,
  "subtotal": 50000,
  "discountTotal": 0,
  "amount": 50000,
  "discounts": [],
  "paymentAttempts": 0,
  "transactionId": null,
  "subscriptionId": null,
  "metadata": null,
  "createdAt": "2025-06-29T13:45:30.000Z",
  "updatedAt": "2025-06-29T13:45:30.000Z",
  "openedAt": null,
  "paidAt": null,
  "canceledAt": null,
  "expiresAt": "2025-06-30T13:45:30.000Z",
  "url": "https://checkout.z2pay.com.br/c/s/cs_02f232c4dcf8eec4c29e0f3748476d1339b63c0e7ffab1dc"
}

{
  "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": "A request with this idempotency key is already being processed"
}

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

POST

checkout

charges

Criar venda rápida

curl --request POST \
  --url https://api.sandbox.z2pay.com/v1/checkout/charges \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "items": [
    {
      "name": "<string>",
      "quantity": 2,
      "unitAmount": 2,
      "description": "<string>",
      "imageUrl": "<string>",
      "metadata": {}
    }
  ],
  "paymentMethods": {},
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "splits": [
    {
      "recipientId": "<string>",
      "percentage": 50.005,
      "liable": true
    }
  ],
  "branding": {
    "primaryColor": "<string>",
    "logoUrl": "<string>",
    "merchantName": "<string>",
    "faviconUrl": "<string>",
    "coverUrl": "<string>"
  },
  "customer": {
    "name": "<string>",
    "email": "jsmith@example.com",
    "document": "<string>",
    "phone": "<string>",
    "address": {
      "zipCode": "<string>",
      "street": "<string>",
      "number": "<string>",
      "complement": "<string>",
      "neighborhood": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "BR"
    }
  },
  "requiredFields": [],
  "customFields": [
    {
      "key": "<string>",
      "label": "<string>",
      "options": [
        "<string>"
      ],
      "required": true
    }
  ],
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "description": "<string>",
  "metadata": {},
  "expirationMinutes": 21602
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        name: '<string>',
        quantity: 2,
        unitAmount: 2,
        description: '<string>',
        imageUrl: '<string>',
        metadata: {}
      }
    ],
    paymentMethods: {},
    mode: 'payment',
    currency: 'BRL',
    locale: 'pt-BR',
    splits: [{recipientId: '<string>', percentage: 50.005, liable: true}],
    branding: {
      primaryColor: '<string>',
      logoUrl: '<string>',
      merchantName: '<string>',
      faviconUrl: '<string>',
      coverUrl: '<string>'
    },
    customer: {
      name: '<string>',
      email: 'jsmith@example.com',
      document: '<string>',
      phone: '<string>',
      address: {
        zipCode: '<string>',
        street: '<string>',
        number: '<string>',
        complement: '<string>',
        neighborhood: '<string>',
        city: '<string>',
        state: '<string>',
        country: 'BR'
      }
    },
    requiredFields: [],
    customFields: [{key: '<string>', label: '<string>', options: ['<string>'], required: true}],
    successUrl: '<string>',
    cancelUrl: '<string>',
    description: '<string>',
    metadata: {},
    expirationMinutes: 21602
  })
};

fetch('https://api.sandbox.z2pay.com/v1/checkout/charges', 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/charges"

payload = {
    "items": [
        {
            "name": "<string>",
            "quantity": 2,
            "unitAmount": 2,
            "description": "<string>",
            "imageUrl": "<string>",
            "metadata": {}
        }
    ],
    "paymentMethods": {},
    "mode": "payment",
    "currency": "BRL",
    "locale": "pt-BR",
    "splits": [
        {
            "recipientId": "<string>",
            "percentage": 50.005,
            "liable": True
        }
    ],
    "branding": {
        "primaryColor": "<string>",
        "logoUrl": "<string>",
        "merchantName": "<string>",
        "faviconUrl": "<string>",
        "coverUrl": "<string>"
    },
    "customer": {
        "name": "<string>",
        "email": "jsmith@example.com",
        "document": "<string>",
        "phone": "<string>",
        "address": {
            "zipCode": "<string>",
            "street": "<string>",
            "number": "<string>",
            "complement": "<string>",
            "neighborhood": "<string>",
            "city": "<string>",
            "state": "<string>",
            "country": "BR"
        }
    },
    "requiredFields": [],
    "customFields": [
        {
            "key": "<string>",
            "label": "<string>",
            "options": ["<string>"],
            "required": True
        }
    ],
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "description": "<string>",
    "metadata": {},
    "expirationMinutes": 21602
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "cs_02f232c4dcf8eec4c29e0f3748476d1339b63c0e7ffab1dc",
  "linkId": null,
  "status": "created",
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "config": {
    "paymentMethods": {
      "card": {
        "enabled": true,
        "installments": {
          "maxInstallments": 12
        }
      },
      "pix": {
        "enabled": true,
        "expiresIn": 3600
      },
      "boleto": {
        "enabled": false
      }
    },
    "description": "Consultoria avulsa"
  },
  "customer": {
    "name": "Maria Souza",
    "email": "maria.souza@example.com",
    "document": "12345678909",
    "documentType": "cpf"
  },
  "customFieldValues": null,
  "paymentMethodSelected": null,
  "subtotal": 50000,
  "discountTotal": 0,
  "amount": 50000,
  "discounts": [],
  "paymentAttempts": 0,
  "transactionId": null,
  "subscriptionId": null,
  "metadata": null,
  "createdAt": "2025-06-29T13:45:30.000Z",
  "updatedAt": "2025-06-29T13:45:30.000Z",
  "openedAt": null,
  "paidAt": null,
  "canceledAt": null,
  "expiresAt": "2025-06-30T13:45:30.000Z",
  "url": "https://checkout.z2pay.com.br/c/s/cs_02f232c4dcf8eec4c29e0f3748476d1339b63c0e7ffab1dc"
}

{
  "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": "A request with this idempotency key is already being processed"
}

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

POST /checkout/charges Faz parte do recurso Vendas rápidas — a relação com Link e Session está lá. Cria a compra com a configuração inline: itens, métodos, branding e splits vão no topo do corpo, com o mesmo formato que o Link aceita. A resposta é 201 com a Session (linkId: null) e a url para você enviar pelo seu canal. O objeto customer é opcional e serve para pré-preencher os dados na página — o comprador ainda pode corrigi-los, e os requiredFields continuam valendo na confirmação.

mode: "subscription" é recusado com 400. Recorrência só nasce de um Link de assinatura.

null explícito é recusado aqui. No Link, vários campos aceitam null; no corpo da venda rápida, não. Campo que você não vai usar deve ser omitido. É a diferença que mais derruba quem copia a configuração de um Link direto para cá — veja o clean() no exemplo abaixo.

Valores são inteiros em centavos, e o split exige soma 100 com exatamente um liable: true — as mesmas regras do Link. Veja Criar checkout link.

Endpoint idempotente. Envie Idempotency-Key para que um retry por timeout não crie duas cobranças — sem ele, a segunda chamada gera outro cs_ e outra URL. Veja Convenções.

Exemplo

curl -X POST https://api.sandbox.z2pay.com/v1/checkout/charges \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "items": [{ "name": "Consultoria 1h", "quantity": 1, "unitAmount": 30000 }],
    "paymentMethods": { "pix": { "enabled": true } },
    "customer": { "name": "Cliente X", "email": "x@example.com" }
  }'

Resposta 201

{
  "id": "cs_50b0abc54b632e7c57de3a73815413ace1d545dcd16da95c",
  "linkId": null,
  "status": "created",
  "amount": 30000,
  "currency": "BRL",
  "customer": { "name": "Cliente X", "email": "x@example.com" },
  "transactionId": null,
  "createdAt": "2026-06-24T12:00:00.000Z",
  "expiresAt": "2026-06-25T12:00:00.000Z",
  "url": "https://pay.sandbox.z2pay.com/c/cs_50b0abc54b632e7c57de3a73815413ace1d545dcd16da95c"
}

Espelhar a configuração de um Link

Já tem um Link com branding, métodos e splits ajustados e quer disparar uma cobrança individual com a mesma cara, mas com outro carrinho? Leia o Link, mova o config para o topo do corpo e poste aqui. É o mesmo caminho do “Duplicar como venda rápida” do painel.

A venda rápida resultante é independente: ela copia a configuração no momento da criação, não cria vínculo. Editar o Link depois não a alcança. Se você quer o vínculo vivo, compartilhe a URL do próprio Link.

Leia o Link

GET /checkout/links/{id}. A resposta traz items, paymentMethods, splits e branding dentro de config; o resto já vem no topo.

Mova o config para o topo

Os quatro campos aninhados sobem um nível. locale, currency, requiredFields, customFields, successUrl, cancelUrl, description, metadata e expirationMinutes são copiados direto.

Troque o que é seu

items vem do seu carrinho, não do Link. Omita name, slug e qualquer configuração de assinatura. Envie mode: "payment".

Poste

POST /checkout/charges → 201 com o cs_ e a url.

Quatro coisas não atravessam: mode: "subscription" e o objeto subscription (recusados); name e slug (são identidade do template); qualquer null (omita em vez de enviar); e chargeType recurring/activation nos itens — em pagamento único todo item é cobrança única.

const API = "https://api.sandbox.z2pay.com/v1";
const KEY = "SUA_CHAVE_DE_SANDBOX";

const link = await fetch(`${API}/checkout/links/${linkId}`, {
  headers: { "x-api-key": KEY },
}).then((r) => r.json());

const { paymentMethods, splits, branding } = link.config;

const body = clean({
  mode: "payment",
  currency: link.currency,
  locale: link.locale,
  items: [{ name: "Pedido #4821", quantity: 1, unitAmount: 34780 }],
  paymentMethods,
  splits,
  branding,
  requiredFields: link.requiredFields,
  customFields: link.customFields,
  successUrl: link.successUrl,
  cancelUrl: link.cancelUrl,
  description: link.description,
  metadata: link.metadata,
  expirationMinutes: link.expirationMinutes,
  customer: { email: "cliente@example.com" },
});

const charge = await fetch(`${API}/checkout/charges`, {
  method: "POST",
  headers: { "x-api-key": KEY, "Content-Type": "application/json" },
  body: JSON.stringify(body),
}).then((r) => r.json());

// Remove as chaves nulas: o corpo da venda rápida recusa `null` explícito.
function clean(obj) {
  return Object.fromEntries(Object.entries(obj).filter(([, v]) => v != null));
}

As URLs de mídia (branding.logoUrl, faviconUrl, coverUrl e items[].imageUrl) copiam verbatim — são endereços públicos de CDN, sem novo upload.

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

Body

application/json

items

object[]

required

Itens da cobrança (unitAmount em centavos); ao menos 1 é obrigatório.

Minimum array length: 1

Show child attributes

paymentMethods

object

required

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

Show child attributes

mode

enum<string>

default:payment

Apenas 'payment' é aceito na venda rápida ad-hoc — 'subscription' é rejeitado (recorrência exige Link).

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

splits

object[]

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

Show child attributes

branding

object

Customização visual do checkout.

Show child attributes

customer

object

Pré-preenchimento dos dados do comprador.

Show child attributes

requiredFields

enum<string>[]

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

Available options:

email,

document,

phone,

address

customFields

object[]

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

Maximum array length: 20

Show child attributes

successUrl

string<uri>

URL de redirecionamento após pagamento aprovado.

Maximum string length: 2000

cancelUrl

string<uri>

URL de redirecionamento quando o comprador cancela.

Maximum string length: 2000

description

string

Descrição da venda rápida (exibida na listagem).

Maximum string length: 2000

metadata

object

Metadados do seller (string → string); propagados ao additionalInfo da Transaction e dos webhooks.

Show child attributes

expirationMinutes

integer

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

Required range: 5 <= x <= 43200

Response

Venda rápida criada

string

Identificador único do registro.

linkId

string | null

Identificador do link de checkout que originou o registro; nulo em sessões ad-hoc.

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).

config

object

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

customer

object | null

Dados do comprador (nome, e-mail, documento e demais informações).

customFieldValues

object | null

Valores preenchidos nos campos personalizados, indexados pela key de cada campo.

paymentMethodSelected

string | null

Forma de pagamento selecionada pelo comprador na sessão (ex.: credit_card, pix, boleto).

subtotal

integer

Soma dos itens antes dos descontos, em centavos.

discountTotal

integer

Total de descontos aplicados, em centavos.

amount

integer

Valor total a ser cobrado, em centavos.

discounts

object[] | null

Descontos aplicados ao valor da sessão.

paymentAttempts

integer

Quantidade de tentativas de pagamento realizadas na sessão.

transactionId

string | null

Identificador da transação gerada pelo pagamento da sessão; nulo até haver pagamento.

subscriptionId

string | null

Identificador da assinatura criada a partir da sessão; nulo até a ativação.

metadata

object | null

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

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).

openedAt

string<date-time> | null

Data e hora em que a sessão foi aberta pelo comprador (ISO 8601); nula se ainda não aberta.

paidAt

string<date-time> | null

Data e hora em que o pagamento foi confirmado (ISO 8601); nula se não pago.

canceledAt

string<date-time> | null

Data e hora do cancelamento (ISO 8601); nula se não cancelado.

expiresAt

string<date-time>

Data e hora de expiração (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

Criar venda rápida

Exemplo

Espelhar a configuração de um Link

Authorizations

Body

Response

​Exemplo

​Espelhar a configuração de um Link

Authorizations

Body

Response

Exemplo

Espelhar a configuração de um Link