Transactions - Z2Pay Developers

A transação (txn_) é o objeto central da Core API: ela agrupa o que o comprador está pagando (os items) e como está pagando (os payments). Cada payment representa uma tentativa/forma de pagamento (cartão, boleto ou Pix). O status da transação nunca é definido diretamente — ele é sempre calculado a partir do estado agregado dos seus payments.

Todas as rotas exigem o header x-api-key (sua chave de sandbox). Veja Autenticação. Os exemplos abaixo usam a base URL de sandbox https://api.sandbox.z2pay.com.

Endpoints

Método	Rota	Descrição
`GET`	`/transactions`	Lista paginada de transações, com filtros
`GET`	`/transactions/:id`	Busca uma transação com seus payments e items
`GET`	`/transactions/:id/items`	Lista apenas os items da transação
`POST`	`/transactions`	Cria uma nova transação
`POST`	`/transactions/:id/refund`	Estorna todos os payments pagos da transação

Status da transação

O status é derivado dos payments por um cálculo central. Em resumo (regras avaliadas em ordem):

Como o status é calculado

Payments com status replaced ou deleted são ignorados no cálculo.
Se a transação tem valor zero → paid.
Se não há payment ativo → pending.
Se todos os payments não-falhos são refused → refused. Se todos são failed/expired → failed.
Entre os payments válidos (excluindo refused/failed/expired): se todos são chargeback → chargeback; se todos são canceled → canceled; se todos são in_protest → in_protest.
Se o valor efetivamente pago cobre o total da transação → paid (mesmo com estorno parcial de excedente).
Se há valor pago (> 0) menor que o total e sem atividade de estorno → partially_paid.
Se as legs liquidadas estão todas em ciclo de estorno: todas refunded → refunded; alguma partially_refunded → partially_refunded; caso contrário → waiting_refund.
Sobrou valor pago/retido junto com estorno ativo → partially_refunded.
Valor estornado cobre o total → refunded.
Sem nada pago e o valor aguardando pagamento cobre o total → waiting_payment.
Caso nenhum dos anteriores → pending.

Valores possíveis de status:

Status	Significado
`pending`	Criada, sem pagamento confirmado nem aguardando pagamento definido
`waiting_payment`	Aguardando pagamento (boleto/Pix emitido, ou payment criado sem processar)
`partially_paid`	Parte do valor foi pago, mas não o total
`paid`	Valor total pago
`refused`	Pagamento recusado
`failed`	Falha terminal no gateway
`canceled`	Cancelada
`waiting_refund`	Estorno solicitado, aguardando processamento
`partially_refunded`	Parte do valor pago foi estornada
`refunded`	Valor total estornado
`chargeback`	Sofreu chargeback
`in_protest`	Em protesto (disputa de chargeback em andamento)

Como o status agrega os payments, uma transação com mais de um payment (ex.: dois cartões, ou Pix + cartão) pode passar por estados intermediários como partially_paid ou partially_refunded.

Criar transação

POST /transactions Cria uma transação. Você sempre informa o cliente e pelo menos um item. Os payments são opcionais:

Com payments e dados de processamento (creditCard/boleto/pix) → os payments são processados imediatamente no gateway.
Com payments sem dados de processamento → os payments ficam aguardando processamento.
Sem payments → a transação fica waiting_payment.

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.

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 payments deve bater com a soma dos items. Quando payments é enviado, a soma de payment.amount precisa ser exatamente igual ao total dos items (Σ item.amount × item.quantity). Caso contrário, 400. Todos os valores são inteiros em centavos.

Corpo da requisição

customerId

string

ID de um cliente existente (cust_). Mutuamente exclusivo com customer.

customer

object

Dados do cliente inline. Mutuamente exclusivo com customerId.

Mostrar campos de customer

customer.name

string

obrigatório

Nome do cliente (mínimo 2 caracteres).

customer.email

string

obrigatório

E-mail válido.

customer.type

string

obrigatório

Tipo do cliente. Valores: individual ou company.

customer.document

string

obrigatório

Documento (mínimo 6 caracteres).

customer.documentType

string

Tipo do documento. Valores: cpf, cnpj ou passport.

customer.phone

string

obrigatório

Telefone do cliente.

customer.address

object

Endereço do comprador. Campos: street, number, complement, neighborhood, city, state, postalCode, country (todos opcionais, podem ser null). Campos faltantes podem ser completados pela configuração do gateway.

referenceCode

string

obrigatório

Seu código de referência para a transação (1 a 255 caracteres). Use para correlacionar com seu sistema.

items

array

obrigatório

Lista de items (mínimo 1).

Mostrar campos de cada item

items[].description

string

obrigatório

Descrição do item (1 a 255 caracteres).

items[].quantity

integer

obrigatório

Quantidade (inteiro, mínimo 1).

items[].amount

integer

obrigatório

Valor unitário em centavos (inteiro, mínimo 1).

items[].code

string

Código/SKU do item (1 a 255 caracteres).

items[].type

string

Tipo do item (até 50 caracteres).

items[].imageUrl

string

URL da imagem do item (URL válida, até 500 caracteres).

payments

array

Formas de pagamento. Se omitido, a transação fica waiting_payment.

Mostrar campos de cada payment

payments[].paymentMethod

string

obrigatório

Método. Valores: credit_card, boleto ou pix.

payments[].amount

integer

obrigatório

Valor do payment em centavos (inteiro, mínimo 1).

payments[].installments

integer

padrão:"1"

Número de parcelas (inteiro, mínimo 1). Parcelamento (> 1) só é permitido para credit_card.

payments[].additionalInfo

object

Metadados livres (objeto chave-valor).

payments[].creditCard

object

Dados de processamento de cartão (somente com paymentMethod: credit_card). Exige id ou token do cartão. Campos: id (crd_), token, statementDescriptor (soft descriptor, até 100 caracteres) e billingAddress.

payments[].boleto

object

Dados do boleto (somente com paymentMethod: boleto). Campos: expirationDate (data), instructions (1 a 255 caracteres).

payments[].pix

object

Dados do Pix (somente com paymentMethod: pix). Campo: expirationDate (data).

payments[].splitId

string

ID de uma config de split salva. Mutuamente exclusivo com split.

payments[].split

array

Config de split inline. Mutuamente exclusivo com splitId. Veja Split.

currency

string

Código de moeda ISO 4217 (3 letras, ex.: BRL). Default: configuração da company ou BRL.

redirectUrl

string

URL de redirecionamento após o pagamento (URL válida).

postbackUrl

string

URL para receber notificações desta transação (URL válida). Veja Webhooks.

string

IP do comprador.

additionalInfo

object

Metadados livres da transação (objeto chave-valor). Pesquisável via filtro metadataSearch.

maxInstallments

integer

Número máximo de parcelas permitido (inteiro, mínimo 1).

routerConfigId

string

Override da configuração de roteamento (opcional).

Exemplo: criar transação com Pix

curl -X POST https://api.sandbox.z2pay.com/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 payment soma 9990 — as somas batem, então a requisição é válida.

{
  "id": "txn_3xK9aQ2bR7tV1mN0",
  "referenceCode": "pedido-2026-0001",
  "status": "waiting_payment",
  "amount": 9990,
  "currency": "BRL",
  "customerId": "cust_8Hn2Lp4Wq6Yz0Bc",
  "payments": [
    {
      "id": "pay_5Rg7Df3Ka9Xs2Vn1",
      "paymentMethod": "pix",
      "status": "waiting_payment",
      "amount": 9990
    }
  ],
  "items": [
    {
      "id": "item_1Ab2Cd3Ef4Gh5Ij",
      "description": "Plano Pro (mensal)",
      "quantity": 1,
      "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.

Exemplo: criar e cobrar cartão com cartão tokenizado

curl -X POST https://api.sandbox.z2pay.com/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_8Hn2Lp4Wq6Yz0Bc",
    "items": [
      { "description": "Camiseta", "quantity": 2, "amount": 5000 }
    ],
    "payments": [
      {
        "paymentMethod": "credit_card",
        "amount": 10000,
        "installments": 1,
        "creditCard": {
          "token": "tok_exemplo_sandbox",
          "statementDescriptor": "MINHALOJA"
        }
      }
    ]
  }'

Dois items de 5000 × 2 = 10000 centavos; o payment soma 10000. As somas batem. O cartão é enviado como token (gerado pelo Tokenizer) — nunca envie dados crus do cartão para a Core API.

Listar transações

GET /transactions Retorna uma lista paginada. Todos os filtros são opcionais e podem ser combinados.

Parâmetros de query

page

integer

Página (paginação). Veja Convenções.

limit

integer

Itens por página.

status

string

Filtra por status da transação.

currency

string

Filtra por moeda.

paymentMethod

string

Filtra por método de pagamento.

string

ID da transação (busca parcial, ILIKE).

referenceCode

string

Filtra pelo seu código de referência.

customerName

string

Filtra pelo nome do cliente.

customerEmail

string

Filtra pelo e-mail do cliente.

customerDocument

string

Filtra pelo documento do cliente.

customerSearch

string

Busca combinada em nome/e-mail/documento do cliente.

recipientIds

string

Lista de IDs de recebedores (separados por vírgula) que devem aparecer em algum split da transação.

metadataSearch

string

Busca textual em qualquer valor armazenado em additionalInfo.

string

Busca genérica.

startDate

string

Data inicial. ISO 8601 com timezone (ex.: 2026-06-01T00:00:00.000Z).

endDate

string

Data final. ISO 8601 com timezone.

dateField

string

Campo de data usado por startDate/endDate. Valores: createdAt, paidAt, refundedAt, canceledAt, chargedbackAt, protestedAt.

sortBy

string

Campo de ordenação. Valores: createdAt, paidAt, amount, status, customerName.

sortDir

string

Direção da ordenação. Valores: asc ou desc.

Exemplo

curl "https://api.sandbox.z2pay.com/transactions?status=paid&sortBy=createdAt&sortDir=desc&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "txn_3xK9aQ2bR7tV1mN0",
      "referenceCode": "pedido-2026-0001",
      "status": "paid",
      "amount": 9990,
      "currency": "BRL",
      "customerId": "cust_8Hn2Lp4Wq6Yz0Bc",
      "createdAt": "2026-06-24T12:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

O formato exato do envelope de paginação está em Convenções. O JSON acima é ilustrativo.

Buscar transação por ID

GET /transactions/:id Retorna os dados completos da transação, incluindo seus payments e items.

string

obrigatório

ID da transação (txn_).

curl https://api.sandbox.z2pay.com/transactions/txn_3xK9aQ2bR7tV1mN0 \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "txn_3xK9aQ2bR7tV1mN0",
  "referenceCode": "pedido-2026-0001",
  "status": "paid",
  "amount": 9990,
  "currency": "BRL",
  "customerId": "cust_8Hn2Lp4Wq6Yz0Bc",
  "payments": [
    {
      "id": "pay_5Rg7Df3Ka9Xs2Vn1",
      "paymentMethod": "pix",
      "status": "paid",
      "amount": 9990
    }
  ],
  "items": [
    {
      "id": "item_1Ab2Cd3Ef4Gh5Ij",
      "description": "Plano Pro (mensal)",
      "quantity": 1,
      "amount": 9990
    }
  ]
}

status

string

Status calculado da transação. Veja a tabela em Status da transação.

payments

array

Payments da transação. Para detalhes de payment, veja Payments.

items

array

Items da transação.

Se o ID não existir, a resposta é 404. Veja Erros.

Listar items da transação

GET /transactions/:id/items Retorna apenas os items (produtos/serviços) da transação, dentro de uma chave data.

string

obrigatório

ID da transação (txn_).

curl https://api.sandbox.z2pay.com/transactions/txn_3xK9aQ2bR7tV1mN0/items \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "item_1Ab2Cd3Ef4Gh5Ij",
      "description": "Plano Pro (mensal)",
      "quantity": 1,
      "amount": 9990
    }
  ]
}

Se a transação não existir, a resposta é 404.

Estornar transação

POST /transactions/:id/refund Cria pedidos de refund para todos os payments pagos da transação de uma só vez. O comportamento de aprovação depende da configuração refund.auto_approve da company (default: ativado):

Com auto-approve: o refund é criado, aprovado e processado no gateway imediatamente.
Sem auto-approve: os refunds ficam pendentes de aprovação manual.

Endpoint idempotente — envie Idempotency-Key. Para estornar um payment específico (estorno parcial), use o endpoint de Refunds / Payments.

string

obrigatório

ID da transação (txn_).

reason

string

obrigatório

Motivo do estorno (1 a 4000 caracteres).

curl -X POST https://api.sandbox.z2pay.com/transactions/txn_3xK9aQ2bR7tV1mN0/refund \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: refund-pedido-0001" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Cliente solicitou cancelamento" }'

{
  "data": [
    {
      "id": "rfd_9Zx8Wv7Ut6Sr5Qp",
      "paymentId": "pay_5Rg7Df3Ka9Xs2Vn1",
      "status": "refunded",
      "amount": 9990,
      "reason": "Cliente solicitou cancelamento"
    }
  ]
}

Status possíveis

200 — refunds criados e processados.
404 — transação não encontrada.
409 — nenhum payment estornável encontrado (ex.: nenhum payment está pago).

Veja Erros para o formato dos erros.

Veja também

Payments

Detalhes de cada forma de pagamento dentro da transação.

Refunds

Estorno de um payment específico e estornos parciais.

Tokenizer

Gere o token do cartão antes de criar a transação.

Split

Configure repasses por payment com split ou splitId.

Customers

Cadastre clientes para reusar via customerId.

Webhooks

Receba notificações de mudança de status da transação.

​Endpoints

​Status da transação

​Criar transação

​Regras de negócio importantes

​Corpo da requisição

​Exemplo: criar transação com Pix

​Exemplo: criar e cobrar cartão com cartão tokenizado

​Listar transações

​Parâmetros de query

​Exemplo

​Buscar transação por ID

​Listar items da transação

​Estornar transação

​Status possíveis

​Veja também

Payments

Refunds

Tokenizer

Split

Customers

Webhooks

Endpoints

Status da transação

Criar transação

Regras de negócio importantes

Corpo da requisição

Exemplo: criar transação com Pix

Exemplo: criar e cobrar cartão com cartão tokenizado

Listar transações

Parâmetros de query

Exemplo

Buscar transação por ID

Listar items da transação

Estornar transação

Status possíveis

Veja também