API
Processar Pagamento Novo
5 min de leitura
Cria uma transação e roteia automaticamente para o gateway ideal com base na moeda e método de pagamento. O endpoint é protegido pelo filtro ApiKeyAuthFilter e toda lógica de negócio é orquestrada pelo ProcessPaymentUseCase.
POST
/v1/payments
Requer x-api-key
Parâmetros do Payload (PaymentRequestDTO)
Todos os campos anotados com @NotNull ou @NotBlank são obrigatórios. A ausência de qualquer um deles resulta em 400 Bad Request via MethodArgumentNotValidException.
CampoReq.Descricao
idempotencyKey
sim
Anotado com
@NotBlank. Identificador único por transação — use UUID v4 vinculado ao ID do pedido no seu sistema. O backend armazena o hash deste valor para detectar reenvios duplicados.
amount
sim
Anotado com
@NotNull e @DecimalMin("0.01"). Valor em BigDecimal. Mínimo: 0.01. Envie sem arredondamento — o gateway recebe o valor exato.
currency
sim
Anotado com
@NotBlank. Código ISO 4217: BRL, USD, EUR. Este valor é passado ao SmartRouter que seleciona o gateway de menor custo para a moeda informada.
paymentMethodRequest
sim
Anotado com
@NotNull @Valid. Objeto com: type (pix, boleto, card_token) obrigatório; e token — obrigatório apenas quando type é card_token, nulo para Pix e boleto.
customer
sim
Anotado com
@NotNull @Valid. Objeto com: id (ID interno do seu sistema), email anotado com @Email @NotBlank, e document (CPF/CNPJ) anotado com @NotBlank.
metadata.gateway
não
Força um gateway específico:
STRIPE, MERCADO_PAGO, PAYPAL, MOCK. Quando presente, o SmartRouter é bypassed e o gateway indicado é usado diretamente.
Idempotência
O
O
ProcessPaymentUseCase verifica o idempotencyKey antes de criar qualquer transação. Se uma entrada com o mesmo key já existir no banco e estiver com status PROCESSING, a API retorna 409 Conflict imediatamente. Se já estiver APPROVED ou FAILED, o payload da transação original é retornado com 200 OK — garantindo exatamente-uma-vez semântica (at-most-once delivery) sem cobranças duplicadas.
SmartRouter
Quando
Quando
metadata.gateway não é fornecido, o SmartRouter seleciona o gateway com base na currency e no type do método de pagamento. Exemplo: BRL + pix → MERCADO_PAGO; USD + card_token → STRIPE. A seleção considera também a saúde dos gateways (circuit breaker) — se o gateway primário estiver degradado, o roteamento é feito para o secundário automaticamente.
Exemplo de Requisição
curl -X POST https://api.orquestraio.com/v1/payments \
-H "x-api-key: Oz_live_sk_abc123def456" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"amount": 197.90,
"currency": "BRL",
"paymentMethodRequest": {
"type": "pix",
"token": null
},
"customer": {
"id": "usr_7f3a21b",
"email": "[email protected]",
"document": "123.456.789-09"
}
}'
const res = await fetch('https://api.orquestraio.com/v1/payments', {
method: 'POST',
headers: {
'x-api-key': process.env.ORQUESTRAIO_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
idempotencyKey: crypto.randomUUID(), // UUID vinculado ao seu order_id
amount: 197.90,
currency: 'BRL',
paymentMethodRequest: {
type: 'card_token',
token: 'tok_4f8a2b1c9d' // obrigatório para card_token
},
customer: {
id: 'usr_7f3a21b',
email: '[email protected]',
document: '123.456.789-09'
}
})
});
if (!res.ok) {
const err = await res.json();
console.error(`Erro ${err.status}: ${err.message}`);
}
const payment = await res.json();
import requests, uuid, os
res = requests.post(
"https://api.orquestraio.com/v1/payments",
headers={
"x-api-key": os.environ["ORQUESTRAIO_API_KEY"],
"Content-Type": "application/json"
},
json={
"idempotencyKey": str(uuid.uuid4()),
"amount": 197.90,
"currency": "BRL",
"paymentMethodRequest": {
"type": "pix",
"token": None
},
"customer": {
"id": "usr_7f3a21b",
"email": "[email protected]",
"document": "123.456.789-09"
}
},
timeout=30
)
res.raise_for_status()
payment = res.json()
// Pagamento por cartão com gateway forçado
{
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"amount": 349.99,
"currency": "USD",
"paymentMethodRequest": {
"type": "card_token",
"token": "tok_4f8a2b1c9d"
},
"customer": {
"id": "usr_7f3a21b",
"email": "[email protected]",
"document": "123.456.789-09"
},
"metadata": {
"gateway": "STRIPE" // bypass do SmartRouter
}
}
Resposta de Sucesso
{
"paymentId": "550e8400-e29b-41d4-a716-446655440000",
"status": "APPROVED",
"amount": 197.90,
"currency": "BRL",
"details": {
"provider": "MERCADO_PAGO",
"transactionId": "00020126580014br.gov.bcb.pix0136a867e..."
},
"createdAt": "2026-02-21T15:30:00Z"
}