> ## 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.
# Processar pagamentos
> Cobra os pagamentos que foram criados sem dados de pagamento — a segunda etapa de quem separa o pedido da cobrança.
`POST /transactions/:transactionId/payments/process`
Faz parte do recurso [Pagamentos](/pt-BR/payments) — o objeto e os status estão lá.
Cobra os pagamentos que já existem na transação mas ainda não foram ao gateway.
## Quando você precisa deste endpoint
Na maior parte das integrações, **você não precisa**. Ao [criar a transação](/pt-BR/transactions/create)
com o objeto do meio de pagamento dentro de `payments` — `creditCard`, `boleto` ou `pix` — a cobrança
acontece na mesma requisição, e a resposta já diz se foi aprovada.
Este endpoint existe para quem **separa o pedido da cobrança em duas etapas**:
```json theme={null}
POST /transactions
{
"items": [{ "description": "Camiseta", "quantity": 1, "amount": 9990 }],
"payments": [{ "paymentMethod": "credit_card", "amount": 9990 }]
}
```
Você disse **que** haverá um pagamento de cartão de R\$ 99,90, mas não disse **qual** cartão. O
pagamento nasce em `pending` — registrado, não cobrado. Nada foi ao gateway.
```json theme={null}
POST /transactions/txn_ebgsvfsb4151nmbgvj4sek6ol/payments/process
{
"customer": { "name": "Maria Souza", "email": "maria@example.com",
"type": "individual", "document": "12345678909", "documentType": "cpf" },
"creditCard": { "token": "tok_abc" }
}
```
Agora a Z2Pay pega aquele pagamento pendente, junta com o cartão e envia ao gateway.
**Por que alguém separaria?** Por ordem: assim o pedido existe antes de o comprador digitar o cartão.
Num checkout próprio, você cria a transação quando o carrinho fecha e já tem o `txn_` para exibir o
número do pedido, gravar no seu banco e mandar o e-mail de "pedido recebido". A cobrança vem na tela
seguinte. Numa chamada só, você teria de esperar o cartão para a transação sequer existir.
O outro uso é **retentar**: o cartão foi recusado, o comprador informa outro, e você chama este
endpoint de novo com o cartão novo.
***
## O que enviar
**O objeto `customer` é obrigatório aqui**, mesmo que a transação tenha sido criada com
`customerId`. O gateway exige os dados do comprador (`name`, `email`, `document`, `documentType`,
`type`) no momento da cobrança, e este endpoint não os busca do cadastro.
**Cartão exige o objeto `creditCard`** — com `token` (do [Tokenizer](/pt-BR/tokenizer)) ou
`cardId` (de um cartão salvo). Sem ele não há o que enviar ao gateway, e o pagamento termina em
`failed`.
**Pix e boleto dispensam o objeto.** `pix` e `boleto` existem só para mudar a expiração — omitidos,
valem os mesmos defaults da criação: **30 minutos** no Pix, **3 dias** no boleto. O campo é
`expirationDate`, o mesmo nome de [`POST /transactions`](/pt-BR/transactions/create).
**Os dados enviados valem para todos os pagamentos processados na chamada.** Se a transação tem dois
pagamentos e você não restringe, os dois recebem o mesmo `creditCard`. Para cobrar cartões
diferentes em cada um, faça uma chamada por pagamento, usando `paymentIds`.
**`paymentIds` restringe quais pagamentos processar.** Omitido, a Z2Pay processa todos os que estão
em `pending` ou `waiting_payment`. Informe apenas IDs de pagamentos **ainda não pagos** — o campo
serve para escolher entre os pendentes, não para reprocessar o que já foi cobrado.
Envie o header `Idempotency-Key` — [idempotência](/pt-BR/convencoes) evita cobrança duplicada se a
requisição for reenviada por timeout ou retry.
**Nada pendente é `409`.** Se nenhum pagamento se qualifica, a resposta é `409` com
`error.details.code: "NO_PENDING_PAYMENTS"` — não um `200` vazio. Repare no caminho: o
`error.code` é sempre a **classe** do erro (`"CONFLICT"`, neste caso); o código específico vem
dentro de `error.details.code`. Costuma significar que a transação já foi cobrada, ou que os
`paymentIds` informados não estão pendentes.
O mesmo `409` responde quando outra requisição com a **mesma `Idempotency-Key`** ainda está em
curso. Nesse caso o corpo é `{ "error": "texto" }`, sem objeto nenhum — trate pelo status, não
pelo código.
## OpenAPI
````yaml openapi/psp.json POST /transactions/{transactionId}/payments/process
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/{transactionId}/payments/process:
post:
tags:
- Transactions
summary: Processar payments
description: >-
Processa os payments pendentes da transação e inicia o ciclo de
pagamento
operationId: PaymentController_processPayments
parameters:
- name: transactionId
in: path
required: true
description: ID da transação
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customer:
type: object
properties:
name:
type: string
minLength: 2
description: Nome completo do cliente.
email:
type: string
format: email
description: E-mail do cliente.
document:
type: string
minLength: 11
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.'
type:
type: string
enum:
- individual
- company
description: >-
Tipo de cliente: individual (pessoa física) ou company
(pessoa jurídica).
phone:
type: object
properties:
countryCode:
type: string
minLength: 1
description: 'Código do país do telefone (ex.: 55).'
areaCode:
type: string
minLength: 1
description: 'Código de área/DDD do telefone (ex.: 11).'
number:
type: string
minLength: 1
description: Número do endereço.
required:
- countryCode
- areaCode
- number
description: >-
Telefone do cliente (formato E.164, ex.:
+5511987654321).
address:
type: object
properties:
street:
type: string
minLength: 1
description: Logradouro (rua, avenida).
number:
type: string
minLength: 1
description: Número do endereço.
complement:
type: string
description: Complemento do endereço (apartamento, bloco, sala).
neighborhood:
type: string
minLength: 1
description: Bairro.
city:
type: string
minLength: 1
description: Cidade.
state:
type: string
minLength: 1
description: 'Estado ou UF (ex.: SP).'
country:
type: string
minLength: 1
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
postalCode:
type: string
minLength: 1
description: CEP, somente dígitos.
required:
- street
- number
- neighborhood
- city
- state
- country
- postalCode
description: Endereço do cliente.
required:
- name
- email
- document
- documentType
- type
description: Dados do comprador exigidos pelo gateway.
creditCard:
type: object
properties:
cardId:
type: string
description: ID de um cartão salvo no vault.
token:
type: string
minLength: 1
description: Token de captura gerado pelo Tokenizer.
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: 'Cartão a processar: cardId do vault ou token do Tokenizer.'
boleto:
type: object
properties:
expirationDate:
type: string
format: date-time
description: >-
Data de vencimento do boleto (default: 3 dias após o
processamento).
instructions:
type: string
minLength: 1
maxLength: 255
description: Instruções impressas no boleto.
description: Dados do boleto para processamento via gateway.
pix:
type: object
properties:
expirationDate:
type: string
format: date-time
description: >-
Expiração do QR Code Pix (default: 30 minutos após o
processamento).
description: Dados do Pix para processamento via gateway.
ip:
type: string
description: IP do comprador (antifraude).
paymentIds:
type: array
items:
type: string
description: >-
IDs específicos de payments a processar; omitido/vazio
processa todos os pendentes.
required:
- customer
responses:
'200':
description: Resultado do processamento dos payments
content:
application/json:
schema:
type: object
properties:
processed:
type: integer
description: Quantidade de pagamentos processados.
results:
type: array
items:
type: object
properties:
payments:
type: array
items:
type: object
properties:
id:
type: string
description: Identificador único do registro.
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`.
description: Pagamentos vinculados à transação.
description: Resultados do processamento em lote.
example:
processed: 1
results:
- payments:
- id: pay_k0fg3q4jjcbi56hdhbi7xlj5e
status: paid
'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: >-
Nenhum pagamento pendente para processar (inclusive quando a
transação não existe), ou requisição de mesma Idempotency-Key ainda
em curso
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)
````