Visão Geral da API OceanPay

A API OceanPay permite integrar pagamentos e cobranças via PIX de forma rápida e segura. Nossa solução oferece endpoints simples para gerar códigos PIX, consultar transações e receber notificações em tempo real via webhooks.

Rápido

Integração em minutos

Seguro

Certificado SSL/TLS

Simples

REST API padrão

Base URL https://www.oceanpaybr.com/api/v1

Formato JSON

Versão v1

1

Autenticação

Todas as requisições à API devem ser autenticadas usando sua API Key. Inclua-a no header X-Api-Key de cada requisição.

Headers obrigatórios

X-Api-Key: sua_api_key_aqui
Content-Type: application/json

Importante

Mantenha sua API Key em segredo. Nunca exponha no frontend ou em repositórios públicos. Também suportamos Authorization: Bearer {sua_api_key} como alternativa.

Você encontra sua API Key em: Painel → Configurações → Integração

2

Criar Pedido (Depósito via PIX)

Este endpoint permite gerar um código PIX para recebimento de pagamentos.

POST https://www.oceanpaybr.com/api/v1/pix

Headers

Header		Descrição
`X-Api-Key`	Obrigatório	Sua chave de API
`Content-Type`	Obrigatório	application/json

Corpo da Requisição (JSON)

Parâmetro		Descrição
`amount`	Obrigatório	Valor em centavos (ex: 1000 = R$10,00)
`description`	Opcional	Descrição da cobrança (máx 255 caracteres)
`customer.name`	Obrigatório	Nome completo do cliente
`customer.email`	Obrigatório	E-mail do cliente
`customer.document`	Obrigatório	CPF ou CNPJ do cliente
`customer.phone`	Opcional	Telefone do cliente
`external_ref`	Opcional	Referência externa para controle interno
`metadata`	Opcional	Dados extras em formato string (JSON recomendado)

Exemplo de Requisição

POST https://www.oceanpaybr.com/api/v1/pix
X-Api-Key: SUA_API_KEY
Content-Type: application/json

{
  "amount": 5000,
  "description": "Produto Premium",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678900",
    "phone": "11999999999"
  },
  "external_ref": "pedido-123"
}

Resposta de Sucesso

201

{
  "success": true,
  "transaction": {
    "id": 42,
    "magicpay_id": "txn_abc123...",
    "amount": 5000,
    "status": "waiting_payment",
    "payment_method": "pix",
    "pix": {
      "qrcode": "00020126580014br.gov.bcb.pix...",
      "expiration_date": "2026-03-03"
    },
    "secure_url": "https://...",
    "created_at": "2026-03-02T12:00:00.000Z"
  }
}

Erros Possíveis

401 API key inválida ou ausente

422 Dados inválidos ou campos obrigatórios faltando

500 Erro interno ao processar transação

3

Consultar Transação

Consulte os detalhes de uma transação específica usando seu ID.

GET https://www.oceanpaybr.com/api/v1/transactions/{id}

Parâmetros de URL

Parâmetro		Descrição
`id`	Obrigatório	ID da transação retornado na criação

Exemplo

GET https://www.oceanpaybr.com/api/v1/transactions/42
X-Api-Key: SUA_API_KEY

Resposta de Sucesso

200

{
  "success": true,
  "transaction": {
    "id": 42,
    "magicpay_id": "txn_abc123...",
    "amount": 5000,
    "status": "paid",
    "status_label": "Pago",
    "payment_method": "pix",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "12345678900"
    },
    "pix": {
      "qrcode": "00020126580014br.gov.bcb.pix...",
      "end2end_id": "E1234...",
      "expiration_date": "2026-03-03"
    },
    "fee_amount": 649,
    "net_amount": 4351,
    "paid_at": "2026-03-02T12:05:30.000Z",
    "created_at": "2026-03-02T12:00:00.000Z"
  }
}

4

Status de Transações

Possíveis valores do campo status nas transações.

waiting_payment Aguardando pagamento do PIX

paid Pagamento confirmado

approved Transação aprovada

refused Pagamento recusado

refunded Pagamento estornado

expired PIX expirado sem pagamento

5

Webhooks (Callbacks)

A API envia notificações automáticas quando o status de uma transação é atualizado. Configure sua URL de webhook no painel em Configurações → Conta → Webhook URL.

Payload do Webhook

{
  "event": "transaction.updated",
  "transaction_id": 42,
  "magicpay_id": "txn_abc123...",
  "status": "paid",
  "amount": 5000,
  "payment_method": "pix",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678900"
  },
  "paid_at": "2026-03-02T12:05:30.000Z"
}

Headers do Webhook

Header	Descrição
`Content-Type`	application/json
`X-Gateway-Signature`	HMAC-SHA256 assinado com seu API Secret para validação

Boas Práticas

• Seu endpoint deve retornar status 200 para confirmar o recebimento
• Caso contrário, tentaremos reenviar até 3 vezes com intervalo exponencial
• Valide o X-Gateway-Signature para garantir autenticidade
• Processe webhooks de forma assíncrona para evitar timeouts

6

Rastreamento UTM (Integração Utmify)

Rastreamento Automático

A OceanPay possui integração nativa com a Utmify para rastreamento de conversões. Configure sua API Key da Utmify no painel e os dados serão enviados automaticamente em dois momentos:

Quando o PIX é gerado

waiting_payment

Quando o PIX é pago

paid / approved

Em caso de estorno

refunded

Payload enviado à Utmify

{
  "orderId": "42",
  "platform": "OceanPay",
  "paymentMethod": "pix",
  "status": "paid",
  "createdAt": "2026-03-02 12:00:00",
  "approvedDate": "2026-03-02 12:05:30",
  "customer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "phone": "11999999999",
    "document": "12345678900"
  },
  "products": [{
    "name": "Produto Premium",
    "price": 50.00,
    "quantity": 1
  }],
  "commission": {
    "totalPrice": 50.00
  }
}

Como configurar: Acesse o painel → Configurações → Integração → cole sua API Key da Utmify. A integração é automática e não requer configuração adicional na API.

7

Exemplos de Código

curl -X POST https://www.oceanpaybr.com/api/v1/pix \
  -H "X-Api-Key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "description": "Produto Premium",
    "customer": {
      "name": "João Silva",
      "email": "joao@email.com",
      "document": "12345678900"
    }
  }'

// Laravel HTTP Client
$response = Http::withHeaders([
    'X-Api-Key' => 'SUA_API_KEY',
])->post('https://www.oceanpaybr.com/api/v1/pix', [
    'amount'      => 5000,
    'description' => 'Produto Premium',
    'customer'    => [
        'name'     => 'João Silva',
        'email'    => 'joao@email.com',
        'document' => '12345678900',
    ],
]);

$data = $response->json();

// QR Code PIX copia-e-cola
$qrcode = $data['transaction']['pix']['qrcode'];

// URL segura para pagamento
$secureUrl = $data['transaction']['secure_url'];

const response = await fetch('https://www.oceanpaybr.com/api/v1/pix', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'SUA_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 5000,
    description: 'Produto Premium',
    customer: {
      name: 'João Silva',
      email: 'joao@email.com',
      document: '12345678900',
    },
  }),
});

const data = await response.json();
console.log('PIX QR Code:', data.transaction.pix.qrcode);
console.log('Secure URL:', data.transaction.secure_url);

import requests

response = requests.post(
    'https://www.oceanpaybr.com/api/v1/pix',
    headers={'X-Api-Key': 'SUA_API_KEY'},
    json={
        'amount': 5000,
        'description': 'Produto Premium',
        'customer': {
            'name': 'João Silva',
            'email': 'joao@email.com',
            'document': '12345678900',
        },
    }
)

data = response.json()
print('PIX QR Code:', data['transaction']['pix']['qrcode'])
print('Secure URL:', data['transaction']['secure_url'])

Limites e Boas Práticas

● Todas as requisições devem ser feitas via HTTPS
● Valores monetários são sempre em centavos (R$10,00 = 1000)
● Use external_ref para mapear transações ao seu sistema
● Configure webhooks para receber atualizações em tempo real
● Mantenha sua API Key em segredo — nunca exponha no frontend
● Valide o X-Gateway-Signature nos webhooks para segurança