Oceanbris Docs

Começar

Como funciona

O caminho de uma venda Pix, do checkout ao repasse, e o papel de cada parte.

A Oceanbris processa o Pix das suas vendas. O seu checkout fala só com a API da Oceanbris; a Oceanbris emite o Pix na rede de processamento, confirma o pagamento, registra cada centavo no seu saldo e faz o repasse para a sua conta conforme o contrato.

O fluxo de uma venda

  1. CheckoutO comprador fecha o pedido no seu site ou aplicativo.
  2. API OceanbrisSeu servidor cria a cobrança com POST /v1/pix/charges.
  3. PixA Oceanbris devolve o QR Code e o copia e cola; você mostra ao comprador.
  4. ConfirmaçãoO comprador paga; a Oceanbris confirma o pagamento na rede de processamento.
  5. WebhookA Oceanbris envia charge.paid ao seu endpoint; você libera o pedido.
  6. Saldo e saqueO líquido entra no seu saldo; você pede o saque pelo painel ou pela API e a Oceanbris transfere.

Passo a passo

  1. Seu servidor cria a cobrança. Envie valor, identificador do pedido (order_reference) e os dados do pagador. A chamada sai do seu servidor, nunca do navegador. Veja Criar cobrança.
  2. Você mostra o Pix. A resposta traz pix.qr_code_payload (o copia e cola) e a validade. Gere a imagem do QR Code a partir dele. Veja QR Code e copia e cola.
  3. O comprador paga. Enquanto o QR está válido, a cobrança fica pending. Se a validade acabar sem pagamento, ela vira expired. Veja Expiração.
  4. A Oceanbris confirma e avisa. Com o pagamento confirmado, a cobrança vira paid e a Oceanbris envia o evento charge.paid, com bruto, tarifa e líquido. Veja Webhooks.
  5. Você confirma e libera o pedido. Confira a assinatura do webhook e, por segurança, consulte a cobrança antes de liberar. Veja Consultar cobrança.
  6. O valor entra no saldo. O líquido fica disponível na hora ou, conforme a adquirente que processou a venda, aparece como pendente até a liquidação ser conciliada. Veja Saldo e extrato.
  7. A Oceanbris repassa. Você pede o saque pelo painel ou pela API, a qualquer hora; a Oceanbris aprova, transfere para a sua conta e cada saque aparece no extrato e nos eventos. Veja Saques.

Quem faz o quê

ParteResponsabilidade
Seu checkout (front-end)Mostra o QR Code e o copia e cola; acompanha o estado pelo seu servidor. Nunca chama a API da Oceanbris diretamente.
Seu servidor (back-end)Guarda a chave de API, cria cobranças, recebe webhooks, consulta a cobrança antes de liberar o pedido.
OceanbrisEmite o Pix, confirma o pagamento, calcula tarifa e líquido, mantém o saldo e o extrato, envia os webhooks e faz os repasses.
CompradorPaga pelo aplicativo do banco, lendo o QR Code ou colando o código.

Dinheiro em centavos

Todos os valores da API são inteiros em centavos. Na entrada você pode mandar número ou string (15990 ou "15990"); na saída a Oceanbris devolve sempre string decimal ("15990" = R$ 159,90), para não haver perda de precisão em nenhuma linguagem.

Pago, liquidado e disponível

Uma venda paga não fica disponível no mesmo instante. A Oceanbris separa:

  • Pago (paid): o comprador pagou e a Oceanbris confirmou.
  • Pendente (pending_cents no saldo): o líquido da venda paga ainda não liberado (adquirente que libera só depois de liquidar e conciliar).
  • Disponível (available_cents): valor liberado para saque, na hora ou depois da liquidação conciliada, conforme a adquirente.

O evento balance.available avisa quando um valor fica disponível. Os prazos dependem do seu contrato.