Pagamentos

Um pagamento representa uma transação na OrcaPay. Este guia mostra o fluxo de criação via Pix e cartão, consulta e gestão do ciclo de vida.

Criando um pagamento Pix

Envie um POST /payments/pix (requer o escopo payments:pix):

curl -X POST https://api.orcapay.com.br/payments/pix \
  -H "X-Api-Key: op_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 159.90,
    "description": "Pedido #1042",
    "externalId": "pedido-1042",
    "customerName": "Maria Silva",
    "customerDocument": "12345678900",
    "customerEmail": "maria@exemplo.com.br",
    "customerPhone": "62999990000",
    "pixExpirationHours": 24
  }'

A resposta 201 traz o QR Code para pagamento:

{
  "id": "9f8a7b6c-5d4e-4a3b-2c1d-0e9f8a7b6c5d",
  "externalId": "pedido-1042",
  "paymentType": "PIX",
  "paymentMethod": "PIX",
  "amount": 159.90,
  "feeAmount": 1.60,
  "feePercent": 1.00,
  "status": "PENDING",
  "statusDescription": "Pendente",
  "pixQrCode": "00020126580014br.gov.bcb.pix...",
  "pixQrCodeImageUrl": "https://...",
  "pixQrCodeBase64": "iVBORw0KGgo...",
  "pixExpiresAt": "2026-07-19T14:30:00Z",
  "createdAt": "2026-07-18T14:30:00Z",
  "expectedSettlementDate": "2026-07-19"
}

O campo externalId é um identificador seu (por exemplo, o número do pedido) que volta em consultas e webhooks para facilitar a correlação — e também protege contra cobranças duplicadas: repetir o POST /payments/pix com o mesmo externalId e o mesmo valor retorna o mesmo pagamento e o mesmo QR Code, em vez de criar outro. Veja externalId e idempotência.

Criando um pagamento com cartão

O fluxo de cartão tem duas etapas: criptografar os dados do cartão no navegador com o SDK JavaScript da OrcaPay e enviar o pagamento pelo seu backend. Os dados abertos do cartão nunca passam pelo seu servidor.

1. Criptografe o cartão com o SDK

Inclua o SDK na sua página de checkout:

<script src="https://sdk.orcapay.com.br/v1/orcapay.min.js"></script>

Inicialize com o identificador do seu estabelecimento e criptografe os dados do cartão:

const orcapay = new OrcaPay({
  establishmentId: 'e1f2a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b',
});

const encryptedCard = await orcapay.encryptCard({
  holder: 'Maria Silva',
  number: '4111 1111 1111 1111',
  expMonth: '12',
  expYear: '2030',
  securityCode: '123',
});

O SDK descobre sozinho o provedor de pagamento e a chave pública configurados para o seu estabelecimento — nenhuma credencial precisa ser exposta no front-end. O retorno é a string encryptedCard, pronta para ser enviada ao seu backend. Espaços no número do cartão são removidos automaticamente; expMonth usa dois dígitos ("01" a "12") e expYear quatro ("2030").

Se preferir não usar o SDK, obtenha a chave pública diretamente em GET /payments/card/public-key/{establishmentId} (endpoint público) e criptografe conforme a documentação do provedor retornado no campo provider.

2. Crie o pagamento

Envie um POST /payments/card (requer o escopo payments:card):

curl -X POST https://api.orcapay.com.br/payments/card \
  -H "X-Api-Key: op_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 159.90,
    "installments": 3,
    "encryptedCard": "encrypted-card-token...",
    "holderName": "Maria Silva",
    "holderDocument": "12345678900",
    "description": "Pedido #1042",
    "externalId": "pedido-1042",
    "customerName": "Maria Silva",
    "customerDocument": "12345678900",
    "customerEmail": "maria@exemplo.com.br",
    "softDescriptor": "MINHALOJA"
  }'

O parcelamento aceita de 1 a 24 parcelas. O softDescriptor é o texto que aparece na fatura do portador.

Envie sempre o externalId: se já existir um pagamento ativo com o mesmo identificador, a requisição retorna 409 CONFLICT sem processar o cartão de novo — é a proteção contra cobrança dupla em retentativas. Veja externalId e idempotência.

Status do pagamento

Status	Significado
PENDING	Aguardando pagamento
PROCESSING	Em processamento
CONFIRMED	Pagamento confirmado
FAILED	Não aprovado
CANCELLED	Cancelado
REVERSED	Estornado integralmente (com estorno parcial o pagamento segue CONFIRMED)
CHARGEBACK	Contestado pelo portador

Para acompanhar as mudanças de status em tempo real, configure webhooks.

Consultando pagamentos

Consulta individual (requer payments:read):

curl https://api.orcapay.com.br/payments/{id} \
  -H "X-Api-Key: op_live_..."

Listagem com filtros e paginação:

curl "https://api.orcapay.com.br/payments?createdFrom=2026-07-01T00:00:00Z&createdTo=2026-07-18T23:59:59Z&paymentMethod=PIX&page=0&size=20&sort=createdAt,desc" \
  -H "X-Api-Key: op_live_..."

A resposta é paginada: os resultados vêm em content, com totalElements, totalPages, number (página atual, iniciando em 0) e size. Também é possível listar por status com GET /payments/status/{status} e consultar o histórico de eventos de um pagamento com GET /payments/{id}/logs.

Cancelamento e estorno

Cancelar um pagamento pendente (requer payments:cancel):

curl -X POST https://api.orcapay.com.br/payments/{id}/cancel \
  -H "X-Api-Key: op_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Pedido cancelado pelo cliente" }'

Estornar um pagamento confirmado, total ou parcialmente (requer payments:refund). Sem corpo, a OrcaPay estorna todo o saldo; com amount (valor exato) ou percentage (percentual do valor total), estorna só uma parte:

curl -X POST https://api.orcapay.com.br/payments/{id}/reverse \
  -H "X-Api-Key: op_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b8e7c1d-6f2a-4c55-9e0b-3f1d2a7c9b14" \
  -d '{ "amount": 40.00, "reason": "Item devolvido pelo cliente" }'

O pagamento continua CONFIRMED enquanto houver saldo e passa para REVERSED quando o valor total é devolvido. Regras de cálculo, validações, prazos e webhooks estão em Estornos.

Conciliação e agenda de recebimento

Para conferência financeira, a API oferece dois relatórios (requerem payments:read):

• GET /payments/conciliation?from=2026-07-01T00:00:00Z&to=2026-07-18T23:59:59Z — totais do período agrupados por status (quantidade, valor bruto, taxas e valor líquido).
• GET /payments/settlement-agenda?from=2026-07-18&to=2026-08-18 — agenda de liquidação: quanto será liquidado por dia.

Ambos aceitam o filtro opcional method (PIX, CREDIT_CARD, DEBIT_CARD).