> ## 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.
# Buscar autorização por ID
> Retorna o estado atual de uma autorização de Pix Automático — se o pagador já autorizou e se ela está vinculada a uma assinatura.
`GET /pix-authorizations/:id`
Faz parte do recurso [Pix Automático](/pt-BR/pix-authorizations) — a tabela de status e o que produz
cada um estão lá.
Devolve a autorização como ela está agora. O webhook é o caminho principal para saber que o pagador
autorizou ou revogou; esta consulta serve para conferir o estado quando você perdeu um evento ou
precisa decidir algo na hora — por exemplo, antes de criar a assinatura.
**ID de outra conta responde `404`.** A autorização pertence à conta da chave que a abriu; fora
dela, o endereço não existe.
**O QR não volta nesta consulta.** `charge` só vem na resposta da
[abertura](/pt-BR/pix-authorizations/create). O primeiro pagamento continua consultável pela
transação de `charge.transactionId`.
## Exemplo
```bash theme={null}
curl https://api.sandbox.z2pay.com/v1/pix-authorizations/pxa_j43n74fbt2geb8c1y86ssf6iw \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX"
```
```json Resposta 200 theme={null}
{
"id": "pxa_j43n74fbt2geb8c1y86ssf6iw",
"customerId": "cust_hqx4mkpi8dcxbrb2nzynxnjky",
"subscriptionId": "sub_m4n6b8v0c2x4z6a8s0d2f4g6h",
"status": "active",
"frequency": "monthly",
"endDay": null,
"createdAt": "2026-08-31T14:22:05.000Z",
"updatedAt": "2026-08-31T14:24:40.000Z"
}
```
## OpenAPI
````yaml openapi/psp.json GET /pix-authorizations/{id}
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/{id}:
get:
tags:
- Pix Automático
summary: Consultar autorização
description: >-
Estado atual da autorização. `pending` aguarda o pagador; `active` está
debitando; `canceled` e `expired` são finais — uma autorização encerrada
não volta, e uma nova adesão cria outra autorização.
operationId: PixAuthorizationController_get
parameters:
- name: id
in: path
required: true
description: ID da autorização (`pxa_`)
schema:
type: string
responses:
'200':
description: Autorização
content:
application/json:
example:
id: pxa_j43n74fbt2geb8c1y86ssf6iw
customerId: cust_hqx4mkpi8dcxbrb2nzynxnjky
subscriptionId: sub_m4n6b8v0c2x4z6a8s0d2f4g6h
status: active
frequency: monthly
recurrenceBeginningDay: '2026-09-01'
endDay: null
createdAt: '2026-08-31T14:22:05.000Z'
updatedAt: '2026-08-31T14:24:40.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.
'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: Autorização não encontrada 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
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.