> ## 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.
# Abrir autorização de Pix Automático
> Abre a autorização de Pix Automático e devolve o QR que cobra o primeiro pagamento e pede a autorização das faturas seguintes.
`POST /pix-authorizations`
Faz parte do recurso [Pix Automático](/pt-BR/pix-authorizations) — o fluxo completo, os status e o
débito de cada ciclo estão lá.
Abre a autorização em `pending` e devolve, em `charge`, o QR do primeiro pagamento. O mesmo QR faz as
duas coisas: cobra `firstCharge.amount` agora e pede ao pagador a autorização das faturas seguintes,
na periodicidade de `frequency`. Exiba o QR na sua tela e espere o webhook
`pix_authorization.activated` para criar a assinatura.
**Envie `customer` ou `customerId` — um dos dois, nunca os dois.** Os dois juntos, ou nenhum,
respondem `400`. Um `customerId` que não é da sua conta responde `404`.
**A abertura recusada responde `409`, não uma cobrança Pix comum.** Acontece quando o Pix
Automático não está habilitado na sua conta (fale com o suporte), quando falta nome ou documento no
cadastro do cliente informado em `customerId`, ou quando o QR não pôde ser gerado — nesse último
caso nada foi cobrado, e você pode tentar de novo.
**O primeiro dia autorizado é amanhã.** `recurrenceBeginningDay` sai como o dia seguinte à abertura
porque a autorização precisa começar no futuro. Isso não adia cobrança nenhuma: o primeiro
pagamento sai agora, pelo QR, e o dia de cada débito seguinte é o vencimento da fatura da
assinatura.
**Com `customer` no corpo, `customerId` vem nulo nesta resposta.** O cliente é criado junto com o
primeiro pagamento e vinculado logo em seguida — o [`GET`](/pt-BR/pix-authorizations/get) e os
webhooks já o trazem.
**`additionalInfo` acompanha o primeiro pagamento, não a autorização.** Ele é gravado na transação
de `charge.transactionId`; a autorização não o devolve.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/pix-authorizations \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_hqx4mkpi8dcxbrb2nzynxnjky",
"frequency": "monthly",
"firstCharge": { "amount": 19900, "description": "Plano Pro — mensalidade" }
}'
```
```json Resposta 201 theme={null}
{
"id": "pxa_j43n74fbt2geb8c1y86ssf6iw",
"customerId": "cust_hqx4mkpi8dcxbrb2nzynxnjky",
"subscriptionId": null,
"status": "pending",
"frequency": "monthly",
"endDay": null,
"charge": {
"transactionId": "txn_x8m2kq4rt6yhb9c3vzn5pfjw1",
"paymentId": "pay_q7w9e2r4t6y8u1i3o5p7a9s2d",
"amount": 19900,
"qrCode": "https://api.z2pay.com/qr/pxa_j43n74fbt2geb8c1y86ssf6iw.png",
"qrCodeText": "00020126580014br.gov.bcb.pix0136...",
"expiresAt": "2026-08-31T14:52:05.000Z"
}
}
```
## OpenAPI
````yaml openapi/psp.json POST /pix-authorizations
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: Payments
description: Consulta e estorno de pagamentos
- name: Pix Automático
description: >-
Autorizações de débito recorrente por Pix. O pagador confirma uma vez no
app do banco e as cobranças seguintes são debitadas sem ação dele.
- name: Receivables
description: >-
Recebíveis: o que cada venda vai depositar na carteira, por recebedor e
parcela, com data prevista e status
- 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:
/pix-authorizations:
post:
tags:
- Pix Automático
summary: Abrir autorização
description: >-
Devolve um QR Code que faz duas coisas num gesto só: cobra a primeira
mensalidade e pede ao pagador a autorização das seguintes. Exiba o QR na
sua tela.
A autorização nasce `pending`. Quando o pagador confirmar no app do
banco, você recebe o webhook `pix_authorization.activated` e pode criar
a assinatura apontando para ela.
**A primeira cobrança é obrigatória.** Plano com primeiro mês grátis ou
entrada zero ainda não é coberto — nesses casos, cobre por Pix comum a
cada ciclo.
operationId: PixAuthorizationController_open
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customerId:
type: string
description: Cliente já cadastrado (`cust_`). 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
default: individual
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
description: 'Tipo do documento do cliente: cpf ou cnpj.'
phone:
type: string
minLength: 1
description: >-
Telefone do cliente (formato E.164, ex.:
+5511987654321).
required:
- name
- email
- document
description: >-
Dados do pagador. Nome e documento são exigidos pelo arranjo
para registrar a autorização junto ao banco dele — sem eles
não há autorização a propor.
frequency:
type: string
enum:
- weekly
- monthly
- quarterly
- semiannual
- annual
description: >-
Com que frequência o pagador será debitado. `weekly`,
`monthly`, `quarterly`, `semiannual` ou `annual` — outras
cadências seguem em Pix comum, pago manualmente a cada
ciclo.
firstCharge:
type: object
properties:
amount:
type: integer
minimum: 1
description: >-
Valor da primeira cobrança, em centavos. É o que o QR
cobra agora.
description:
type: string
minLength: 1
maxLength: 255
description: >-
Descrição que aparece na cobrança. Omitida, usamos uma
genérica.
expirationDate:
type: string
format: date-time
description: >-
Expiração do QR (ISO 8601 com fuso). Omitida, 30
minutos.
required:
- amount
description: >-
A cobrança que o QR liquida agora — obrigatória nesta
versão.
endDate:
type: string
format: date-time
description: >-
Até quando a autorização vale (ISO 8601 com fuso). Omitida,
ela vale até ser cancelada.
additionalInfo:
type: object
additionalProperties: {}
description: Dados seus, gravados na transação do primeiro pagamento.
required:
- frequency
- firstCharge
responses:
'201':
description: Autorização aberta, com o QR da primeira cobrança
content:
application/json:
example:
id: pxa_j43n74fbt2geb8c1y86ssf6iw
customerId: cust_hqx4mkpi8dcxbrb2nzynxnjky
subscriptionId: null
status: pending
frequency: monthly
recurrenceBeginningDay: '2026-09-01'
endDay: null
createdAt: '2026-08-31T14:22:05.000Z'
updatedAt: '2026-08-31T14:22:05.000Z'
charge:
transactionId: txn_x8m2kq4rt6yhb9c3vzn5pfjw1
paymentId: pay_q7w9e2r4t6y8u1i3o5p7a9s2d
amount: 19900
qrCode: https://api.z2pay.com/qr/pxa_j43n74fbt2geb8c1y86ssf6iw.png
qrCodeText: 00020126580014br.gov.bcb.pix0136...
expiresAt: '2026-08-31T14:52:05.000Z'
schema:
type: object
properties:
id:
type: string
description: ID da autorização (`pxa_`).
customerId:
type: string
nullable: true
description: >-
Cliente pagador (`cust_`). Na resposta da abertura vem
nulo quando o pagador foi enviado em `customer`: o vínculo
é preenchido logo depois, e o `GET` já o traz.
subscriptionId:
type: string
nullable: true
description: >-
Assinatura que usa esta autorização como forma de
pagamento. Nulo até a assinatura ser criada — e para
sempre numa autorização que nunca virou assinatura.
status:
type: string
description: >-
Situação da autorização: `pending`, `active`, `canceled`
ou `expired`. `canceled` e `expired` são finais.
enum:
- pending
- active
- canceled
- expired
frequency:
type: string
description: >-
Periodicidade que o pagador autorizou: `weekly`,
`monthly`, `quarterly`, `semiannual` ou `annual`. Precisa
ser a mesma da assinatura.
enum:
- weekly
- monthly
- quarterly
- semiannual
- annual
recurrenceBeginningDay:
type: string
description: >-
Primeiro dia em que o débito pode acontecer
(`YYYY-MM-DD`), no calendário da sua conta. Na abertura
pela API é o dia seguinte — o primeiro pagamento sai na
hora, pelo QR.
endDay:
type: string
nullable: true
description: >-
Último dia de validade (`YYYY-MM-DD`), resolvido a partir
do `endDate` enviado. Nulo quando a autorização vale até
ser encerrada.
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
charge:
type: object
description: >-
O primeiro pagamento, que o QR cobra agora. Só vem na
resposta da abertura.
properties:
transactionId:
type: string
description: Transação do primeiro pagamento (`txn_`).
paymentId:
type: string
description: Pagamento Pix dessa transação (`pay_`).
amount:
type: integer
description: Valor cobrado agora, em centavos.
qrCode:
type: string
nullable: true
description: URL da imagem do QR Code.
qrCodeText:
type: string
nullable: true
description: Código Pix copia e cola.
expiresAt:
type: string
nullable: true
description: Até quando o QR aceita pagamento, ISO 8601.
'400':
description: Payload inválido
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: Credencial ausente 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
'404':
description: Cliente informado em `customerId` não existe nesta conta
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: NOT_FOUND
message: Resource not found
'409':
description: >-
Pix Automático não habilitado na conta, periodicidade não aceita,
dados do pagador incompletos, ou falha ao gerar a cobrança
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: CONFLICT
message: No refundable payment found
'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)
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.