API

Métodos de Pagamento

3 min de leitura

O Orquestraio suporta três tipos de pagamento: pix, boleto e card_token. O tipo é informado no objeto paymentMethodRequest de cada requisição.

PIX

Transferência instantânea 24/7, liquidação em segundos. Disponível exclusivamente em BRL via MercadoPago.

Campo	Valor	Obrigatório
`type`	`"pix"`	Sim
`token`	`null`	Não — sempre nulo para PIX

{ "idempotencyKey": "pix-order-991", "amount": 150.00, "currency": "BRL", "paymentMethodRequest": { "type": "pix", "token": null }, "customer": { "id": "usr_1", "email": "[email protected]", "document": "123.456.789-09" } }

Confirmação assíncrona: PIX tem confirmação em milissegundos, mas o status final (APPROVED) chega via webhook payment.approved. Configure seu endpoint de webhook antes de ir para produção com PIX.

Boleto Bancário

Boleto gerado com vencimento padrão de 3 dias úteis. Disponível em BRL via MercadoPago. O pagamento é confirmado pelo banco emissor — status atualizado via webhook em até 1–3 dias úteis.

Campo	Valor	Obrigatório
`type`	`"boleto"`	Sim
`token`	`null`	Não — sempre nulo para boleto

Atenção: Boleto tem alta taxa de abandono e não tem cancelamento automático — o boleto vencido fica em PENDING até que o gateway confirme o não-pagamento. Implemente lógica de expiração no seu sistema.

Cartão via Token

Pagamento por cartão de crédito ou débito usando um token pré-gerado pelo SDK do gateway. O Orquestraio nunca recebe dados brutos de cartão — somente o token opaco retornado pelo frontend do gateway.

Campo	Valor	Obrigatório
`type`	`"card_token"`	Sim
`token`	Token opaco do gateway (ex: `"tok_4f8a2b1c9d"`)	Sim

Como gerar o token: Use o SDK JavaScript do gateway no frontend (Stripe.js, MercadoPago SDK) para tokenizar os dados do cartão. O token gerado é enviado ao seu backend, que o repassa ao Orquestraio. Dados sensíveis nunca transitam pelo seu servidor.

{ "idempotencyKey": "card-order-772", "amount": 299.90, "currency": "USD", "paymentMethodRequest": { "type": "card_token", "token": "tok_4f8a2b1c9d" // gerado pelo Stripe.js no frontend }, "customer": { "id": "usr_7f3a21b", "email": "[email protected]", "document": "123.456.789-09" } }

Compatibilidade por Gateway

Método	Stripe	MercadoPago	PayPal	MOCK
`pix`	—	✓	—	✓
`boleto`	—	✓	—	✓
`card_token`	✓	✓	Beta	✓

O SmartRouter seleciona automaticamente o gateway compatível com o método informado. Você pode sobrescrever via metadata.gateway. Se o gateway especificado não suportar o método, a API retorna 400 Bad Request.