Skip to main content

​
Visão Geral

Os Pedidos (Orders) são gerados automaticamente quando uma cobrança é criada. Um pedido pode conter múltiplas cobranças (charges).

​
Status de um Pedido

StatusDescrição
PendingAguardando processamento ou pagamento (ex: PIX pendente)
ChallengedRequer verificação adicional do cliente (OTP)
ApprovedPedido aprovado e pago com sucesso
DeclinedPedido recusado pela operadora/gateway
RefundedPagamento estornado para o cliente
CanceledPedido cancelado

​
Pedidos Desafiados (Challenged)

Quando um pedido entra no status Challenged, o cliente precisa confirmar a identidade antes que o pagamento seja processado. Isso pode ocorrer por:
  • OTP — código de verificação enviado por SMS ou e-mail
  • Magic Link — link de verificação enviado por e-mail

​
Fluxo de confirmação

1. POST /v1/charge → status: Challenged (HTTP 202)
2. GET  /v1/orders/{code}/confirmations → lista os desafios pendentes
3. POST /v1/orders/{code}/confirmations/{id}/verify → submete o código OTP
   OU
   POST /v1/orders/{code}/confirmations/{id}/resend → reenvia o código

​
Campos de uma Confirmação

CampoTipoDescrição
idstringUUID identificador da confirmação
typestringTipo: otp, magic_link
statusstringpending, verified, expired, canceled
expires_atdatetimeData de expiração do desafio (nullable)
Confirmações têm prazo de expiração (15 minutos). Após expirar, use a rota /resend para gerar um novo código.

​
Formato de resposta

A rota de listagem de confirmações (GET .../confirmations) retorna diretamente {"data": [...]}, sem o envelope padrão APIReturnUtil. Já as rotas de verificação e reenvio utilizam o envelope padrão com os campos mensagem, erro, mensagenserro, codigoretorno, id e data.
A rota de verificação (/verify) processa as cobranças pendentes do pedido e retorna o mesmo formato da criação de cobrança (HTTP 201 com dados da cobrança no campo data).