> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar transação
> Cria uma transação com seus itens e pagamentos, cobrando na mesma requisição ou deixando a cobrança para depois.
`POST /transactions`
Faz parte do recurso [Transações](/pt-BR/transactions) — o conceito, o ciclo de vida e a
tabela de status estão lá.
Cria uma transação. São obrigatórios o **cliente**, o seu **código de referência**
(`referenceCode`), pelo menos um **item** e pelo menos um **pagamento**. O que decide se a cobrança
acontece agora ou depois não é a presença do `payments`, e sim a dos dados do meio de pagamento
dentro dele:
* **Com `creditCard`, `pix` ou `boleto`** → o pagamento é **cobrado imediatamente** no gateway. Para
cartão, os dados vão em `creditCard`; para Pix e boleto, os objetos `pix`/`boleto` são
**opcionais** e servem só para customizar a expiração. No Pix, o QR Code
(`pixUrl`/`pixCopyPaste`) já vem preenchido na **resposta síncrona** do `POST`.
* **Sem nenhum deles** → o pagamento nasce registrado e **não cobrado**, e a transação fica em
`pending`. Você cobra quando quiser, em
[`POST /transactions/:id/payments/process`](/pt-BR/payments/process). É o caminho para ter o
número do pedido antes de o comprador digitar o cartão.
**`payments` não aceita lista vazia.** A transação precisa nascer com pelo menos um pagamento,
ainda que sem os dados de cobrança. Não existe rota para acrescentar um pagamento a uma transação
já criada — sem nenhum, ela ficaria em `pending` para sempre, e a única saída seria criar outra.
Enviar `[]` ou omitir o campo resulta em `400`.
Endpoint idempotente. Envie o header `Idempotency-Key` (TTL de 7 dias) para garantir que reenvios
da mesma requisição não criem transações duplicadas. Veja [Convenções](/pt-BR/convencoes).
## Regras de negócio importantes
**`customer` e `customerId` são mutuamente exclusivos.** Envie **um dos dois** (obrigatório):
`customerId` para reusar um cliente já cadastrado, ou `customer` inline para criar/identificar o
cliente no ato. Enviar os dois, ou nenhum, resulta em `400`.
**A soma dos pagamentos deve bater com a soma dos itens.** Quando `payments` é enviado, a soma de
`payment.amount` precisa ser exatamente igual ao total dos itens
(`Σ item.amount × item.quantity`). Caso contrário, `400`. Todos os valores são **inteiros em
centavos**.
**Expiração de Pix e boleto tem default.** Sem `pix.expirationDate`, o QR Code vale **30
minutos**; sem `boleto.expirationDate`, o boleto vence em **3 dias**. Os dois objetos existem
só para mudar isso — o pagamento é processado com ou sem eles.
**O token do cartão muda de nome entre as APIs.** O [Tokenizer](/pt-BR/tokenizer) devolve o campo
como `tokenId`; aqui ele entra como `creditCard.token`, e no Checkout como `card.tokenId`. É o
mesmo valor — só o nome do campo acompanha o contexto.
**`statementDescriptor` é normalizado antes de ir para a fatura.** A criação aceita até 100
caracteres, mas o texto persistido e enviado à adquirente passa por três etapas: os acentos são
removidos (`é` → `e`), tudo que não for letra, número ou espaço **cai fora**, e o resultado é
cortado em **13 caracteres**. `"Café & Cia"` chega ao portador como `"Cafe Cia"`.
A limpeza não é preciosismo: a adquirente **recusa a cobrança inteira** se o descritor trouxer
caractere especial. Por isso o campo é saneado em vez de rejeitado — e por isso a resposta já o
devolve na forma final. Use um texto curto, sem acento e reconhecível na fatura.
**O endereço da compra volta para o cadastro do cliente.** Além de virar o `customerAddress`
congelado na transação, o `customer.address` informado aqui atualiza o cadastro — **campo a
campo**: valor preenchido substitui, valor vazio **não apaga** o que já estava lá. Um checkout que
pede só o CEP não zera rua, cidade e estado de quem já tinha endereço.
A atualização é best-effort: se falhar, a venda segue normalmente, porque a transação já guarda o
seu próprio snapshot.
## Exemplo: criar transação com Pix
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/transactions \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Idempotency-Key: pedido-2026-0001" \
-H "Content-Type: application/json" \
-d '{
"referenceCode": "pedido-2026-0001",
"customer": {
"name": "Maria Souza",
"email": "maria@example.com",
"type": "individual",
"document": "12345678909",
"documentType": "cpf",
"phone": "+5511999998888"
},
"items": [
{ "description": "Plano Pro (mensal)", "quantity": 1, "amount": 9990 }
],
"payments": [
{ "paymentMethod": "pix", "amount": 9990 }
]
}'
```
O item custa `9990` centavos (R\$ 99,90) e o pagamento soma `9990` — as somas batem, então a
requisição é válida.
```json theme={null}
{
"id": "txn_ebgsvfsb4151nmbgvj4sek6ol",
"referenceCode": "pedido-2026-0001",
"status": "waiting_payment",
"amount": 9990,
"currency": "BRL",
"customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
"payments": [
{
"id": "pay_kd6z67zbp52rgtg2idms96fhm",
"paymentMethod": "pix",
"status": "waiting_payment",
"amount": 9990,
"pixUrl": "https://pix.z2pay.com/qr/pay_kd6z67zbp52rgtg2idms96fhm/qr.png",
"pixCopyPaste": "00020126580014br.gov.bcb.pix0136f1d2...6304A1B2",
"expiresAt": "2026-06-24T12:30:00.000Z"
}
],
"items": [
{
"id": "item_s4206yea51f6fsiugybgb51sr",
"description": "Plano Pro (mensal)",
"quantity": 1,
"unitValue": 9990,
"amount": 9990
}
],
"createdAt": "2026-06-24T12:00:00.000Z"
}
```
Resposta `201 Created`. O exemplo de JSON é ilustrativo — confira os campos reais na resposta do seu ambiente.
O pagamento já volta com **`pixUrl`** (URL da imagem do QR Code) e **`pixCopyPaste`** (BR Code
copia-e-cola, EMV iniciando em `00020126...`) preenchidos na própria resposta síncrona do create —
é esse o dado que você exibe ao comprador. O status `waiting_payment` significa que o QR Code foi
emitido e aguarda o pagador; `expiresAt` reflete a expiração default de 30 minutos.
Na resposta, cada item traz **`unitValue`** (o valor unitário que você enviou em `items[].amount`)
e **`amount`** (o total da linha = `unitValue × quantity`). Com `quantity: 1` os dois coincidem;
no exemplo de cartão abaixo, com `quantity: 2`, o `amount` é o dobro do `unitValue`.
## Exemplo: criar e cobrar cartão com cartão tokenizado
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/transactions \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Idempotency-Key: pedido-2026-0002" \
-H "Content-Type: application/json" \
-d '{
"referenceCode": "pedido-2026-0002",
"customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
"items": [
{ "description": "Camiseta", "quantity": 2, "amount": 5000 }
],
"payments": [
{
"paymentMethod": "credit_card",
"amount": 10000,
"installments": 1,
"creditCard": {
"token": "tok_exemplo_sandbox",
"statementDescriptor": "MINHALOJA"
}
}
]
}'
```
**Um item** com valor unitário de `5000` centavos (R\$ 50,00) e `quantity: 2` → total de `10000`
centavos (R\$ 100,00); o pagamento soma `10000`. As somas batem. O cartão é
enviado como `token` (gerado pelo [Tokenizer](/pt-BR/tokenizer)) — nunca envie dados crus
do cartão para a API.
## OpenAPI
````yaml openapi/psp.json POST /transactions
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/transactions:
post:
tags:
- Transactions
summary: Criar transação
description: >-
Cria uma nova transação de pagamento. Suporta idempotência via header
Idempotency-Key (TTL 7 dias)
operationId: TransactionController_create
parameters:
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição (TTL 7 dias)
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
nullable: true
description: >-
ID de um cliente existente (mutuamente exclusivo com
customer).
customer:
type: object
properties:
name:
type: string
minLength: 2
description: Nome completo do cliente.
email:
type: string
format: email
description: E-mail do cliente.
type:
type: string
enum:
- individual
- company
description: >-
Tipo de cliente: individual (pessoa física) ou company
(pessoa jurídica).
document:
type: string
minLength: 6
description: Documento do cliente (CPF ou CNPJ, somente dígitos).
documentType:
type: string
enum:
- cpf
- cnpj
- passport
description: 'Tipo do documento do cliente: cpf ou cnpj.'
phone:
type: string
minLength: 1
description: >-
Telefone do cliente (formato E.164, ex.:
+5511987654321).
address:
type: object
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: Complemento do endereço (apartamento, bloco, sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
description: Endereço do cliente.
required:
- name
- email
- type
- document
- phone
description: >-
Dados do cliente inline (mutuamente exclusivo com
customerId).
currency:
type: string
enum:
- BRL
description: >-
Código de moeda ISO 4217. Hoje o único valor aceito é 'BRL',
que também é o padrão quando o campo é omitido.
referenceCode:
type: string
minLength: 1
maxLength: 255
description: >-
Código de referência do integrador (1–255 chars); sem
validação de unicidade — pode repetir entre transações.
items:
type: array
items:
type: object
properties:
code:
type: string
minLength: 1
maxLength: 255
description: Código/SKU do item no sistema do integrador.
description:
type: string
minLength: 1
maxLength: 255
description: Descrição do item.
quantity:
type: integer
minimum: 1
description: Quantidade do item.
amount:
type: integer
minimum: 1
description: >-
Valor UNITÁRIO do item, em centavos (total da linha =
amount × quantity).
required:
- description
- quantity
- amount
minItems: 1
description: >-
Itens da transação; o total é a soma de amount × quantity de
cada item.
payments:
type: array
items:
type: object
properties:
paymentMethod:
type: string
enum:
- credit_card
- boleto
- pix
description: Método de pagamento deste payment.
amount:
type: integer
minimum: 1
description: >-
Valor deste payment, em centavos; a soma dos payments
deve igualar o total dos items.
installments:
type: integer
minimum: 1
default: 1
description: Número de parcelas (apenas credit_card; default 1).
additionalInfo:
type: object
additionalProperties: {}
description: Metadados livres do payment (chave → valor).
creditCard:
type: object
properties:
id:
type: string
nullable: true
description: ID de um cartão salvo no vault.
token:
type: string
minLength: 1
description: Token de captura gerado pelo Tokenizer.
statementDescriptor:
type: string
maxLength: 100
description: >-
Texto na fatura do portador (normalizado e
truncado em 13 chars).
billingAddress:
type: object
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: >-
Complemento do endereço (apartamento, bloco,
sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
postalCode:
type: string
nullable: true
description: CEP, somente dígitos.
description: Endereço de cobrança do cartão.
description: >-
Dados do cartão para processar imediatamente via
gateway (exige id ou token).
boleto:
type: object
properties:
expirationDate:
type: string
format: date-time
description: Data de vencimento do boleto.
instructions:
type: string
minLength: 1
maxLength: 255
description: Instruções impressas no boleto.
description: >-
Dados do boleto para processamento imediato via
gateway.
pix:
type: object
properties:
expirationDate:
type: string
format: date-time
description: >-
Expiração do QR Code Pix (default: 30 minutos após
a criação).
description: >-
Dados do Pix; opcional — Pix processa mesmo sem este
objeto.
splitId:
type: string
nullable: true
description: >-
ID de um split pré-configurado (mutuamente exclusivo
com split).
split:
type: array
items:
type: object
properties:
recipientId:
type: string
minLength: 1
description: ID do recebedor que recebe esta parte do split.
type:
type: string
enum:
- sale
- interest
- platform_fee
default: sale
description: >-
Categoria da parte do split: sale (venda),
interest (juros) ou platform_fee (taxa da
plataforma).
value:
type: number
minimum: 0.01
description: >-
Valor desta parte: percentual quando
valueType=percentage; valor fixo em centavos
quando valueType=fixed.
valueType:
type: string
enum:
- percentage
- fixed
description: >-
Como interpretar value: percentage (percentual
do total) ou fixed (valor fixo em centavos).
processingFee:
type: boolean
description: >-
Se true, este recebedor arca (proporcionalmente)
com as taxas de processamento.
liable:
type: boolean
description: >-
Se true, este recebedor é responsável por
chargebacks e estornos desta parte.
required:
- recipientId
- value
- valueType
minItems: 1
description: >-
Regras de divisão inline deste payment (mutuamente
exclusivo com splitId); sem split = 100% owner.
required:
- paymentMethod
- amount
minItems: 1
description: >-
Payments da transação (valores em centavos); com dados de
processamento processa via gateway, sem eles ficam
pendentes; omitido, a transação fica waiting_payment.
ip:
type: string
nullable: true
description: IP do comprador (antifraude).
ipSource:
type: string
enum:
- observed
- declared
nullable: true
description: >-
Origem do IP: `observed` quando lido da conexão do comprador
(checkout), `declared` quando informado pelo integrador.
Ausente vira `declared`.
additionalInfo:
type: object
additionalProperties: {}
description: >-
Metadados livres (chave → valor), devolvidos nos webhooks da
transação.
required:
- referenceCode
- items
- payments
responses:
'201':
description: Transação criada
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
customerId:
type: string
description: ID do cliente associado à transação.
amount:
type: integer
description: Valor em centavos.
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
paidAmount:
type: integer
description: Valor efetivamente pago, em centavos.
refundedAmount:
type: integer
description: Valor total estornado, em centavos.
status:
type: string
description: >-
Situação da transação, derivada dos pagamentos. Valores:
`pending`, `waiting_payment`, `partially_paid`, `paid`,
`refused`, `failed`, `canceled`, `waiting_refund`,
`partially_refunded`, `refunded`, `chargeback`,
`in_protest`.
parentTransactionId:
nullable: true
description: >-
ID da transação de origem, quando esta é derivada de
outra.
referenceCode:
type: string
description: Código de referência definido pelo integrador na criação.
ip:
type: string
description: Endereço IP de origem da transação.
additionalInfo:
type: object
properties:
source:
type: string
description: psp_import, platform_calc ou manual
description: Informações adicionais do registro (dados livres).
customerName:
type: string
description: Nome do cliente da transação.
customerEmail:
type: string
description: E-mail do cliente da transação.
customerDocument:
type: string
description: Documento (CPF ou CNPJ) do cliente da transação.
customerDocumentType:
type: string
description: 'Tipo de documento do cliente: cpf ou cnpj.'
customerPhone:
type: string
description: Telefone do cliente da transação.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
paidAt:
nullable: true
description: Data e hora em que o pagamento foi liquidado (ISO 8601).
expiresAt:
nullable: true
description: Data e hora em que o registro expira (ISO 8601).
canceledAt:
nullable: true
description: Data e hora em que a transação foi cancelada (ISO 8601).
refundedAt:
nullable: true
description: Data e hora em que o estorno foi concluído (ISO 8601).
chargedbackAt:
nullable: true
description: >-
Data e hora em que a transação sofreu chargeback (ISO
8601).
protestedAt:
nullable: true
description: Data e hora em que a transação foi protestada (ISO 8601).
items:
type: array
description: >-
Itens da transação. Vazio quando a transação não tem
itens.
items:
type: object
properties:
id:
type: string
description: ID do item.
transactionId:
type: string
description: Transação a que o item pertence.
code:
type: string
nullable: true
description: Seu código/SKU do item.
description:
type: string
description: Descrição do item.
unitValue:
type: integer
description: Valor unitário, em centavos.
quantity:
type: integer
description: Quantidade.
amount:
type: integer
description: >-
Total da linha, em centavos (`unitValue` ×
`quantity`).
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
payments:
type: array
description: >-
Pagamentos da transação, com cartão e splits quando
houver.
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
transactionId:
type: string
description: ID da transação relacionada ao registro.
replacedByPaymentId:
type: string
nullable: true
description: >-
ID do pagamento que substituiu este, em caso de
retentativa.
amount:
type: integer
description: Valor em centavos.
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
installments:
type: integer
description: Número de parcelas.
paymentMethod:
type: string
description: 'Forma de pagamento (ex.: credit_card, pix, boleto).'
cardId:
type: string
nullable: true
description: ID do cartão tokenizado usado no pagamento.
status:
type: string
description: >-
Situação do pagamento. Valores: `pending`,
`waiting_payment`, `paid`, `refused`, `failed`,
`canceled`, `replaced`, `waiting_refund`,
`partially_refunded`, `refunded`, `chargeback`,
`in_protest`.
additionalInfo:
type: object
nullable: true
description: Informações adicionais do registro (dados livres).
statementDescriptor:
type: string
nullable: true
description: >-
Texto exibido na fatura do cliente (statement
descriptor).
billingAddress:
type: object
nullable: true
description: >-
Endereço de cobrança do cartão, como informado na
criação da transação. Snapshot: preservado como
veio, mesmo que o cadastro do cliente mude depois.
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: >-
Complemento do endereço (apartamento, bloco,
sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
boletoUrl:
type: string
nullable: true
description: URL para visualização e impressão do boleto.
boletoDigitableLine:
type: string
nullable: true
description: Linha digitável do boleto.
boletoBarcode:
type: string
nullable: true
description: Código de barras do boleto.
pixUrl:
type: string
nullable: true
description: URL do QR Code PIX para pagamento.
pixCopyPaste:
type: string
nullable: true
description: >-
Código PIX copia e cola (payload EMV) para
pagamento.
splitConfigId:
type: string
nullable: true
description: ID da configuração de split aplicada ao pagamento.
originalAmount:
type: integer
nullable: true
description: >-
Valor original do pagamento antes de ajustes, em
centavos.
acquirerReturnCode:
type: string
nullable: true
description: >-
Código de retorno enviado pelo adquirente ao
processar o pagamento.
acquirerReturnMessage:
type: string
nullable: true
description: >-
Mensagem de retorno enviada pelo adquirente ao
processar o pagamento.
retryable:
type: boolean
nullable: true
description: Indica se o pagamento recusado pode ser retentado.
declineCode:
type: string
nullable: true
description: Código de recusa retornado pelo adquirente.
errorMessage:
type: string
nullable: true
description: Mensagem de erro quando o processamento falha.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: >-
Data e hora da última atualização do registro (ISO
8601).
paidAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o pagamento foi liquidado (ISO
8601).
expiresAt:
type: string
format: date-time
nullable: true
description: Data e hora em que o registro expira (ISO 8601).
canceledAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação foi cancelada (ISO
8601).
refundedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o estorno foi concluído (ISO
8601).
chargedbackAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação sofreu chargeback
(ISO 8601).
protestedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a transação foi protestada (ISO
8601).
card:
type: object
nullable: true
description: >-
Dados do cartão usado no pagamento. Ausente fora de
`credit_card`.
properties:
id:
type: string
description: ID do cartão (`crd_`).
brand:
type: string
description: 'Bandeira (ex.: `visa`, `mastercard`).'
firstDigits:
type: string
description: Seis primeiros dígitos.
lastDigits:
type: string
description: Quatro últimos dígitos.
holderName:
type: string
description: Nome impresso no cartão.
expirationMonth:
type: string
description: Mês de validade (`MM`).
expirationYear:
type: string
description: Ano de validade (`YYYY`).
status:
type: string
description: Situação do cartão.
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
splits:
type: array
description: >-
Divisão do valor deste pagamento entre recebedores.
Vazio quando não há split.
items:
type: object
properties:
id:
type: string
description: ID do split.
paymentId:
type: string
description: Pagamento dividido.
recipientId:
type: string
description: Recebedor (`rec_`).
recipientName:
type: string
nullable: true
description: >-
Nome do recebedor, resolvido no momento da
consulta.
value:
type: integer
description: >-
Valor configurado: percentual (0–100) ou valor
fixo em centavos, conforme `valueType`.
amount:
type: integer
description: >-
Valor efetivamente destinado ao recebedor, em
centavos.
currency:
type: string
description: Moeda, ISO 4217.
type:
type: string
description: Papel do recebedor na divisão.
typeLabel:
type: string
description: Rótulo legível de `type`.
valueType:
type: string
description: 'Como ler `value`: percentual ou fixo.'
processingFee:
type: boolean
description: >-
Se este recebedor arca com a taxa de
processamento.
liable:
type: boolean
description: Se este recebedor responde por chargebacks.
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
customer:
type: object
nullable: true
description: >-
Cliente da transação, quando `customerId` está preenchido.
Não vem na listagem — use `GET /customers/{id}`.
properties:
id:
type: string
description: ID do cliente (`cust_`).
name:
type: string
description: Nome completo do cliente.
email:
type: string
description: E-mail do cliente.
type:
type: string
description: >-
Tipo de cliente: individual (pessoa física) ou company
(pessoa jurídica).
document:
type: string
description: Documento do cliente (CPF ou CNPJ, somente dígitos).
documentType:
type: string
description: 'Tipo do documento do cliente: cpf ou cnpj.'
phone:
type: string
description: >-
Telefone do cliente (formato E.164, ex.:
+5511987654321).
address:
type: object
nullable: true
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: >-
Complemento do endereço (apartamento, bloco,
sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
description: >-
Endereço do cadastro do cliente **hoje** — não o
informado nesta compra.
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
customerAddress:
type: object
nullable: true
properties:
street:
type: string
nullable: true
description: Logradouro (rua, avenida).
number:
type: string
nullable: true
description: Número do endereço.
complement:
type: string
nullable: true
description: Complemento do endereço (apartamento, bloco, sala).
neighborhood:
type: string
nullable: true
description: Bairro.
city:
type: string
nullable: true
description: Cidade.
state:
type: string
nullable: true
description: 'Estado ou UF (ex.: SP).'
postalCode:
type: string
nullable: true
description: CEP / código postal (somente dígitos).
country:
type: string
nullable: true
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
description: >-
Endereço informado nesta compra, congelado no momento da
criação. É este que vale para nota fiscal e antifraude:
editar o cadastro do cliente depois não o altera. Compare
com `customer.address`, que reflete o cadastro atual.
example:
id: txn_tyjpijlt9r6tig31605cvkbru
customerId: cust_f7vm6b4j4cckf8gli2b2472ix
amount: 19990
currency: BRL
paidAmount: 0
refundedAmount: 0
status: waiting_payment
parentTransactionId: null
referenceCode: ORDER-2025-00123
ip: 189.45.12.34
additionalInfo:
source: checkout-web
customerName: Maria Silva
customerEmail: maria.silva@example.com
customerDocument: '12345678909'
customerDocumentType: cpf
customerPhone: '+5511987654321'
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
paidAt: null
expiresAt: '2026-06-25T12:00:00.000Z'
canceledAt: null
refundedAt: null
chargedbackAt: null
protestedAt: null
items:
- id: item_s4206yea51f6fsiugybgb51sr
transactionId: txn_tyjpijlt9r6tig31605cvkbru
code: PLANO-PRO
description: Plano Pro (mensal)
unitValue: 19990
quantity: 1
amount: 19990
createdAt: '2026-06-24T12:00:00.000Z'
updatedAt: '2026-06-24T12:00:00.000Z'
payments:
- id: pay_kd6z67zbp52rgtg2idms96fhm
transactionId: txn_tyjpijlt9r6tig31605cvkbru
replacedByPaymentId: null
amount: 19990
currency: BRL
installments: 1
paymentMethod: pix
cardId: null
status: waiting_payment
additionalInfo: null
statementDescriptor: null
billingAddress: null
boletoUrl: null
boletoDigitableLine: null
boletoBarcode: null
pixUrl: >-
https://pix.z2pay.com/qr/pay_kd6z67zbp52rgtg2idms96fhm/qr.png
pixCopyPaste: >-
00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540519.905802BR5913LOJA
EXEMPLO6009SAO PAULO62070503***6304A1B2
splitConfigId: null
originalAmount: null
acquirerReturnCode: null
acquirerReturnMessage: null
retryable: null
declineCode: null
errorMessage: null
createdAt: '2026-06-24T12:00:00.000Z'
updatedAt: '2026-06-24T12:05:00.000Z'
paidAt: null
expiresAt: '2026-06-25T12:00:00.000Z'
canceledAt: null
refundedAt: null
chargedbackAt: null
protestedAt: null
card: null
splits: []
customer:
id: cust_f7vm6b4j4cckf8gli2b2472ix
name: Maria Silva
email: maria.silva@example.com
type: individual
document: '12345678909'
documentType: cpf
phone: '+5511999998888'
address:
street: Av. Paulista
number: '1000'
complement: Conj. 101
neighborhood: Bela Vista
city: São Paulo
state: SP
postalCode: '01310100'
country: BR
createdAt: '2026-06-24T12:00:00.000Z'
updatedAt: '2026-06-24T12:00:00.000Z'
customerAddress:
street: Av. Paulista
number: '1000'
complement: Conj. 101
neighborhood: Bela Vista
city: São Paulo
state: SP
postalCode: '01310100'
country: BR
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
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)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````