> ## 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.
# Criar assinatura
> Cria uma assinatura recorrente. Sem `start_at`, a primeira fatura é cobrada na criação e vem em `latest_invoice`. Com `start_at` futuro, a assinatura fica `scheduled` e nada é cobrado agora. Se a primeira fatura for recusada, a resposta é 402 e a assinatura fica `incomplete_expired`.
**Intervalo.** `interval` é `day` ou `week`, com `interval_count`. Não existe mês de calendário: uma cobrança "mensal" é `day` × 30 e a data desliza em relação ao dia do mês. O intervalo total não pode passar de 365 dias.
**Regras.** Valores fixos de `discounts` e `increments` são inteiros em centavos; descontos percentuais vão até 100. `split` não pode ser combinado com descontos ou acréscimos. `minimum_price` é aceito e devolvido, mas ainda não é aplicado na cobrança. Não existe webhook de assinatura criada: a primeira fatura vem na própria resposta.
**`201` não significa pago.** Sem `start_at`, a primeira fatura é cobrada na criação e volta em `latest_invoice`. Com cartão, ela costuma ficar em `processing` até a confirmação; com PIX, fica em `requires_action` com o QR Code em `latest_invoice.next_action`. Se a primeira fatura for recusada, a resposta é `402` com a assinatura em `incomplete_expired` e o motivo em `latest_invoice.failure_reason`.
Todos os valores são em **centavos** (`10000` = R\$ 100,00). O intervalo é `interval` (`day` ou `week`) × `interval_count`, com no máximo **365 dias**. Não existe mês de calendário: uma assinatura "mensal" é `day` × `30` e a data de cobrança desliza em relação ao calendário. Veja [Intervalo de cobrança](/pages/v2/assinaturas/reference#intervalo-de-cobrança).
Com `start_at` (a partir de amanhã), a assinatura nasce `scheduled` e **nada é cobrado** na criação.
Para usar um cartão salvo, envie `payment.card.token` com o `id` retornado por [`POST /v2/cards`](/pages/v2/cartoes/create). Sem token, envie `number`, `holder_name`, `exp_month`, `exp_year` e `cvc`.
O campo `minimum_price` é aceito e devolvido, mas **não é aplicado** na cobrança das faturas.
Esta rota passa pelo bloqueio de clientes (`403` `customer_blocked`) e pelo limite por comprador (`429` `rate_limit_exceeded`). Envie o header `Idempotency-Key` para reenviar com segurança. Veja [Idempotência e limites](/pages/v2/start/idempotencia-e-limites).
## OpenAPI
````yaml POST /v2/subscriptions
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/subscriptions:
post:
tags:
- Assinaturas (v2)
summary: Criar assinatura
description: >
Cria uma assinatura recorrente. Sem `start_at`, a primeira fatura é
cobrada na criação e vem em `latest_invoice`. Com `start_at` futuro, a
assinatura fica `scheduled` e nada é cobrado agora. Se a primeira fatura
for recusada, a resposta é 402 e a assinatura fica `incomplete_expired`.
**Intervalo.** `interval` é `day` ou `week`, com `interval_count`. Não
existe mês de calendário: uma cobrança "mensal" é `day` × 30 e a data
desliza em relação ao dia do mês. O intervalo total não pode passar de
365 dias.
**Regras.** Valores fixos de `discounts` e `increments` são inteiros em
centavos; descontos percentuais vão até 100. `split` não pode ser
combinado com descontos ou acréscimos. `minimum_price` é aceito e
devolvido, mas ainda não é aplicado na cobrança. Não existe webhook de
assinatura criada: a primeira fatura vem na própria resposta.
operationId: v2CreateSubscription
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V2CreateSubscriptionRequest'
example:
code: plano-anual-123
description: Plano de teste
interval: week
interval_count: 2
max_invoices: 12
customer:
name: João Silva
email: joao@exemplo.com.br
phone:
ddi: 55
ddd: 11
number: '999999999'
document:
type: cpf
number: '12345678909'
items:
- code: SKU-SUB
description: Assinatura
quantity: 1
amount: 10000
payment:
type: card
card:
number: '4111111111111111'
holder_name: João Silva
exp_month: '12'
exp_year: '2030'
cvc: '123'
installments: 1
discounts:
- type: fixed
value: 1000
invoice_number: 1
increments:
- type: percentage
value: 10
invoice_number: 2
responses:
'201':
description: >
Assinatura criada. Com cobrança imediata, o status fica `incomplete`
até a primeira fatura ser paga (a confirmação chega por webhook
`invoice.paid`). Com `start_at` futuro, fica `scheduled`.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Subscription'
example:
id: sub_4Hn8Qw2Rt6Yp1Zx3
object: subscription
code: plano-anual-123
status: incomplete
currency: brl
description: Plano de teste
interval: week
interval_count: 2
billing_type: prepaid
amount: 10000
items:
- code: SKU-SUB
description: Assinatura
quantity: 1
amount: 10000
discounts:
- type: fixed
value: 1000
invoice_number: 1
increments:
- type: percentage
value: 10
invoice_number: 2
max_invoices: 12
invoices_paid: 0
minimum_price: null
payment_method:
type: card
installments: 1
card:
token: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
brand: visa
last_four: '1111'
holder_name: João Silva
statement_descriptor: null
start_at: '2026-09-14T00:00:00-03:00'
next_billing_at: '2026-09-28T00:00:00-03:00'
created_at: '2026-09-14T12:00:00-03:00'
customer:
name: João Silva
email: joao@exemplo.com.br
latest_invoice:
id: '719305'
object: invoice
subscription: sub_4Hn8Qw2Rt6Yp1Zx3
number: 1
status: processing
currency: brl
amount: 9000
attempts: 1
items:
- code: SKU-SUB
description: Assinatura
quantity: 1
amount: 10000
discounts:
- type: fixed
value: 1000
invoice_number: 1
increments: []
payments:
- id: cha_8Kq2Lm9XvB3nT7pZ
object: payment_intent
status: processing
amount: 9000
amount_refunded: 0
currency: brl
payment_method_details:
type: card
card:
brand: visa
last_four: '1111'
holder_name: João Silva
next_action: null
created_at: '2026-09-14T12:00:00-03:00'
metadata: {}
'400':
$ref: '#/components/responses/V2IdempotencyInvalid'
'401':
$ref: '#/components/responses/V2Unauthorized'
'402':
description: >
A primeira fatura foi recusada. Não é erro de requisição: o corpo
traz a assinatura com `status: incomplete_expired` e o motivo em
`latest_invoice.failure_reason`.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Subscription'
'403':
$ref: '#/components/responses/V2PurchaseBlocked'
'409':
$ref: '#/components/responses/V2IdempotencyInUse'
'422':
description: Dados inválidos ou configuração não aceita
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
examples:
validation_error:
summary: Intervalo acima do limite
value:
error:
type: invalid_request_error
code: validation_error
message: The billing interval cannot exceed 365 days.
param: interval_count
card_token_invalid:
summary: Cartão salvo não encontrado nesta conta
value:
error:
type: invalid_request_error
code: card_token_invalid
message: >-
O cartão salvo informado não foi encontrado para esta
conta.
param: payment.card.token
split_error:
summary: Split inválido
value:
error:
type: invalid_request_error
code: split_error
message: A configuração de split informada é inválida.
param: split
fraud_bypass_not_allowed:
summary: Conta sem permissão para pular a análise de fraude
value:
error:
type: invalid_request_error
code: fraud_bypass_not_allowed
message: >-
Esta conta não tem permissão para pular a análise de
fraude.
acquirer_feature_not_supported:
summary: Nenhuma adquirente da conta suporta a assinatura
value:
error:
type: invalid_request_error
code: acquirer_feature_not_supported
message: >-
Nenhuma adquirência habilitada para esta conta suporta
esta composição de pagamentos.
idempotency_key_conflict:
summary: Idempotency-Key usada com outro corpo
value:
error:
type: idempotency_error
code: idempotency_key_conflict
message: >-
The Idempotency-Key has already been used with a
different request body.
'429':
$ref: '#/components/responses/V2BuyerRateLimited'
'500':
$ref: '#/components/responses/V2ServerError'
security:
- secretKeyAuth: []
components:
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: >
Chave de idempotência opcional e recomendada. Tem até 128 caracteres e
vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a
resposta original (mesmo status e mesmo corpo), sem processar de novo.
Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode
ser reutilizada. A mesma chave com um corpo diferente retorna 422
(`idempotency_key_conflict`), uma requisição original ainda em andamento
retorna 409 (`idempotency_key_in_use`) e uma chave com mais de 128
caracteres retorna 400 (`idempotency_key_invalid`).
schema:
type: string
maxLength: 128
example: pedido-1024-tentativa-1
schemas:
V2CreateSubscriptionRequest:
type: object
required:
- interval
- interval_count
- customer
- items
- payment
properties:
code:
type: string
maxLength: 255
nullable: true
description: Código da assinatura na sua integração
example: plano-anual-123
description:
type: string
maxLength: 255
nullable: true
example: Plano de teste
currency:
type: string
enum:
- BRL
- USD
default: BRL
international:
type: boolean
interval:
type: string
enum:
- day
- week
description: >
Unidade do intervalo entre cobranças. Não existe mês de calendário:
para uma cobrança mensal, use `day` com `interval_count: 30` — a
data desliza em relação ao dia do mês.
example: week
interval_count:
type: integer
minimum: 1
description: >-
Quantidade de unidades entre cobranças. O intervalo total não pode
passar de 365 dias
example: 2
billing_type:
type: string
enum:
- prepaid
default: prepaid
start_at:
type: string
format: date
nullable: true
description: >
Data da primeira cobrança, a partir de amanhã. Sem `start_at`, a
primeira fatura é cobrada na criação.
example: '2026-09-20'
max_invoices:
type: integer
minimum: 1
nullable: true
description: >-
Número máximo de faturas. Ao pagar a última, a assinatura fica
`completed`
example: 12
minimum_price:
type: integer
minimum: 0
nullable: true
description: Aceito e devolvido pela API, mas ainda não é aplicado na cobrança
statement_descriptor:
type: string
maxLength: 50
nullable: true
description: Texto na fatura do cartão
metadata:
type: object
nullable: true
additionalProperties: true
customer:
$ref: '#/components/schemas/V2SubscriptionCustomer'
items:
type: array
minItems: 1
items:
$ref: '#/components/schemas/V2SubscriptionItem'
payment:
$ref: '#/components/schemas/V2SubscriptionPaymentInput'
discounts:
type: array
nullable: true
items:
$ref: '#/components/schemas/V2SubscriptionAdjustment'
increments:
type: array
nullable: true
items:
$ref: '#/components/schemas/V2SubscriptionAdjustment'
split:
type: array
minItems: 1
maxItems: 10
description: >
Divisão de cada fatura entre recebedores. A soma de `split[].amount`
precisa ser igual ao total dos itens. Exatamente um recebedor com
`options.charge_processing_fee: true`, ao menos um com
`options.charge_remainder_fee: true` e ao menos um com
`options.liable: true`. Cada `receiver_code` (até 32 caracteres)
precisa pertencer à conta e estar ativo ou com ativação pendente.
Não pode ser combinado com `discounts` ou `increments`.
items:
$ref: '#/components/schemas/V2SplitRecipient'
fraud_analysis:
$ref: '#/components/schemas/V2FraudAnalysis'
V2Subscription:
type: object
description: >
Assinatura. `incomplete`: a primeira fatura ainda não foi paga.
`incomplete_expired`: a primeira fatura foi recusada. `scheduled`: a
primeira cobrança está agendada (`start_at`). `active`: em dia.
`past_due`: fatura em atraso. `suspended`: suspensa. `canceled`:
cancelada. `completed`: todas as faturas previstas foram pagas.
properties:
id:
type: string
example: sub_4Hn8Qw2Rt6Yp1Zx3
object:
type: string
enum:
- subscription
code:
type: string
nullable: true
example: plano-anual-123
status:
type: string
enum:
- incomplete
- incomplete_expired
- scheduled
- active
- past_due
- suspended
- canceled
- completed
currency:
type: string
example: brl
description:
type: string
nullable: true
interval:
type: string
enum:
- day
- week
interval_count:
type: integer
billing_type:
type: string
enum:
- prepaid
amount:
type: integer
description: Total dos itens, em centavos, sem descontos ou acréscimos
items:
type: array
items:
$ref: '#/components/schemas/V2SubscriptionItem'
discounts:
type: array
items:
$ref: '#/components/schemas/V2SubscriptionAdjustment'
increments:
type: array
items:
$ref: '#/components/schemas/V2SubscriptionAdjustment'
max_invoices:
type: integer
nullable: true
invoices_paid:
type: integer
description: Quantidade de faturas pagas
minimum_price:
type: integer
nullable: true
description: Aceito e devolvido pela API, mas ainda não é aplicado na cobrança
payment_method:
type: object
properties:
type:
type: string
enum:
- card
- pix
installments:
type: integer
description: Presente quando `type` é `card`
card:
type: object
nullable: true
description: Presente quando `type` é `card`
properties:
token:
type: string
description: O `id` do cartão salvo, para reutilizar em outras compras
example: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
brand:
type: string
example: visa
last_four:
type: string
example: '1111'
holder_name:
type: string
example: João Silva
statement_descriptor:
type: string
nullable: true
start_at:
type: string
nullable: true
next_billing_at:
type: string
nullable: true
created_at:
type: string
customer:
type: object
properties:
name:
type: string
email:
type: string
latest_invoice:
nullable: true
allOf:
- $ref: '#/components/schemas/V2Invoice'
metadata:
type: object
additionalProperties: true
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
V2SubscriptionCustomer:
description: Dados do comprador da assinatura
allOf:
- $ref: '#/components/schemas/V2CustomerWithDocument'
- type: object
properties:
ip:
type: string
description: Endereço IP do comprador (IPv4 ou IPv6)
example: 189.10.20.30
gender:
type: string
enum:
- male
- female
- other
birthdate:
type: string
format: date
description: Data de nascimento (YYYY-MM-DD)
example: '1990-05-20'
address:
type: object
description: >-
Endereço. Quando enviado, `zip_code`, `street`, `number`,
`neighborhood`, `city` e `state` são obrigatórios
required:
- zip_code
- street
- number
- neighborhood
- city
- state
properties:
zip_code:
type: string
maxLength: 20
example: '01310100'
street:
type: string
maxLength: 255
example: Avenida Paulista
number:
type: integer
example: 1000
neighborhood:
type: string
maxLength: 255
example: Bela Vista
city:
type: string
maxLength: 255
example: São Paulo
state:
type: string
maxLength: 2
example: SP
complement:
type: string
maxLength: 255
nullable: true
country:
type: string
maxLength: 255
nullable: true
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
V2SubscriptionPaymentInput:
type: object
required:
- type
properties:
type:
type: string
enum:
- card
- pix
card:
allOf:
- $ref: '#/components/schemas/V2SubscriptionCardInput'
- type: object
properties:
installments:
type: integer
minimum: 1
maximum: 12
description: Número de parcelas de cada fatura
example: 1
pix_expiration:
type: integer
minimum: 1
description: Tempo de expiração do QR Code, em segundos
example: 3600
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
V2SplitRecipient:
type: object
required:
- receiver_code
- amount
properties:
receiver_code:
type: string
description: Código do recebedor da sua conta
example: rec_abc123
amount:
type: integer
minimum: 1
description: Valor deste recebedor, em centavos
example: 7000
options:
type: object
properties:
charge_processing_fee:
type: boolean
description: Este recebedor paga a taxa de processamento
charge_remainder_fee:
type: boolean
description: Este recebedor fica com o restante da divisão
liable:
type: boolean
description: >-
Este recebedor é responsável pelo risco da transação
(chargeback)
V2FraudAnalysis:
type: object
description: >
Pula a análise de fraude. Exige permissão da conta — sem ela, a
requisição retorna 422 (`fraud_bypass_not_allowed`). Todo pulo precisa
de um motivo, que fica registrado.
required:
- skip
properties:
skip:
type: boolean
example: true
reason:
type: string
enum:
- upsell
- one_click
- trusted_customer
- external_analysis
description: >
Obrigatório quando `skip` é `true`. `upsell`: compra complementar em
uma sessão já analisada. `one_click`: cliente recorrente pagando com
cartão salvo. `trusted_customer`: cliente confiável para você.
`external_analysis`: você fez a sua própria análise de fraude.
example: upsell
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'
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.
V2CustomerWithDocument:
type: object
description: >
Dados do comprador, com documento obrigatório. A API v2 não tem recurso
de cliente: envie o comprador em cada requisição.
required:
- name
- email
- phone
- document
properties:
name:
type: string
maxLength: 255
example: João Silva
email:
type: string
format: email
example: joao@exemplo.com.br
phone:
type: object
required:
- ddi
- ddd
- number
properties:
ddi:
type: integer
description: Código do país
example: 55
ddd:
type: integer
description: Código de área
example: 11
number:
type: string
maxLength: 20
example: '999999999'
document:
type: object
required:
- type
- number
properties:
type:
type: string
enum:
- cpf
- cnpj
- passport
example: cpf
number:
type: string
maxLength: 50
example: '12345678909'
V2SubscriptionCardInput:
type: object
description: >
Obrigatório quando `payment.type` é `card`. Envie `token` (o `id` de um
cartão salvo) ou os dados completos do cartão (`number`, `holder_name`,
`exp_month`, `exp_year` e `cvc`).
properties:
token:
type: string
maxLength: 64
description: O `id` de um cartão salvo da sua conta
example: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
number:
type: string
minLength: 13
example: '4111111111111111'
holder_name:
type: string
maxLength: 255
example: João Silva
exp_month:
type: string
example: '12'
exp_year:
type: string
example: '2030'
cvc:
type: string
example: '123'
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.
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:
V2IdempotencyInvalid:
description: O header `Idempotency-Key` tem mais de 128 caracteres
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: invalid_request_error
code: idempotency_key_invalid
message: Idempotency-Key must be 128 characters or fewer.
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.
V2PurchaseBlocked:
description: >-
Conta, item ou comprador bloqueado. A resposta traz `customer_message`
para exibir ao pagador
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
examples:
customer_blocked:
summary: Comprador bloqueado (e-mail, documento ou BIN do cartão)
value:
error:
type: invalid_request_error
code: customer_blocked
message: Este comprador está bloqueado para novos pedidos.
customer_message: >-
Não foi possível concluir sua transação. Tente novamente
mais tarde.
item_purchases_blocked:
summary: Venda de um dos itens bloqueada
value:
error:
type: invalid_request_error
code: item_purchases_blocked
message: As compras de um dos itens deste pedido estão bloqueadas.
customer_message: >-
Não foi possível concluir sua transação. Tente novamente
mais tarde.
account_requests_blocked:
summary: Conta bloqueada
value:
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.
V2IdempotencyInUse:
description: >-
Uma requisição com a mesma `Idempotency-Key` ainda está em andamento.
Tente novamente em instantes
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: idempotency_error
code: idempotency_key_in_use
message: >-
A request with this Idempotency-Key is still being processed.
Retry shortly.
V2BuyerRateLimited:
description: >
Muitas tentativas do mesmo comprador (e-mail ou documento) para os
mesmos itens — resposta com o envelope `error` e `customer_message` — ou
limite geral de requisições excedido, com o corpo padrão `{ "message":
"Too Many Attempts." }`. As duas trazem o header `Retry-After`.
headers:
Retry-After:
description: Segundos até a próxima tentativa
schema:
type: integer
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/V2Error'
- $ref: '#/components/schemas/V2ThrottleError'
examples:
rate_limit_exceeded:
summary: Muitas tentativas do mesmo comprador
value:
error:
type: invalid_request_error
code: rate_limit_exceeded
message: >-
Muitas tentativas de pedido para este comprador. Tente
novamente mais tarde.
customer_message: >-
Não foi possível processar no momento devido a múltiplas
tentativas. Tente novamente em instantes.
too_many_attempts:
summary: Limite geral de requisições
value:
message: Too Many Attempts.
V2ServerError:
description: Erro inesperado ao processar a requisição
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
example:
error:
type: api_error
code: internal_error
message: Ocorreu um erro inesperado ao processar a requisição.
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.
````