> ## 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 pedido
> Cria um pedido com um ou mais pagamentos (`payments`), como um cartão, dois cartões ou cartão + PIX. A soma de `items[].amount × items[].quantity` precisa ser igual à soma de `payments[].amount`. Todos os valores são em centavos.
**Captura.** Um pagamento com cartão sem `capture_method` usa `manual`: o valor é autorizado e o pedido fica em `requires_capture` até você chamar `POST /v2/orders/{id}/capture`. Com `capture_method: automatic`, a venda é direta, mas só em pedidos com um único pagamento. Em pedidos com dois ou mais pagamentos, todo cartão é pré-autorizado. Em cartão + PIX, o cartão é capturado automaticamente quando o PIX é pago.
**201 não significa pago.** A resposta traz o resultado da autorização: `requires_capture`, `requires_action` (QR Code PIX ou verificação por código em `next_action`), `processing` (venda aceita, aguardando confirmação) ou `failed` (HTTP 402, com `failure_reason`). A confirmação do pagamento chega por webhook (`order.paid`, `charge.paid`).
**Tudo ou nada.** Se um dos pagamentos for recusado, os pagamentos já autorizados são desfeitos e o pedido falha.
**`201 Created` não significa pago.** O pedido pode voltar em `requires_capture`, `requires_action` ou `processing`. A confirmação chega pelos webhooks `order.paid` e `charge.paid`. Um pagamento recusado responde `402`, com o pedido completo e o motivo em `failure_reason`.
Envie **um ou mais pagamentos** em `payments`. Um pedido com vários pagamentos é tudo ou nada: se um for recusado, os demais são desfeitos.
Sem `capture_method`, um pagamento com cartão usa captura **manual** e o pedido fica em `requires_capture` até você chamar [`/capture`](/pages/v2/pedidos/capture). Com `capture_method: "automatic"`, a venda é direta só quando o pedido tem **um único** pagamento. Em cartão + PIX, o cartão é capturado automaticamente quando o PIX é pago. Veja [Captura](/pages/v2/pedidos/reference#captura).
Para cobrar um cartão salvo, envie `card.token` com o `id` do [cartão](/pages/v2/cartoes/reference) no lugar dos dados do cartão.
A soma dos itens (`amount × quantity`) precisa ser igual à soma dos pagamentos. Com cartão no pedido, o `pix_expiration` pode ser de no máximo 86400 segundos. Pular a análise de fraude (`fraud_analysis`) exige permissão da conta.
Limite de **2 tentativas por minuto** do mesmo comprador para os mesmos itens (`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/orders
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/orders:
post:
tags:
- Pedidos (v2)
summary: Criar pedido
description: >
Cria um pedido com um ou mais pagamentos (`payments`), como um cartão,
dois cartões ou cartão + PIX. A soma de `items[].amount ×
items[].quantity` precisa ser igual à soma de `payments[].amount`. Todos
os valores são em centavos.
**Captura.** Um pagamento com cartão sem `capture_method` usa `manual`:
o valor é autorizado e o pedido fica em `requires_capture` até você
chamar `POST /v2/orders/{id}/capture`. Com `capture_method: automatic`,
a venda é direta, mas só em pedidos com um único pagamento. Em pedidos
com dois ou mais pagamentos, todo cartão é pré-autorizado. Em cartão +
PIX, o cartão é capturado automaticamente quando o PIX é pago.
**201 não significa pago.** A resposta traz o resultado da autorização:
`requires_capture`, `requires_action` (QR Code PIX ou verificação por
código em `next_action`), `processing` (venda aceita, aguardando
confirmação) ou `failed` (HTTP 402, com `failure_reason`). A confirmação
do pagamento chega por webhook (`order.paid`, `charge.paid`).
**Tudo ou nada.** Se um dos pagamentos for recusado, os pagamentos já
autorizados são desfeitos e o pedido falha.
operationId: v2CreateOrder
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V2CreateOrderRequest'
examples:
cartao_captura_manual:
summary: Cartão com captura manual
value:
currency: BRL
customer:
name: João Silva
email: joao@exemplo.com.br
phone:
ddi: '55'
ddd: '11'
number: '999999999'
document:
type: cpf
number: '12345678909'
payments:
- type: card
amount: 10000
capture_method: manual
card:
number: '4111111111111111'
holder_name: João Silva
exp_month: '12'
exp_year: '2030'
cvc: '123'
installments: 1
items:
- code: SKU-1
description: Camiseta Premium
quantity: 1
amount: 10000
metadata:
pedido_loja: '1024'
pix:
summary: PIX
value:
customer:
name: João Silva
email: joao@exemplo.com.br
phone:
ddi: '55'
ddd: '11'
number: '999999999'
payments:
- type: pix
amount: 5000
pix_expiration: 3600
items:
- code: SKU-2
description: Curso Online
quantity: 1
amount: 5000
cartao_e_pix:
summary: Cartão + PIX no mesmo pedido
value:
customer:
name: João Silva
email: joao@exemplo.com.br
phone:
ddi: '55'
ddd: '11'
number: '999999999'
payments:
- type: card
amount: 7000
card:
number: '4111111111111111'
holder_name: João Silva
exp_month: '12'
exp_year: '2030'
cvc: '123'
installments: 1
- type: pix
amount: 3000
pix_expiration: 3600
items:
- code: SKU-1
description: Camiseta Premium
quantity: 1
amount: 10000
cartao_salvo:
summary: Cartão salvo com split
value:
customer:
name: João Silva
email: joao@exemplo.com.br
phone:
ddi: '55'
ddd: '11'
number: '999999999'
payments:
- type: card
amount: 10000
capture_method: automatic
card:
token: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
installments: 1
split:
- receiver_code: rec_abc123
amount: 7000
options:
charge_processing_fee: true
charge_remainder_fee: true
liable: true
- receiver_code: rec_xyz456
amount: 3000
items:
- code: SKU-1
description: Camiseta Premium
quantity: 1
amount: 10000
responses:
'201':
description: >
Pedido criado. Confira o `status`: `requires_capture` (cartão
autorizado, aguardando captura), `requires_action` (PIX aguardando
pagamento ou verificação por código, veja `next_action`) ou
`processing` (venda aceita, aguardando confirmação). 201 não
significa pago.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Order'
examples:
cartao_captura_manual:
summary: Cartão autorizado, aguardando captura
value:
id: '482913'
object: order
status: requires_capture
currency: brl
amount: 10000
payments:
- id: cha_8Kq2Lm9XvB3nT7pZ
object: payment_intent
status: requires_capture
amount: 10000
amount_refunded: 0
currency: brl
payment_method_details:
type: card
card:
brand: visa
last_four: '1111'
holder_name: João Silva
next_action: null
pix:
summary: PIX aguardando pagamento
value:
id: '482914'
object: order
status: requires_action
currency: brl
amount: 5000
payments:
- id: cha_Ry5Wc1Hd7Nf3Jk9A
object: payment_intent
status: requires_action
amount: 5000
amount_refunded: 0
currency: brl
payment_method_details:
type: pix
pix:
qr_code: >-
00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
qr_code_url: https://pix.exemplo.com.br/qr/cha_Ry5Wc1Hd7Nf3Jk9A
expires_at: '2026-09-14T16:00:00.000000Z'
next_action:
type: pix_display_qr_code
pix:
qr_code: >-
00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
qr_code_url: https://pix.exemplo.com.br/qr/cha_Ry5Wc1Hd7Nf3Jk9A
expires_at: '2026-09-14T16:00:00.000000Z'
cartao_e_pix:
summary: Cartão autorizado + PIX aguardando pagamento
value:
id: '482915'
object: order
status: requires_action
currency: brl
amount: 10000
payments:
- id: cha_8Kq2Lm9XvB3nT7pZ
object: payment_intent
status: requires_capture
amount: 7000
amount_refunded: 0
currency: brl
payment_method_details:
type: card
card:
brand: visa
last_four: '1111'
holder_name: João Silva
- id: cha_Ry5Wc1Hd7Nf3Jk9A
object: payment_intent
status: requires_action
amount: 3000
amount_refunded: 0
currency: brl
payment_method_details:
type: pix
pix:
qr_code: >-
00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
qr_code_url: https://pix.exemplo.com.br/qr/cha_Ry5Wc1Hd7Nf3Jk9A
expires_at: '2026-09-14T16:00:00.000000Z'
next_action:
type: pix_display_qr_code
pix:
qr_code: >-
00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890
qr_code_url: https://pix.exemplo.com.br/qr/cha_Ry5Wc1Hd7Nf3Jk9A
expires_at: '2026-09-14T16:00:00.000000Z'
'400':
$ref: '#/components/responses/V2IdempotencyInvalid'
'401':
$ref: '#/components/responses/V2Unauthorized'
'402':
$ref: '#/components/responses/V2OrderPaymentFailed'
'403':
$ref: '#/components/responses/V2PurchaseBlocked'
'409':
$ref: '#/components/responses/V2IdempotencyInUse'
'422':
description: Dados inválidos ou composição de pagamento não aceita
content:
application/json:
schema:
$ref: '#/components/schemas/V2Error'
examples:
validation_error:
summary: Campo inválido
value:
error:
type: invalid_request_error
code: validation_error
message: The items must sum to the total amount of all payments.
param: items
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: payments.0.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.
unsupported_payment_method_combination:
summary: Combinação de meios de pagamento não suportada
value:
error:
type: invalid_request_error
code: unsupported_payment_method_combination
message: Esta combinação de meios de pagamento não é suportada.
acquirer_feature_not_supported:
summary: Nenhuma adquirente da conta suporta a composição
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:
V2CreateOrderRequest:
type: object
description: >
A soma de `items[].amount × items[].quantity` precisa ser igual à soma
de `payments[].amount`. Todos os valores são em centavos.
required:
- customer
- payments
- items
properties:
currency:
type: string
enum:
- BRL
- USD
default: BRL
customer:
$ref: '#/components/schemas/V2Customer'
payments:
type: array
minItems: 1
description: >-
Um ou mais meios de pagamento. Todos são processados juntos, no
mesmo pedido
items:
$ref: '#/components/schemas/V2OrderPayment'
items:
type: array
minItems: 1
items:
$ref: '#/components/schemas/V2OrderItem'
fraud_analysis:
$ref: '#/components/schemas/V2FraudAnalysis'
metadata:
type: object
nullable: true
additionalProperties: true
description: Dados livres da sua integração
example:
pedido_loja: '1024'
V2Order:
type: object
description: >
Pedido. O `status` é a agregação dos seus pagamentos. `processing`: em
processamento. `requires_capture`: cartão autorizado, aguardando
captura. `requires_action`: PIX aguardando pagamento ou verificação por
código (veja `next_action`). `paid`: pago. `failed`: recusado (veja
`failure_reason`). `canceled`: cancelado. `refunded` e
`partially_refunded`: estornado. `chargeback`: contestado.
properties:
id:
type: string
description: Código do pedido
example: '482913'
object:
type: string
enum:
- order
status:
type: string
enum:
- processing
- requires_capture
- requires_action
- paid
- failed
- canceled
- refunded
- partially_refunded
- chargeback
currency:
type: string
example: brl
amount:
type: integer
description: Valor total, em centavos
example: 10000
payments:
type: array
items:
$ref: '#/components/schemas/V2PaymentIntent'
next_action:
nullable: true
allOf:
- $ref: '#/components/schemas/V2NextAction'
failure_reason:
$ref: '#/components/schemas/V2FailureReason'
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
V2Customer:
type: object
description: >
Dados do comprador. A API v2 não tem recurso de cliente: envie o
comprador em cada requisição.
required:
- name
- email
- phone
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: string
description: Código do país
example: '55'
ddd:
type: string
description: Código de área
example: '11'
number:
type: string
example: '999999999'
document:
type: object
description: Documento do comprador (opcional no pedido)
properties:
type:
type: string
description: Tipo do documento
example: cpf
number:
type: string
example: '12345678909'
V2OrderPayment:
type: object
description: Um meio de pagamento do pedido
required:
- amount
properties:
type:
type: string
enum:
- card
- pix
default: card
description: Meio de pagamento. Sem `type`, o pagamento é tratado como cartão
amount:
type: integer
minimum: 1
description: Valor deste pagamento, em centavos
example: 10000
capture_method:
type: string
enum:
- automatic
- manual
default: manual
description: >
Só para cartão. `manual` (padrão) autoriza o valor e deixa o pedido
em `requires_capture` até `POST /v2/orders/{id}/capture`.
`automatic` faz a venda direta, mas só em pedidos com um único
pagamento: em pedidos com dois ou mais pagamentos, todo cartão é
pré-autorizado. Em cartão + PIX, o cartão é capturado
automaticamente quando o PIX é pago.
card:
$ref: '#/components/schemas/V2OrderCardInput'
pix_expiration:
type: integer
minimum: 1
description: >
Só para PIX. Tempo de expiração do QR Code, em segundos. Quando o
pedido também tem cartão, o máximo é 86400 (24 horas), porque o
cartão fica pré-autorizado até o PIX ser pago.
example: 3600
split:
type: array
description: >
Divisão deste pagamento entre recebedores. A soma de
`split[].amount` precisa ser igual ao `amount` deste pagamento. Uma
configuração de split inválida retorna 422 (`split_error`).
items:
$ref: '#/components/schemas/V2SplitRecipient'
V2OrderItem:
type: object
required:
- description
- quantity
- amount
properties:
code:
type: string
maxLength: 255
nullable: true
description: Código do item na sua conta
example: SKU-1
description:
type: string
maxLength: 255
example: Camiseta Premium
quantity:
type: integer
minimum: 1
example: 1
amount:
type: integer
minimum: 1
description: Valor unitário, em centavos
example: 10000
category:
type: string
maxLength: 255
nullable: true
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
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.
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.
V2OrderCardInput:
type: object
description: >
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. Dispensa os demais dados do
cartão
example: 9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f
number:
type: string
minLength: 13
description: Número do cartão. Obrigatório sem `token`
example: '4111111111111111'
holder_name:
type: string
description: Nome impresso no cartão. Obrigatório sem `token`
example: João Silva
exp_month:
type: string
description: Mês de validade. Obrigatório sem `token`
example: '12'
exp_year:
type: string
description: Ano de validade. Obrigatório sem `token`
example: '2030'
cvc:
type: string
description: Código de segurança. Obrigatório sem `token`
example: '123'
installments:
type: integer
minimum: 1
description: Número de parcelas
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)
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.
V2OrderPaymentFailed:
description: >
Pagamento recusado. Não é erro de requisição: o corpo traz o pedido
completo com `status: failed` e o motivo em `failure_reason`. Exiba ao
pagador o `customer_message`, nunca o `message`.
content:
application/json:
schema:
$ref: '#/components/schemas/V2Order'
example:
id: '482913'
object: order
status: failed
currency: brl
amount: 10000
payments:
- id: cha_8Kq2Lm9XvB3nT7pZ
object: payment_intent
status: failed
amount: 10000
amount_refunded: 0
currency: brl
payment_method_details:
type: card
card:
brand: visa
last_four: '1111'
holder_name: João Silva
next_action: null
failure_reason:
code: insufficient_funds
message: O cartão não possui saldo suficiente para concluir o pagamento.
customer_message: >-
Não foi possível concluir o pagamento. Revise os dados
informados ou tente outro meio de pagamento.
merchant_message: >-
O pagamento não foi concluído. Oriente o comprador a revisar os
dados informados ou tentar outro meio de pagamento.
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.
````