API
Referência da API
10 min de leitura
Documentação completa de todos os endpoints, campos, tipos e respostas da API REST do Orquestraio.
Base URL
Produção
https://api.orquestraio.com
Self-hosted
http://localhost:8080
Autenticação
Todas as requisições exigem o header x-api-key com sua chave de API.
x-api-key: Oz_live_xxxxxxxxxxxxxxxx
# Ambiente de dev: orquestraio-livre-123
Chaves de produção têm prefixo Oz_live_. Chaves de teste têm prefixo Oz_test_. Ver Autenticação.
POST
/v1/payments
Cria um pagamento
Cria e processa um pagamento. O gateway de destino é determinado pelo campo metadata.gateway ou pelo SmartRouter quando omitido.
Request Body
Campo
Req
Descrição
idempotencyKey
req
string — Chave única para garantir que o pagamento não seja processado duas vezes. Use UUID v4 vinculado ao ID do pedido no seu sistema. Max 255 chars. Ver Idempotência.
amount
req
number — Valor do pagamento em reais (não centavos). Exemplo:
50.00. Mínimo: 0.01. Máximo: 999999.99.currency
req
string — Código ISO 4217 da moeda. Atualmente apenas
"BRL" é suportado.paymentMethodRequest
req
object — Define o método de pagamento. Ver objeto abaixo.
paymentMethodRequest.type
req
paymentMethodRequest.token
opt
string | null — Token do cartão gerado no frontend (ex: Stripe.js, MP Checkout). Obrigatório quando
type: "card_token". Omita para pix e boleto.customer
req
object — Dados do pagador.
customer.id
req
string — ID único do cliente no seu sistema.
customer.email
req
string — E-mail do cliente. Usado pelo gateway para antifraude e recibo.
customer.document
opt
string — CPF ou CNPJ do cliente. Obrigatório para PIX e Boleto na maioria dos gateways. Formato:
"123.456.789-01" ou "12.345.678/0001-90".customer.name
opt
string — Nome completo do cliente.
metadata
opt
object — Metadados opcionais de controle.
metadata.gateway
opt
enum — Força o uso de um gateway específico. Se omitido, o SmartRouter escolhe automaticamente. Valores:
STRIPE · MERCADO_PAGO · PAYPAL · ABACATE_PAY · MOCK.metadata.orderId
opt
string — ID do pedido no seu sistema. Retornado na resposta e nos webhooks para correlação.
metadata.description
opt
string — Descrição do pagamento. Aparece no extrato do cliente e no painel do gateway. Max 255 chars.
Exemplo de Request
curl -X POST https://api.orquestraio.com/v1/payments \
-H "x-api-key: Oz_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"amount": 149.90,
"currency": "BRL",
"paymentMethodRequest": {
"type": "pix",
"token": null
},
"customer": {
"id": "usr_8f3k2p",
"email": "[email protected]",
"document": "123.456.789-01",
"name": "João da Silva"
},
"metadata": {
"orderId": "ord_9x2m1a",
"description": "Plano Pro — Junho 2026"
}
}'
const res = await fetch('https://api.orquestraio.com/v1/payments', {
method: 'POST',
headers: {
'x-api-key': process.env.OZ_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
idempotencyKey: crypto.randomUUID(),
amount: 149.90,
currency: 'BRL',
paymentMethodRequest: { type: 'pix', token: null },
customer: {
id: 'usr_8f3k2p',
email: '[email protected]',
document: '123.456.789-01',
name: 'João da Silva',
},
metadata: {
orderId: 'ord_9x2m1a',
description: 'Plano Pro — Junho 2026',
},
}),
});
const payment = await res.json();
import requests, uuid
payment = requests.post(
"https://api.orquestraio.com/v1/payments",
headers={"x-api-key": os.environ["OZ_API_KEY"]},
json={
"idempotencyKey": str(uuid.uuid4()),
"amount": 149.90,
"currency": "BRL",
"paymentMethodRequest": {
"type": "pix",
"token": None
},
"customer": {
"id": "usr_8f3k2p",
"email": "[email protected]",
"document": "123.456.789-01",
"name": "João da Silva",
},
"metadata": {
"orderId": "ord_9x2m1a",
"description": "Plano Pro — Junho 2026",
},
}
).json()
Respostas
{
"paymentId": "550e8400-e29b-41d4-a716-446655440000",
"status": "APPROVED",
"amount": 149.90,
"currency": "BRL",
"details": {
"provider": "MERCADO_PAGO",
"pixCode": "00020126580014BR.GOV.BCB.PIX...",
"pixExpiration": "2026-06-06T16:00:00Z"
},
"metadata": {
"orderId": "ord_9x2m1a"
},
"createdAt": "2026-06-06T15:30:00Z"
}
{
"paymentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"status": "PENDING",
"amount": 149.90,
"currency": "BRL",
"details": {
"provider": "STRIPE",
"boletoBarcode": "34191.09008 61207.727308 71141.790001 1 98760000014990",
"boletoUrl": "https://boleto.stripe.com/...",
"boletoDueDate": "2026-06-09"
},
"createdAt": "2026-06-06T15:30:00Z"
}
{
"paymentId": "3b1f8a9c-4c2d-4e3a-b4c5-1d2e3f4a5b6c",
"status": "DECLINED",
"amount": 149.90,
"currency": "BRL",
"details": {
"provider": "STRIPE",
"declineCode": "insufficient_funds",
"declineMessage": "Saldo insuficiente"
},
"createdAt": "2026-06-06T15:30:00Z"
}
{
"error": "VALIDATION_ERROR",
"message": "Campo obrigatório ausente: customer.email",
"field": "customer.email",
"timestamp": "2026-06-06T15:30:00Z"
}
{
"error": "IDEMPOTENCY_CONFLICT",
"message": "idempotencyKey já foi usado com um payload diferente",
"originalPaymentId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2026-06-06T15:30:00Z"
}
Campos da Resposta
CampoDescrição
paymentId
string (UUID) — Identificador único do pagamento no Orquestraio. Use para rastrear e reconciliar.
status
enum —
APPROVED · DECLINED · PENDING. Ver tabela de status abaixo.details.provider
string — Gateway que processou o pagamento. Reflete a escolha do SmartRouter.
details.pixCode
string? — Payload do QR Code PIX. Presente quando
type: pix e status APPROVED.details.boletoBarcode
string? — Linha digitável do boleto. Presente quando
type: boleto.details.declineCode
string? — Código de recusa normalizado. Presente quando
status: DECLINED.createdAt
string (ISO 8601) — Timestamp de criação em UTC.
GET
/v1/payments/{paymentId}
Consulta um pagamento
Retorna o estado atual de um pagamento pelo seu paymentId. Útil para polling de status em PIX e Boleto enquanto o webhook não chega.
ParâmetroReqDescrição
paymentId
req
string (UUID) · path param — O ID retornado na criação do pagamento.
curl https://api.orquestraio.com/v1/payments/550e8400-e29b-41d4-a716-446655440000 \
-H "x-api-key: Oz_live_xxxx"
Prefira webhooks: Use este endpoint apenas como fallback. Configure webhooks para receber atualizações de status em tempo real sem precisar fazer polling.
Tipos e Enums
paymentMethodRequest.type
pix
boleto
card_token
| Valor | Descrição | Gateways suportados |
|---|---|---|
pix | Pagamento via PIX. Retorna QR Code e payload. Confirmação via webhook. | MERCADO_PAGO, ABACATE_PAY, MOCK |
boleto | Boleto bancário. Retorna linha digitável e URL. Vence em 3 dias úteis. | STRIPE, MERCADO_PAGO, MOCK |
card_token | Cartão tokenizado pelo frontend. Requer token válido do gateway. | STRIPE, MERCADO_PAGO, PAYPAL, MOCK |
metadata.gateway
STRIPE
MERCADO_PAGO
PAYPAL
ABACATE_PAY
MOCK
Quando omitido, o SmartRouter escolhe automaticamente baseado em disponibilidade, taxa de sucesso e regras configuradas.
status
APPROVED
DECLINED
PENDING
| Status | Descrição | Próximo passo |
|---|---|---|
APPROVED | Pagamento confirmado pelo gateway. | Libere o produto/serviço. |
DECLINED | Pagamento recusado (saldo, fraude, etc.). | Informe o cliente. Nunca tente cobrança dupla. |
PENDING | Aguardando confirmação (PIX, Boleto, 3DS). | Aguarde webhook payment.approved. |
Códigos de Erro
Todos os erros retornam JSON com campos error (código) e message (descrição legível). Ver referência completa em Erros & Status.
| HTTP | error | Causa |
|---|---|---|
400 | VALIDATION_ERROR | Campo obrigatório ausente ou com valor inválido. |
401 | UNAUTHORIZED | API key inválida ou ausente. |
403 | FORBIDDEN | API key sem permissão para esta operação. |
409 | IDEMPOTENCY_CONFLICT | Mesma idempotencyKey usada com payload diferente. |
422 | PAYMENT_DECLINED | Pagamento recusado pelo gateway. |
429 | RATE_LIMIT_EXCEEDED | Muitas requisições. Ver Rate Limiting. |
503 | GATEWAY_UNAVAILABLE | Todos os gateways disponíveis estão com Circuit Breaker OPEN. |