文档 OrionPay API
Referência pública dos endpoints REST de pagamento, integração e carteira pessoal do OrionPay. Base URL: https://payapi.orion.moe
AI Agents — connect via MCP
An LLM-friendly index lives at /llms.txt and the full inline spec at /llms-full.txt. The OpenAPI 3.1 spec is at payapi.orion.moe/openapi.json.
A Streamable HTTP MCP server with 22 tools is live at payapi.orion.moe/mcp:
claude mcp add orionpay --transport http https://payapi.orion.moe/mcp --header "X-API-Key: $ORIONPAY_API_KEY"Generate an API key at Dashboard > API & Webhooks > MCP / LLM.
身份认证
Todo endpoint público exige uma API Key enviada no header X-API-Key (ou Authorization: Bearer). Existem dois tipos:
API Key Pessoal
productId = null. Controla a carteira do próprio usuário.
Endpoints: /api/v1/pix/personal, /api/v1/personal/*.
API Key de Produto
Vinculada a um produto. Vende e gerencia acesso.
Endpoints: /api/v1/pix/generate, /api/v1/card/*, /integration/*.
X-API-Key: opay_abc123def456...快速开始
// Gerar PIX via API
const response = await fetch('https://payapi.orion.moe/api/v1/pix/generate', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'opay_sua_chave_aqui'
},
body: JSON.stringify({
amount: 199.90,
name: 'João da Silva',
email: '[email protected]'
})
})
const { data } = await response.json()
console.log(data.purchaseId) // ID interno da compra
console.log(data.pixCode) // PIX copia-e-cola
console.log(data.qrCode) // QR Code (mesmo valor)
console.log(data.expiresAt) // ISO 8601可用端点
PIX
/api/v1/pix/generateAPI Key de ProdutoGerar PIX para venda de produto
Gera um QR Code PIX vinculado a um produto. Usa o preço do produto ou o valor informado.
Request body
{
"amount": 199.90,
"description": "Venda de produto",
"name": "João da Silva",
"email": "[email protected]",
"cpf": "12345678901",
"phone": "+5511999999999"
}Response (200)
{
"success": true,
"data": {
"purchaseId": 12345,
"productId": 8,
"productTitle": "Exemplo Produto",
"id": "550e8400-e29b-41d4-a716-446655440000",
"pixCode": "00020126580014br.gov.bcb.pix...",
"qrCode": "00020126580014br.gov.bcb.pix...",
"amount": 199.90,
"description": "Venda de produto: Exemplo Produto",
"expiresAt": "2026-04-24T14:30:00.000Z",
"status": "PENDING",
"coProducers": [
{ "userId": 5, "name": "Co-produtor Name", "percentage": 15.50 }
]
}
}/api/v1/pix/personalAPI Key PessoalGerar PIX de depósito pessoal
Gera um QR Code PIX que credita saldo na carteira BRL do dono da API Key. Exige chave pessoal (productId = null).
Request body
{
"amount": 50.00,
"description": "Depósito pessoal",
"name": "João da Silva",
"email": "[email protected]",
"cpf": "12345678901"
}Response (200)
{
"success": true,
"data": {
"transactionId": 789,
"id": "550e8400-e29b-41d4-a716-446655440000",
"pixCode": "00020126580014br.gov.bcb.pix...",
"qrCode": "00020126580014br.gov.bcb.pix...",
"amount": 50.00,
"description": "Depósito pessoal via PIX",
"expiresAt": "2026-04-24T14:30:00.000Z",
"status": "PENDING"
}
}/api/v1/pix/status/:idQualquer API Key2 req/minConsultar status de pagamento PIX
Aceita purchaseId (numérico), transactionId (numérico) ou eulenDepositId (UUID).
Response (200)
{
"success": true,
"type": "product_purchase",
"id": 12345,
"eulenDepositId": "550e8400-e29b-41d4-a716-446655440000",
"status": "PAID",
"paidAt": "2026-04-24T12:00:00.000Z",
"accessToken": "abcd1234efgh5678ijkl9012mnop3456",
"productId": 8,
"productTitle": "Exemplo Produto",
"amount": 199.90,
"buyerEmail": "[email protected]",
"buyerName": "João Silva",
"createdAt": "2026-04-24T10:00:00.000Z"
}Pagamento com Cartão
/api/v1/card/generateAPI Key de Produto100 req/minProcessar pagamento com cartão de crédito
Captura tokenizada de cartão. Valor mínimo R$ 5,00. Endereço de cobrança é opcional.
Request body
{
"name": "João da Silva",
"email": "[email protected]",
"cpf": "12345678901",
"phone": "+5511999999999",
"amount": 99.99,
"description": "Compra Produto X",
"cardNumber": "4242424242424242",
"cardHolderName": "JOAO DA SILVA",
"cardExpiryMonth": "12",
"cardExpiryYear": "2028",
"cardCvv": "123",
"billingAddressStreet": "Rua Exemplo",
"billingAddressNumber": "100",
"billingAddressCity": "São Paulo",
"billingAddressState": "SP",
"billingAddressZipCode": "01001000"
}Response (200)
{
"success": true,
"purchaseId": 12346,
"paymentId": 456,
"status": "approved",
"transactionId": "gateway-txn-12345",
"authorizationCode": "123456",
"amount": 99.99,
"cardBrand": "VISA",
"cardLastDigits": "4242",
"message": "Pagamento aprovado com sucesso"
}/api/v1/card/status/:paymentIdAPI Key de ProdutoConsultar status de pagamento com cartão
Retorna o estado da autorização e dados da compra vinculada.
Response (200)
{
"id": 456,
"status": "PAID",
"amount": 99.99,
"cardBrand": "VISA",
"cardLastDigits": "4242",
"gatewayTransactionId": "gateway-txn-12345",
"createdAt": "2026-04-24T10:00:00.000Z",
"paidAt": "2026-04-24T10:05:00.000Z",
"errorMessage": null,
"purchase": {
"id": 12346,
"productId": 8,
"accessToken": "abcd1234efgh5678ijkl9012mnop3456"
}
}Integration API (Área de Membros)
/integration/verify-accessAPI Key de Produto2 req/minVerificar acesso de comprador
Query: email ou accessToken (ao menos um obrigatório).
Response (200)
{
"hasAccess": true,
"purchaseId": 12345,
"accessToken": "abcd1234efgh5678ijkl9012mnop3456",
"buyerEmail": "[email protected]",
"buyerName": "João Silva",
"productTitle": "Exemplo Produto",
"purchaseDate": "2026-04-20T10:00:00.000Z",
"expiresAt": "2026-05-20T10:00:00.000Z"
}/integration/grant-accessAPI Key de ProdutoConceder acesso manual
Cria uma compra já paga para o email informado. Útil para cortesias e suporte.
Request body
{
"buyerEmail": "[email protected]",
"buyerName": "Maria Santos",
"price": 199.90,
"expiresAt": "2026-05-24T00:00:00.000Z"
}Response (200)
{
"success": true,
"message": "Acesso concedido com sucesso",
"purchaseId": 12347,
"accessToken": "abcd1234efgh5678ijkl9012mnop3456",
"buyerEmail": "[email protected]",
"buyerName": "Maria Santos",
"expiresAt": "2026-05-24T00:00:00.000Z"
}/integration/buyersAPI Key de Produto30 req/minListar compradores
Query opcional: status (PENDING, PAID, EXPIRED).
Response (200)
{
"total": 2,
"buyers": [
{
"purchaseId": 12345,
"buyerEmail": "[email protected]",
"buyerName": "João Silva",
"price": 199.90,
"paymentStatus": "PAID",
"accessToken": "abcd1234efgh5678ijkl9012mnop3456",
"purchaseDate": "2026-04-20T10:00:00.000Z",
"paidAt": "2026-04-20T10:05:00.000Z",
"expiresAt": "2026-05-20T10:00:00.000Z",
"paymentLink": "Link de Pagamento Exemplo"
}
]
}/integration/buyers/:purchaseIdAPI Key de ProdutoDetalhes de comprador
Retorna dados completos de uma compra pelo ID.
Response (200)
{
"purchaseId": 12345,
"buyerEmail": "[email protected]",
"buyerName": "João Silva",
"price": 199.90,
"paymentStatus": "PAID",
"accessToken": "abcd1234efgh5678ijkl9012mnop3456",
"purchaseDate": "2026-04-20T10:00:00.000Z",
"paidAt": "2026-04-20T10:05:00.000Z",
"expiresAt": "2026-05-20T10:00:00.000Z",
"product": { "id": 8, "title": "Exemplo Produto", "productType": "COURSE" },
"paymentLink": { "id": 1, "title": "Link de Pagamento Exemplo" }
}/integration/contentAPI Key de Produto30 req/minObter conteúdo do produto
Query: accessToken (obrigatório). Valida o token e retorna os conteúdos liberados.
Response (200)
{
"productId": 8,
"buyerEmail": "[email protected]",
"buyerName": "João Silva",
"contents": [
{
"id": 1,
"type": "video",
"title": "Aula 1 - Introdução",
"url": "https://storage.example.com/video1.mp4",
"fileSize": 524288000,
"mimeType": "video/mp4",
"order": 1,
"metadata": "{\"duration\": 3600}"
}
]
}/integration/revoke-access/:purchaseIdAPI Key de ProdutoRevogar acesso
Invalida o accessToken da compra informada.
Response (200)
{
"success": true,
"message": "Acesso revogado com sucesso",
"purchaseId": 12345
}/api/v1/integration/deposit/pixAPI Key de Produto10 req/minGerar depósito PIX com CPF do pagador
Cria QR Code PIX vinculando o CPF do pagador ao produto.
Request body
{
"cpf": "12345678901",
"amount": 199.90,
"buyerEmail": "[email protected]",
"buyerName": "João da Silva"
}Response (200)
{
"purchaseId": 12348,
"productId": 8,
"productTitle": "Exemplo Produto",
"id": "550e8400-e29b-41d4-a716-446655440000",
"pixCode": "00020126580014br.gov.bcb.pix...",
"qrCode": "00020126580014br.gov.bcb.pix...",
"amount": 199.90,
"expiresAt": "2026-04-24T14:30:00.000Z",
"status": "created"
}Personal API (Carteira própria)
/api/v1/personal/balanceAPI Key Pessoal60 req/hConsultar saldos
Retorna saldo por moeda, incluindo bloqueado e pendente.
Response (200)
{
"success": true,
"wallets": [
{
"currency": "BRL",
"balance": 5000.00,
"blockedBalance": 500.00,
"pendingBalance": 0.00,
"availableBalance": 4500.00
},
{
"currency": "L-BTC",
"balance": 0.02,
"blockedBalance": 0.00,
"pendingBalance": 0.00,
"availableBalance": 0.02
}
]
}/api/v1/personal/limitsAPI Key Pessoal30 req/hConsultar limites de saque
Retorna limites diários/mensais e o consumo atual.
Response (200)
{
"success": true,
"limits": {
"dailyWithdrawBRL": 10000.00,
"monthlyWithdrawBRL": 100000.00,
"dailyWithdrawCrypto": 2.00,
"monthlyWithdrawCrypto": 10.00,
"dailyUsed": 2000.00,
"monthlyUsed": 15000.00
}
}/api/v1/personal/transactionsAPI Key Pessoal60 req/hListar transações
Query: limit, offset, type (DEPOSIT, WITHDRAWAL, SWAP).
Response (200)
{
"success": true,
"transactions": [
{
"id": 789,
"type": "DEPOSIT",
"status": "COMPLETED",
"amount": 500.00,
"description": "P-API: Depósito via PIX",
"blockchainTxId": null,
"createdAt": "2026-04-24T10:00:00.000Z"
}
],
"pagination": { "total": 50, "limit": 10, "offset": 0, "hasMore": true }
}/api/v1/personal/withdraw/pixAPI Key Pessoal10 req/hSaque via PIX
amount entre 1 e 100.000. pixKeyType é detectado automaticamente (EMAIL, CPF, CNPJ, PHONE, RANDOM). taxNumber ou euid são obrigatórios (pelo menos um deve ser informado).
Request body
{
"amount": 200.00,
"pixKey": "12345678000123",
"pixKeyType": "CPF",
"description": "Saque via API",
"taxNumber": "12345678901",
"euid": "seu-euid"
}Response (200)
{
"success": true,
"transactionId": 791,
"status": "QUEUED",
"amount": 200.00,
"pixKey": "12345678000123",
"pixKeyType": "CPF",
"description": "Saque via API",
"createdAt": "2026-04-24T14:00:00.000Z"
}/api/v1/personal/withdraw/cryptoAPI Key Pessoal10 req/hSaque em cripto
Suporta L-BTC, BTC-PEGOUT, DePix, USDt, USDC. memo obrigatório para TON.
Request body
{
"amount": 0.01,
"toAddress": "bc1q6y3kz2c8s4n9p1m0l2k3j4h5g6f7e8d9c0b1a",
"assetTicker": "BTC-PEGOUT",
"network": "bitcoin"
}Response (200)
{
"success": true,
"transactionId": 792,
"status": "PENDING",
"amount": 0.01,
"assetTicker": "BTC-PEGOUT",
"toAddress": "bc1q6y3kz2c8s4n9p1m0l2k3j4h5g6f7e8d9c0b1a",
"blockchainTxId": null,
"createdAt": "2026-04-24T14:00:00.000Z"
}/api/v1/personal/withdraw/status/:idAPI Key Pessoal120 req/hStatus de saque
Retorna estado atual e metadados (txHash, pixKey, confirmações, etc).
Response (200)
{
"success": true,
"transaction": {
"id": 791,
"status": "COMPLETED",
"amount": 200.00,
"description": "Saque PIX - Chave CPF",
"blockchainTxId": null,
"metadata": { "pixKey": "12345678000123", "pixKeyType": "CPF", "bankCode": "001" },
"createdAt": "2026-04-24T14:00:00.000Z",
"updatedAt": "2026-04-24T14:05:00.000Z"
}
}/api/v1/personal/swap/quoteAPI Key Pessoal120 req/hCotação de swap
Moedas suportadas: DePix, L-BTC, USDt, EURx. Cotação válida por 5 minutos.
Request body
{
"fromCurrency": "BRL",
"toCurrency": "BTC",
"amount": 1000.00
}Response (200)
{
"success": true,
"fromCurrency": "BRL",
"toCurrency": "BTC",
"fromAmount": 1000.00,
"toAmount": 0.0195,
"rate": 0.0000195,
"fee": 5.00,
"feeCurrency": "BRL",
"expiresAt": "2026-04-24T14:15:00.000Z"
}/api/v1/personal/swap/executeAPI Key Pessoal20 req/hExecutar swap
Debita fromCurrency e credita toCurrency ao preço vigente no momento da execução.
Request body
{
"fromCurrency": "BRL",
"toCurrency": "BTC",
"amount": 1000.00
}Response (200)
{
"success": true,
"transactionId": 793,
"fromCurrency": "BRL",
"toCurrency": "BTC",
"fromAmount": 1000.00,
"toAmount": 0.0195,
"status": "COMPLETED",
"executedAt": "2026-04-24T14:05:00.000Z"
}Payment Links (público)
/payment-links/purchase/:purchaseId/statusPúblico (sem auth)6 req/minStatus de pagamento (sem API Key)
Único endpoint sem auth. Aceita ID numérico (compra) ou UUID (eulenDepositId). Pensado para polling no checkout.
Response (200)
{
"purchaseId": 12345,
"paymentStatus": "PAID",
"paidAt": "2026-04-24T12:00:00.000Z",
"accessToken": "abcd1234efgh5678ijkl9012mnop3456",
"productTitle": "Exemplo Produto",
"price": 199.90
}Rate limits
Ao exceder o limite, o backend responde com HTTP 429. Os limites são por API Key + rota e resetam na janela indicada.
交易状态
Transaction 资源（GET /transactions/:id）上 status 字段的可能值
PIX 已生成，等待支付。余额尚未移动。
Eulen 处理中。可能是 under_review（反欺诈）、delayed（Eulen 在批准前保留 DePix — 尚无资金影响），或在 approved 后处于 delay-depix HOLD（PIX 已确认，blockedBalance 已增加；通过 metadata.holdSource = "delay-depix" + metadata.approvedAt + availableAt 识别该子阶段）。该子阶段的 webhook：deposit.approved_delay。
DePix 已交付到储备。资金记入 balance（如果 isOnHold=true 则记入 pendingBalance）。发出的 webhook：deposit.success 或 deposit.on_hold。
PIX 失败（未支付、过期、被 Eulen 或银行拒绝）。未移动任何余额。
交易被管理员手动取消或因 TTL（PIX 在窗口内未支付）取消。
退款：在保留期间检测到 MED（PIX 退款）或管理员手动退款。根据 metadata.holdSource 从 blockedBalance 或 pendingBalance 扣除。
交易由团队人工审核中，等待批准或拒绝。
Webhooks
当重要事件发生时自动接收通知
安全性
Todo webhook traz assinatura HMAC-SHA256 no header X-Webhook-Signature, calculada sobre o corpo bruto (raw body) com o segredo do webhook. Valide sempre antes de processar.
X-Webhook-Signature: a1b2c3d4e5f6...可用事件
payment.successPagamento confirmado e creditado.
{
"event": "payment.success",
"productId": 8,
"productTitle": "Exemplo Produto",
"webhookName": "notificar_sistema",
"timestamp": "2026-04-24T12:00:00.000Z",
"data": {
"purchaseId": 12345,
"transactionId": "txn_abc123",
"productId": 8,
"buyerEmail": "[email protected]",
"buyerName": "João Silva",
"accessToken": "abcd1234efgh5678ijkl9012mnop3456",
"price": 199.90,
"netAmount": 179.91,
"platformFee": 19.99,
"timestamp": "2026-04-24T12:00:00.000Z"
}
}purchase.createdCompra criada, aguardando pagamento.
{
"event": "purchase.created",
"productId": 8,
"timestamp": "2026-04-24T10:00:00.000Z",
"data": {
"purchaseId": 12345,
"transactionId": "txn_abc123",
"amount": 199.90,
"status": "pending",
"createdAt": "2026-04-24T10:00:00.000Z",
"buyerEmail": "[email protected]",
"buyerName": "João Silva"
}
}access.grantedAcesso liberado ao comprador após confirmação de pagamento.
{
"event": "access.granted",
"productId": 8,
"timestamp": "2026-04-24T12:00:05.000Z",
"data": {
"purchaseId": 12345,
"buyerEmail": "[email protected]",
"accessToken": "abcd1234efgh5678ijkl9012mnop3456",
"expiresAt": "2026-05-24T12:00:05.000Z",
"grantedAt": "2026-04-24T12:00:05.000Z"
}
}payment.refunded_medPagamento reembolsado por MED (chargeback) durante o hold antifraude.
{
"event": "payment.refunded_med",
"productId": 8,
"timestamp": "2026-04-24T15:00:00.000Z",
"data": {
"transactionId": 789,
"amount": 199.90,
"reference": "550e8400-e29b-41d4-a716-446655440000",
"status": "refunded",
"type": "DEPOSIT",
"currency": "BRL",
"reason": "med_during_antifraud_hold",
"medDetectedAt": "2026-04-24T14:50:00.000Z",
"refundedAt": "2026-04-24T15:00:00.000Z"
}
}med.createdMED (chargeback) detectado em depósito Eulen.
{
"event": "med.created",
"timestamp": "2026-04-24T14:50:00.000Z",
"data": {
"qrId": "550e8400-e29b-41d4-a716-446655440000",
"bankTxId": "E00000000202604241450",
"amount": 199.90,
"currency": "BRL",
"medDetectedAt": "2026-04-24T14:50:00.000Z",
"depositStatus": "depix_sent",
"payerTaxNumber": "12345678901",
"transactionId": 789,
"purchaseId": 12345,
"productId": 8,
"productTitle": "Exemplo Produto"
}
}withdrawal.completedSaque transmitido à blockchain ou ao banco.
{
"event": "withdrawal.completed",
"timestamp": "2026-04-24T14:05:00.000Z",
"data": {
"withdrawalId": 792,
"amount": 0.01,
"fee": 0.00001,
"totalDeducted": 0.01001,
"asset": "L-BTC",
"toAddress": "lq1qqw...",
"txHash": "abc123...",
"network": "liquid",
"isSideShift": false,
"completedAt": "2026-04-24T14:05:00.000Z"
}
}withdrawal.settledSaque totalmente confirmado na rede de destino (inclui Peg-Out BTC).
{
"event": "withdrawal.settled",
"timestamp": "2026-04-24T14:30:00.000Z",
"data": {
"withdrawalId": 792,
"amount": 0.01,
"asset": "BTC-PEGOUT",
"toAddress": "bc1q...",
"liquidTxHash": "abc123...",
"settleTxHash": "def456...",
"settleNetwork": "bitcoin",
"completedAt": "2026-04-24T14:30:00.000Z"
}
}withdrawal.failedSaque falhou (saldo insuficiente, endereço inválido, etc). Valores já refundidos ao saldo.
{
"event": "withdrawal.failed",
"timestamp": "2026-04-24T14:05:00.000Z",
"data": {
"withdrawalId": 792,
"amount": 0.01,
"asset": "L-BTC",
"toAddress": "lq1qqw...",
"network": "liquid",
"error": "Insufficient hotwallet balance",
"failedAt": "2026-04-24T14:05:00.000Z"
}
}swap.completedSwap atômico executado com sucesso.
{
"event": "swap.completed",
"timestamp": "2026-04-24T14:05:00.000Z",
"data": {
"txid": "abc123...",
"fromCurrency": "L-BTC",
"toCurrency": "DePix",
"fromAmount": 0.01,
"toAmountGross": 3500.00,
"toAmountNet": 3482.50,
"feePercent": 0.5,
"feeAmount": 17.50,
"completedAt": "2026-04-24T14:05:00.000Z"
}
}swap.failedSwap falhou ou foi reembolsado.
{
"event": "swap.failed",
"timestamp": "2026-04-24T14:05:00.000Z",
"data": {
"transactionId": 793,
"fromCurrency": "L-BTC",
"toCurrency": "DePix",
"fromAmount": 0.01,
"step": "REFUNDED",
"reason": "Manual refund by admin",
"refundedAt": "2026-04-24T14:05:00.000Z"
}
}webhook.testEvento disparado manualmente pela dashboard para testar a URL.
{
"event": "webhook.test",
"timestamp": "2026-04-24T14:05:00.000Z",
"data": {
"message": "Webhook de teste",
"testId": "test_abc123"
}
}Validação (Node.js)
// Validar assinatura de webhook (Node.js)
const crypto = require('crypto')
function validateWebhook(rawBody, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('hex')
return crypto.timingSafeEqual(
Buffer.from(signature, 'hex'),
Buffer.from(expected, 'hex')
)
}
app.post('/webhooks/orionpay', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-webhook-signature']
const rawBody = req.body.toString('utf8')
if (!validateWebhook(rawBody, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).json({ error: 'Invalid signature' })
}
const { event, data } = JSON.parse(rawBody)
switch (event) {
case 'payment.success':
grantAccess(data.buyerEmail, data.accessToken)
break
case 'payment.refunded_med':
revokeAccess(data.transactionId)
break
case 'withdrawal.settled':
markWithdrawalSettled(data.withdrawalId)
break
}
res.status(200).json({ received: true })
})