> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4seletpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Consultar fatura
> Consulta uma fatura de assinatura pelo `id`. O status da fatura reflete o último pagamento: uma fatura recusada pode ser paga de novo com `POST /v2/invoices/{id}/pay`.
O `id` da fatura é um código numérico de 6 dígitos, como `482913`. Ele aparece em `latest_invoice.id` da assinatura e na [listagem de faturas](/pages/v2/assinaturas/invoices).
Esta rota encontra apenas faturas de assinaturas. O identificador de um pedido avulso retorna `404` (`resource_missing`). Para pedidos, use [Consultar pedido](/pages/v2/pedidos/get).
Quando `status` é `failed`, a resposta traz o motivo em `failure_reason`. Quando o cliente precisa agir, `next_action` traz o QR Code PIX ou os dados do código de verificação.
## OpenAPI
````yaml GET /v2/invoices/{id}
openapi: 3.1.0
info:
title: 4Selet Pay API
description: >
API de processamento de pagamentos da plataforma 4Selet Pay. Suporta
cobranças únicas, assinaturas recorrentes, PIX, Cartão de Crédito. Todas as
rotas autenticadas requerem um Bearer Token obtido via `/v1/login`.
version: 1.0.0
contact:
name: 4Selet Pay
email: suporte@4selet.com.br
servers:
- url: https://sandbox.4seletpay.com.br/api
description: Servidor de Sandbox
security:
- bearerAuth: []
tags:
- name: Autenticação
description: Rotas de autenticação e criação de usuários
- name: Cobranças
description: Criação, consulta, cancelamento e reembolso de cobranças
- name: Pedidos
description: Consulta de pedidos e gerenciamento de confirmações desafiadas
- name: Cartões
description: Cadastro e gerenciamento dos cartões salvos de um cliente
- name: Assinaturas
description: Criação e gerenciamento de assinaturas recorrentes
- name: Faturas
description: Gerenciamento de faturas e pagamento de faturas em atraso
- name: Clientes Bloqueados
description: Gerenciamento de lista negra de clientes
- name: Contas
description: Criação e gerenciamento de contas na plataforma
- name: Aplicativo
description: Endpoints para dashboard e uso via aplicativo mobile
- name: Notificações Push
description: Envio e gerenciamento de notificações push
- name: Utilitários
description: Endpoints utilitários como listagem de fusos horários
- name: Gestão
description: Relatórios gerenciais (acesso restrito a Super Admins)
- name: Webhooks
description: Endpoints para receber notificações de gateways de pagamento
- name: Endpoints de Webhook
description: >-
Gerenciamento de endpoints de webhook para receber notificações de eventos
da plataforma
- name: Links de Pagamento
description: Criação e gerenciamento de links de pagamento com checkout pré-configurado
- name: Análise de Fraude
description: >-
API de Risco — consulta o risco de fraude de uma transação (autenticada
por chave de API)
- name: Pedidos (v2)
description: >-
API v2 — pedidos com um ou mais meios de pagamento, captura, cancelamento
e verificação por código
- name: Cobranças (v2)
description: API v2 — consulta e estorno de cobranças
- name: Cartões (v2)
description: API v2 — cadastro e consulta de cartões salvos
- name: Assinaturas (v2)
description: API v2 — criação e gerenciamento de assinaturas recorrentes
- name: Faturas (v2)
description: >-
API v2 — consulta, pagamento e verificação por código das faturas de
assinaturas
paths:
/v2/invoices/{id}:
get:
tags:
- Faturas (v2)
summary: Consultar fatura
description: >
Consulta uma fatura de assinatura pelo `id`. O status da fatura reflete
o último pagamento: uma fatura recusada pode ser paga de novo com `POST
/v2/invoices/{id}/pay`.
operationId: v2RetrieveInvoice
parameters:
- $ref: '#/components/parameters/V2Id'
responses:
'200':
description: Fatura encontrada
content:
application/json:
schema:
$ref: '#/components/schemas/V2Invoice'
'401':
$ref: '#/components/responses/V2Unauthorized'
'403':
$ref: '#/components/responses/V2AccountBlocked'
'404':
$ref: '#/components/responses/V2InvoiceNotFound'
'429':
$ref: '#/components/responses/V2ThrottleExceeded'
security:
- secretKeyAuth: []
components:
parameters:
V2Id:
name: id
in: path
required: true
description: Identificador do recurso (o campo `id` devolvido pela API)
schema:
type: string
schemas:
V2Invoice:
type: object
description: >
Fatura de um ciclo da assinatura. `processing`: em processamento.
`requires_action`: PIX aguardando pagamento ou verificação por código
(veja `next_action`). `paid`: paga. `failed`: recusada (veja
`failure_reason`). `canceled`: cancelada. `refunded` e
`partially_refunded`: estornada. `chargeback`: contestada.
properties:
id:
type: string
example: '719305'
object:
type: string
enum:
- invoice
subscription:
type: string
example: sub_4Hn8Qw2Rt6Yp1Zx3
number:
type: integer
description: Número da fatura na assinatura
example: 1
status:
type: string
enum:
- processing
- requires_action
- paid
- failed
- canceled
- refunded
- partially_refunded
- chargeback
currency:
type: string
example: brl
amount:
type: integer
description: Valor da fatura, em centavos, já com descontos e acréscimos
example: 9000
attempts:
type: integer
description: Tentativas de cobrança
items:
type: array
items:
$ref: '#/components/schemas/V2SubscriptionItem'
discounts:
type: array
items:
$ref: '#/components/schemas/V2SubscriptionAdjustment'
increments:
type: array
items:
$ref: '#/components/schemas/V2SubscriptionAdjustment'
payments:
type: array
items:
$ref: '#/components/schemas/V2PaymentIntent'
next_action:
nullable: true
allOf:
- $ref: '#/components/schemas/V2NextAction'
created_at:
type: string
failure_reason:
$ref: '#/components/schemas/V2FailureReason'
V2SubscriptionItem:
type: object
required:
- code
- description
- quantity
- amount
properties:
code:
type: string
maxLength: 255
example: SKU-SUB
description:
type: string
maxLength: 255
example: Assinatura
quantity:
type: integer
minimum: 1
example: 1
amount:
type: integer
minimum: 1
description: Valor unitário, em centavos
example: 10000
V2SubscriptionAdjustment:
type: object
required:
- type
- value
properties:
type:
type: string
enum:
- fixed
- percentage
value:
type: number
exclusiveMinimum: 0
description: >
Em `fixed`, valor inteiro em centavos. Em `percentage`, percentual
(em descontos, no máximo 100).
example: 1000
invoice_number:
type: integer
minimum: 1
nullable: true
description: >-
Número da fatura a que o ajuste se aplica. Sem valor, vale para
todas as faturas
example: 1
V2PaymentIntent:
type: object
description: >
Um meio de pagamento dentro de um pedido ou fatura. O `id` é o mesmo da
cobrança (`GET /v2/charges/{id}`).
properties:
id:
type: string
example: cha_8Kq2Lm9XvB3nT7pZ
object:
type: string
enum:
- payment_intent
status:
type: string
enum:
- requires_action
- requires_capture
- processing
- paid
- failed
- canceled
- refund_processing
- partially_refunded
- refunded
- chargeback
description: >
`requires_action`: PIX aguardando pagamento ou verificação por
código. `requires_capture`: cartão autorizado, aguardando captura.
`processing`: em processamento. `paid`: pago. `failed`: recusado.
`canceled`: cancelado. `refund_processing`: estorno em
processamento. `partially_refunded` e `refunded`: estornado em parte
ou totalmente. `chargeback`: contestado pelo portador.
amount:
type: integer
description: Valor em centavos
example: 10000
amount_refunded:
type: integer
description: Valor estornado, em centavos
example: 0
currency:
type: string
example: brl
payment_method_details:
type: object
properties:
type:
type: string
enum:
- card
- pix
- boleto
card:
type: object
description: Presente em pagamentos com cartão
properties:
brand:
type: string
example: visa
last_four:
type: string
example: '1111'
holder_name:
type: string
example: João Silva
pix:
$ref: '#/components/schemas/V2Pix'
V2NextAction:
type: object
description: >
O que precisa acontecer para o pagamento seguir. `pix_display_qr_code`:
exiba o QR Code para o pagador. `otp_confirmation`: a análise de fraude
pediu verificação — nada é cobrado até o código ser confirmado na rota
`/confirm`.
properties:
type:
type: string
enum:
- pix_display_qr_code
- otp_confirmation
pix:
$ref: '#/components/schemas/V2Pix'
otp:
type: object
description: Presente quando `type` é `otp_confirmation`
properties:
confirmation_id:
type: string
example: 5f1c2a9e-7b3d-4e8f-9a6c-1d2e3f4a5b6c
expires_at:
type: string
description: Data e hora de expiração do código
example: '2026-09-14T12:15:00.000000Z'
V2FailureReason:
type: object
description: Motivo da recusa. Presente só quando o status é `failed`
required:
- code
- message
- customer_message
- merchant_message
properties:
code:
type: string
enum:
- card_declined
- insufficient_funds
- expired_card
- incorrect_cvc
- incorrect_number
- card_not_supported
- fraud_suspected
- invalid_request
- acquirer_error
- processing_error
message:
type: string
description: Texto técnico. Não exiba ao pagador
example: O cartão não possui saldo suficiente para concluir o pagamento.
customer_message:
type: string
description: Texto para exibir ao pagador
example: >-
Não foi possível concluir o pagamento. Revise os dados informados ou
tente outro meio de pagamento.
merchant_message:
type: string
description: Texto para você ou a sua equipe de atendimento
example: >-
O pagamento não foi concluído. Oriente o comprador a revisar os
dados informados ou tentar outro meio de pagamento.
V2Error:
type: object
description: Envelope de erro da API v2
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
enum:
- invalid_request_error
- idempotency_error
- authentication_error
- api_error
description: Categoria do erro
code:
type: string
description: Código estável do erro. Use este campo na sua lógica
example: validation_error
message:
type: string
description: Texto técnico, para log e depuração. Não exiba ao pagador
example: The payments field is required.
param:
type: string
description: >-
Campo que causou o erro, em notação de ponto. Presente só quando
se aplica
example: payments
customer_message:
type: string
description: Texto para exibir ao pagador. Presente só quando se aplica
V2ThrottleError:
type: object
description: >
Corpo padrão, fora do envelope `error`, do limite geral de requisições e
do limite de reenvio do código de verificação
properties:
message:
type: string
example: Too Many Attempts.
V2Pix:
type: object
properties:
qr_code:
type: string
description: Código PIX copia e cola
example: 00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
qr_code_url:
type: string
description: Link do QR Code
example: https://pix.exemplo.com.br/qr/cha_8Kq2Lm9XvB3nT7pZ
expires_at:
type: string
description: Data e hora de expiração do QR Code
example: '2026-09-14T16:00:00.000000Z'
responses:
V2Unauthorized:
description: Chave de API ausente, inválida, revogada ou de outro ambiente
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: authentication_error
code: invalid_api_secret
message: Invalid API secret.
V2AccountBlocked:
description: >-
As requisições da conta estão bloqueadas. A resposta traz
`customer_message`
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: invalid_request_error
code: account_requests_blocked
message: As requisições desta conta estão bloqueadas.
customer_message: >-
Não foi possível concluir sua transação. Tente novamente mais
tarde.
V2InvoiceNotFound:
description: Fatura não encontrada nesta conta
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: invalid_request_error
code: resource_missing
message: Recurso "invoice" não encontrado.
V2ThrottleExceeded:
description: >
Limite geral de requisições excedido (120 por minuto por chave de API e
por conta). Esta resposta não usa o envelope `error` da API v2.
headers:
X-RateLimit-Limit:
description: Limite de requisições da janela
schema:
type: integer
X-RateLimit-Remaining:
description: Requisições restantes na janela
schema:
type: integer
Retry-After:
description: Segundos até a próxima tentativa
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/V2ThrottleError'
example:
message: Too Many Attempts.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Token JWT obtido via `POST /v1/login`. Envie no header `Authorization:
Bearer `.
secretKeyAuth:
type: http
scheme: bearer
description: >
Chave de API (secret key) da conta, no formato `sk_live_...` (produção)
ou `sk_test_...` (Dev mode). Envie no header `Authorization: Bearer
`. Autentica todas as rotas da API v2 e as rotas de Análise de
Fraude. A chave identifica a conta, então a API v2 não usa o header
`account`. Uma chave só é aceita no ambiente em que foi criada. Gere a
sua no dashboard em Configurações → Chaves de API.
````