Documentação da API

Introdução

A API do CorexPay permite que você integre pagamentos PIX e Cartão de Crédito ao seu sistema de forma simples e segura.

Características

API RESTful completa
Autenticação via Token Bearer
Webhooks em tempo real
Respostas em JSON

Obter Credenciais de API

Para usar a API, você precisa gerar uma chave de API no painel do sistema.

Passo 1: Acesse a página de Chaves de API

No painel do sistema, acesse a seção "Chave API" no menu lateral.

Ir para Chaves de API →

Passo 2: Gere uma nova chave

Clique em "Gerar Nova Chave" e dê um nome descritivo (ex: "Site Principal", "App Mobile").

⚠️ Importante: Copie e guarde o token imediatamente, pois ele só será exibido uma vez!

Passo 3: Configure no seu sistema

Adicione o token gerado nas configurações do seu site/aplicação. O token terá o formato:

nxp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Integração PIX (Pagamentos)

Crie pagamentos PIX e receba notificações em tempo real quando o pagamento for confirmado.

Endpoint

POST http://corexpaysolutions.com/api/v1/payments/pix

Parâmetros

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor do pagamento (mínimo: R$ 0,01)
payer_name	string	Sim	Nome completo do pagador
payer_email	string	Sim	Email do pagador
payer_cpf	string	Sim	CPF do pagador (máximo 14 caracteres)
description	string	Não	Descrição do pagamento

Resposta de Sucesso (201)

{
  "success": true,
  "data": {
    "transaction_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100.00,
    "fee": 4.00,
    "amount_net": 96.00,
    "status": "pending",
    "qr_code": "00020126580014BR.GOV.BCB.PIX...",
    "pix_code": "00020126580014BR.GOV.BCB.PIX...",
    "pix_key": "00020126580014BR.GOV.BCB.PIX...",
    "expires_at": "2024-11-26T12:30:00Z",
    "expires_in_seconds": 300
  }
}

Cashout - Saques via PIX

Crie saques via PIX para transferir saldo da conta do usuário para uma chave PIX.

Importante: Para saques automáticos funcionarem, você precisa: 1. Configurar o modo de saque como "Automático" ao criar a credencial de API 2. Adicionar o IP do seu servidor nas configurações da API 3. O usuário precisa estar aprovado (KYC) e com saques desbloqueados

Endpoint

POST http://corexpaysolutions.com/api/v1/cashout/pix

Parâmetros

Campo	Tipo	Obrigatório	Descrição
amount	float	Sim	Valor líquido desejado (mínimo: R$ 10,00). O sistema calcula automaticamente o valor bruto incluindo taxas.
pix_key	string	Sim	Chave PIX de destino (CPF, Email, Telefone ou Chave Aleatória)

Resposta de Sucesso

{
  "success": true,
  "message": "Saque criado e processado automaticamente.",
  "withdrawal": {
    "id": 123,
    "amount": 95.00,
    "amount_gross": 100.00,
    "fee": 5.00,
    "status": "processing",
    "pix_key": "12345678900"
  }
}

Consultar Transações

Liste e filtre as transações da sua conta ou busque uma transação específica.

Listar Transações

GET http://corexpaysolutions.com/api/v1/transactions

Parâmetros (Query String)

Campo	Tipo	Obrigatório	Descrição
status	string	Não	Filtrar por status (pending, completed, failed, etc)
type	string	Não	Filtrar por tipo (pix, credit, withdrawal)
start_date	string (YYYY-MM-DD)	Não	Data inicial do filtro
end_date	string (YYYY-MM-DD)	Não	Data final do filtro
per_page	integer	Não	Itens por página (padrão: 20)

Resposta de Sucesso

{
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "amount_gross": 100.00,
      "amount_net": 96.00,
      "fee": 4.00,
      "type": "pix",
      "status": "completed",
      "gateway_provider": "pluggou",
      "external_id": "TXN_123456789",
      "description": "Depósito via PIX - API",
      "created_at": "2024-01-20T10:30:00Z",
      "updated_at": "2024-01-20T10:35:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100
  }
}

Buscar Transação Específica

GET http://corexpaysolutions.com/api/v1/transactions/{uuid}

Webhooks (Notificações)

Receba notificações automáticas em seu sistema sempre que o status de uma transação mudar.

Configuração

Configure a URL de webhook na sua Chave de API no painel do sistema.

Acesse a seção "Chave API" no menu lateral
Crie uma nova chave de API ou edite uma existente
Preencha o campo "Webhook URL" com a URL do seu servidor
Salve as alterações

⚠️ Importante: A URL deve ser pública e acessível via HTTP/HTTPS para receber as notificações.

Eventos Disparados

Evento	Descrição
transaction.completed	Disparado quando o pagamento é confirmado (pago) e o saldo é creditado.
transaction.failed	Disparado quando o pagamento falha, expira ou é cancelado.
withdrawal.completed	Disparado quando um saque é completado com sucesso.

Exemplo de Payload (JSON)

O sistema enviará uma requisição POST para sua URL com o seguinte corpo:

{
  "event": "transaction.completed",
  "created_at": "2024-01-20T10:30:00Z",
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "TXN_123456789",
    "amount_gross": 150.00,
    "amount_net": 145.50,
    "fee": 4.50,
    "status": "completed",
    "gateway_provider": "pluggou",
    "paid_at": "2024-01-20T10:35:00Z"
  }
}

Campos do Payload

Campo	Tipo	Descrição
event	string	Nome do evento disparado
created_at	string (ISO 8601)	Timestamp de criação do webhook
data.transaction_id	string (UUID)	UUID único da transação no sistema
data.external_id	string	ID da transação no gateway externo
data.amount_gross	float	Valor bruto da transação
data.amount_net	float	Valor líquido (após taxas)
data.fee	float	Valor da taxa cobrada
data.status	string	Status da transação (completed, failed, etc)
data.gateway_provider	string	Nome do gateway (pluggou, bspay, venit, etc)
data.paid_at	string (ISO 8601)	Timestamp de confirmação do pagamento

Resposta Esperada

Seu servidor deve responder com status HTTP 200 OK para confirmar o recebimento. Caso contrário, o sistema tentará reenviar a notificação.

Segurança

Para validar que o webhook realmente veio do sistema, você pode:

Verificar o IP de origem (se disponível)
Validar a estrutura do payload
Confirmar o transaction_id consultando a API

Exemplo em PHP

Exemplo de criação de pagamento PIX usando Guzzle.

<?php

$client = new \GuzzleHttp\Client();

$response = $client->post('http://corexpaysolutions.com/api/v1/payments/pix', [
    'headers' => [
        'Authorization' => 'Bearer SEU_TOKEN',
        'X-Client-ID' => 'SEU_CLIENT_ID',
        'Accept' => 'application/json',
    ],
    'json' => [
        'amount' => 100.00,
        'payer_name' => 'João Silva',
        'payer_email' => 'joao@email.com',
        'payer_cpf' => '12345678900',
        'description' => 'Pagamento de Teste'
    ]
]);

$body = json_decode($response->getBody(), true);
print_r($body);

Exemplo em Python

Exemplo usando a biblioteca requests.

import requests

url = "http://corexpaysolutions.com/api/v1/payments/pix"

payload = {
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste"
}

headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Exemplo em JavaScript

Exemplo usando fetch API.

const url = "http://corexpaysolutions.com/api/v1/payments/pix";

const payload = {
    amount: 100.00,
    payer_name: "João Silva",
    payer_email: "joao@email.com",
    payer_cpf: "12345678900",
    description: "Pagamento de Teste"
};

const headers = {
    "Authorization": "Bearer SEU_TOKEN",
    "X-Client-ID": "SEU_CLIENT_ID",
    "Content-Type": "application/json"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Exemplo cURL

curl -X POST "http://corexpaysolutions.com/api/v1/payments/pix" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "X-Client-ID: SEU_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "payer_name": "João Silva",
    "payer_email": "joao@email.com",
    "payer_cpf": "12345678900",
    "description": "Pagamento de Teste"
  }'

Códigos de Erro

Lista de possíveis códigos de status HTTP retornados pela API.

Código	Significado	Descrição
200	OK	Requisição processada com sucesso.
201	Created	Recurso criado com sucesso (ex: novo pagamento).
400	Bad Request	Dados inválidos enviados na requisição. Verifique os campos.
401	Unauthorized	Token inválido ou não fornecido.
403	Forbidden	Acesso negado ao recurso solicitado.
404	Not Found	Recurso não encontrado (ex: transação inexistente).
422	Unprocessable Entity	Erro de validação (ex: email inválido, saldo insuficiente).
500	Internal Server Error	Erro interno do servidor. Tente novamente mais tarde.

Documentação da API

Navegação

Introdução

Características

Obter Credenciais de API

Passo 1: Acesse a página de Chaves de API

Passo 2: Gere uma nova chave

Passo 3: Configure no seu sistema

Integração PIX (Pagamentos)

Endpoint

Parâmetros

Resposta de Sucesso (201)

Cashout - Saques via PIX

Endpoint

Parâmetros

Resposta de Sucesso

Consultar Transações

Listar Transações

Parâmetros (Query String)

Resposta de Sucesso

Buscar Transação Específica

Webhooks (Notificações)

Configuração

Eventos Disparados

Exemplo de Payload (JSON)

Campos do Payload

Resposta Esperada

Segurança

Exemplo em PHP

Exemplo em Python

Exemplo em JavaScript

Exemplo cURL

Códigos de Erro