Documentação API

Introducao

Bem-vindo a documentacao da API do SellxPay. Nossa API RESTful permite que voce integre pagamentos via PIX, Boleto e Cartao de Credito de forma rapida e segura.

URL Base

https://app.sellxpay.com.br/api/v1

Informacoes Gerais

Todas as respostas sao retornadas em formato JSON.
Todas as requisicoes devem incluir o header Content-Type: application/json.
Rate limiting: 60 requisicoes por minuto por token de acesso. Ao exceder o limite, a API retorna 429 Too Many Requests com o header Retry-After indicando os segundos para aguardar.
Valores monetarios sao representados como number em Reais (R$) com ate 2 casas decimais. Exemplo: 100.00 = R$ 100,00. Nao envie valores em centavos.
Datas seguem o formato ISO 8601 em UTC: YYYY-MM-DDTHH:mm:ss.sssZ.

Status das Transacoes

Tabela de referencia com todos os status possiveis de uma transacao:

Status	Descricao
`pending`	Transacao criada, aguardando pagamento
`paid`	Pagamento confirmado com sucesso
`cancelled`	Transacao cancelada (pelo usuario ou sistema)
`expired`	Tempo limite atingido sem pagamento
`reversed`	Pagamento estornado/reembolsado
`refused`	Transacao recusada (cartao negado, antifraude, etc.)
`chargedback`	Chargeback recebido (contestacao do titular do cartao)
`in_analysis`	Em analise antifraude

Formatos de Chave PIX

Ao enviar uma chave PIX, informe o pix_key_type correspondente:

Tipo	Formato	Exemplo
`cpf`	11 digitos, apenas numeros (sem pontos ou tracos)	`12345678900`
`cnpj`	14 digitos, apenas numeros (sem pontos, barras ou tracos)	`12345678000199`
`email`	Email valido	`joao@email.com`
`phone`	Telefone com DDI +55, DDD e numero (apenas numeros com +)	`+5511999998888`
`random`	Chave aleatoria (UUID gerado pelo banco)	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`

Autenticacao

A API utiliza autenticacao OAuth2 com credenciais de cliente. Voce precisa obter um token de acesso antes de realizar qualquer operacao.

Suas credenciais (client_id e client_secret) estao disponiveis no painel, em API Keys.

POST /api/v1/oauth/token

Header de Autorizacao

Envie suas credenciais codificadas em Base64 no header Authorization:

Authorization: Basic {base64(client_id:client_secret)}

Resposta 200 OK

{
  "access_token": "1|abc123def456...",
  "token_type": "Bearer",
  "expires_in": 1800
}

O token expira em 30 minutos. Apos expirar, a API retorna 401 Unauthorized. Solicite um novo token repetindo o passo de autenticacao. Nao existe refresh token — sempre gere um novo.

Exemplos de Codigo

curl -X POST https://app.sellxpay.com.br/api/v1/oauth/token \
  -H "Authorization: Basic $(echo -n 'CLIENT_ID:CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/json"

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/oauth/token',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Basic ' . base64_encode('CLIENT_ID:CLIENT_SECRET'),
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
$accessToken = $response['access_token'];

const axios = require('axios');
const credentials = Buffer.from('CLIENT_ID:CLIENT_SECRET').toString('base64');

const { data } = await axios.post('https://app.sellxpay.com.br/api/v1/oauth/token', {}, {
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json',
  }
});
const accessToken = data.access_token;

import requests
import base64

credentials = base64.b64encode(b'CLIENT_ID:CLIENT_SECRET').decode()
response = requests.post(
    'https://app.sellxpay.com.br/api/v1/oauth/token',
    headers={
        'Authorization': f'Basic {credentials}',
        'Content-Type': 'application/json',
    }
)
access_token = response.json()['access_token']

PIX - Gerar QR Code (Deposito)

Gera um QR Code PIX para receber um pagamento (cash-in). O QR Code tem validade de 30 minutos.

POST /api/v1/pix/qrcode

Autorizacao

Authorization: Bearer {access_token}

Parametros do Body

Campo	Tipo	Obrigatorio	Descricao
`amount`	number	Sim	Valor do deposito (min: 10.00, max: 50000.00)
`external_id`	string	Nao	ID externo para referencia
`postback_url`	string	Nao	URL para receber notificacao de pagamento
`payer_name`	string	Nao	Nome do pagador
`payer_document`	string	Nao	CPF/CNPJ do pagador
`payer_email`	string	Nao	Email do pagador
`description`	string	Nao	Descricao da cobranca

Resposta 201 Created

{
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "order-123",
  "amount": 100.00,
  "tax": 2.99,
  "net_amount": 97.01,
  "status": "pending",
  "qr_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_base64": "data:image/png;base64,iVBOR...",
  "copy_paste": "00020126580014br.gov.bcb.pix...",
  "expires_at": "2025-01-01T00:30:00.000Z"
}

Exemplos de Codigo

curl -X POST https://app.sellxpay.com.br/api/v1/pix/qrcode \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "external_id": "order-123",
    "postback_url": "https://seusite.com/webhook",
    "payer_name": "Joao Silva",
    "payer_document": "12345678900"
  }'

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/pix/qrcode',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 100.00,
        'external_id' => 'order-123',
        'postback_url' => 'https://seusite.com/webhook',
        'payer_name' => 'Joao Silva',
        'payer_document' => '12345678900',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$qrCode = $response['qr_code_base64'];
$transactionId = $response['transaction_id'];

const { data } = await axios.post('https://app.sellxpay.com.br/api/v1/pix/qrcode', {
  amount: 100.00,
  external_id: 'order-123',
  postback_url: 'https://seusite.com/webhook',
  payer_name: 'Joao Silva',
  payer_document: '12345678900',
}, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  }
});

const qrCode = data.qr_code_base64;
const transactionId = data.transaction_id;

response = requests.post(
    'https://app.sellxpay.com.br/api/v1/pix/qrcode',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 100.00,
        'external_id': 'order-123',
        'postback_url': 'https://seusite.com/webhook',
        'payer_name': 'Joao Silva',
        'payer_document': '12345678900',
    }
)
data = response.json()
qr_code = data['qr_code_base64']
transaction_id = data['transaction_id']

PIX - Enviar Pagamento (Saque)

Envia um pagamento PIX para uma chave (cash-out). O valor sera debitado do seu saldo.

POST /api/v1/pix/payment

Autorizacao

Authorization: Bearer {access_token}

Parametros do Body

Campo	Tipo	Obrigatorio	Descricao
`amount`	number	Sim	Valor do pagamento
`pix_key`	string	Sim	Chave PIX do destinatario
`pix_key_type`	string	Sim	Tipo: `cpf`, `cnpj`, `email`, `phone`, `random`
`external_id`	string	Nao	ID externo para referencia
`description`	string	Nao	Descricao do pagamento

Anti-fraude: Pagamentos acima do limite configurado podem bloquear temporariamente a funcionalidade de saque da sua conta, exigindo liberacao pelo administrador.

Resposta 201 Created

{
  "transaction_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "external_id": "withdraw-456",
  "amount": 500.00,
  "tax": 4.99,
  "net_amount": 495.01,
  "status": "pending",
  "pix_key": "12345678900",
  "pix_key_type": "cpf"
}

Exemplos de Codigo

curl -X POST https://app.sellxpay.com.br/api/v1/pix/payment \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "pix_key": "12345678900",
    "pix_key_type": "cpf",
    "external_id": "withdraw-456",
    "description": "Pagamento fornecedor"
  }'

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/pix/payment',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 500.00,
        'pix_key' => '12345678900',
        'pix_key_type' => 'cpf',
        'external_id' => 'withdraw-456',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const { data } = await axios.post('https://app.sellxpay.com.br/api/v1/pix/payment', {
  amount: 500.00,
  pix_key: '12345678900',
  pix_key_type: 'cpf',
  external_id: 'withdraw-456',
}, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  }
});

response = requests.post(
    'https://app.sellxpay.com.br/api/v1/pix/payment',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 500.00,
        'pix_key': '12345678900',
        'pix_key_type': 'cpf',
        'external_id': 'withdraw-456',
    }
)
data = response.json()

Boleto - Gerar Boleto

Gera um boleto bancario para cobranca.

POST /api/v1/boleto/create

Autorizacao

Authorization: Bearer {access_token}

Parametros do Body

Campo	Tipo	Obrigatorio	Descricao
`amount`	number	Sim	Valor do boleto
`payer_name`	string	Sim	Nome completo do pagador
`payer_document`	string	Sim	CPF/CNPJ do pagador
`payer_email`	string	Nao	Email do pagador
`payer_address`	object	Nao	Endereco do pagador
`street`	string	Nao	Logradouro
`number`	string	Nao	Numero
`city`	string	Nao	Cidade
`state`	string	Nao	UF (2 caracteres)
`zip_code`	string	Nao	CEP
`due_date`	string	Nao	Data de vencimento (YYYY-MM-DD). Padrao: 3 dias
`description`	string	Nao	Descricao
`external_id`	string	Nao	ID externo
`postback_url`	string	Nao	URL de notificacao

Resposta 201 Created

{
  "transaction_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "external_id": "invoice-789",
  "amount": 250.00,
  "tax": 3.99,
  "status": "pending",
  "boleto_url": "https://boleto.exemplo.com/view/abc123",
  "boleto_barcode": "23793.38128 60000.000003 00000.000400 1 84340000025000",
  "digitable_line": "23793381286000000000300000004001843400000250 00",
  "expires_at": "2025-01-04T23:59:59.000Z"
}

Exemplos de Codigo

curl -X POST https://app.sellxpay.com.br/api/v1/boleto/create \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "payer_name": "Joao Silva",
    "payer_document": "12345678900",
    "payer_email": "joao@email.com",
    "due_date": "2025-01-10",
    "external_id": "invoice-789",
    "postback_url": "https://seusite.com/webhook"
  }'

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/boleto/create',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 250.00,
        'payer_name' => 'Joao Silva',
        'payer_document' => '12345678900',
        'payer_email' => 'joao@email.com',
        'due_date' => '2025-01-10',
        'external_id' => 'invoice-789',
        'postback_url' => 'https://seusite.com/webhook',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const { data } = await axios.post('https://app.sellxpay.com.br/api/v1/boleto/create', {
  amount: 250.00,
  payer_name: 'Joao Silva',
  payer_document: '12345678900',
  payer_email: 'joao@email.com',
  due_date: '2025-01-10',
  external_id: 'invoice-789',
  postback_url: 'https://seusite.com/webhook',
}, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  }
});

response = requests.post(
    'https://app.sellxpay.com.br/api/v1/boleto/create',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 250.00,
        'payer_name': 'Joao Silva',
        'payer_document': '12345678900',
        'payer_email': 'joao@email.com',
        'due_date': '2025-01-10',
        'external_id': 'invoice-789',
        'postback_url': 'https://seusite.com/webhook',
    }
)
data = response.json()

Cartao - Cobrar Cartao

Realiza uma cobranca no cartao de credito do cliente.

POST /api/v1/card/charge

Autorizacao

Authorization: Bearer {access_token}

PCI Compliance: Recomendamos utilizar card_token gerado pelo nosso SDK ao inves de enviar os dados do cartao diretamente.

Parametros do Body

Campo	Tipo	Obrigatorio	Descricao
`amount`	number	Sim	Valor da cobranca
`card_token`	string	Condicional	Token do cartao (preferencial)
`card_number`	string	Condicional	Numero do cartao
`card_holder`	string	Condicional	Nome no cartao
`card_expiry`	string	Condicional	Validade (MM/YY)
`card_cvv`	string	Condicional	CVV
`installments`	integer	Nao	Parcelas (1-12, padrao: 1)
`capture`	boolean	Nao	Captura automatica (padrao: true)
`payer_name`	string	Sim	Nome do comprador
`payer_document`	string	Sim	CPF/CNPJ
`payer_email`	string	Nao	Email
`external_id`	string	Nao	ID externo
`postback_url`	string	Nao	URL de notificacao

Resposta 201 Created

{
  "transaction_id": "d4e5f6a7-b8c9-0123-defg-234567890123",
  "external_id": "order-999",
  "amount": 199.90,
  "tax": 5.99,
  "installments": 3,
  "status": "paid",
  "card_brand": "visa",
  "card_last_digits": "4242"
}

Exemplos de Codigo

curl -X POST https://app.sellxpay.com.br/api/v1/card/charge \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 199.90,
    "card_token": "tok_abc123def456",
    "installments": 3,
    "payer_name": "Joao Silva",
    "payer_document": "12345678900",
    "external_id": "order-999",
    "postback_url": "https://seusite.com/webhook"
  }'

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/card/charge',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 199.90,
        'card_token' => 'tok_abc123def456',
        'installments' => 3,
        'payer_name' => 'Joao Silva',
        'payer_document' => '12345678900',
        'external_id' => 'order-999',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const { data } = await axios.post('https://app.sellxpay.com.br/api/v1/card/charge', {
  amount: 199.90,
  card_token: 'tok_abc123def456',
  installments: 3,
  payer_name: 'Joao Silva',
  payer_document: '12345678900',
  external_id: 'order-999',
}, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  }
});

response = requests.post(
    'https://app.sellxpay.com.br/api/v1/card/charge',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': 199.90,
        'card_token': 'tok_abc123def456',
        'installments': 3,
        'payer_name': 'Joao Silva',
        'payer_document': '12345678900',
        'external_id': 'order-999',
    }
)
data = response.json()

Saldo - Consultar Saldo

Retorna o saldo atual da sua conta.

GET /api/v1/balance

Autorizacao

Authorization: Bearer {access_token}

Resposta 200 OK

{
  "balance": 15000.50,
  "balance_blocked": 500.00,
  "available_balance": 14500.50
}

Exemplos de Codigo

curl -X GET https://app.sellxpay.com.br/api/v1/balance \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/balance',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$saldo = $response['available_balance'];

const { data } = await axios.get('https://app.sellxpay.com.br/api/v1/balance', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  }
});

const saldo = data.available_balance;

response = requests.get(
    'https://app.sellxpay.com.br/api/v1/balance',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    }
)
saldo = response.json()['available_balance']

Transacoes - Listar Transacoes

Retorna a lista paginada de transacoes do merchant autenticado, com suporte a filtros.

GET /api/v1/transactions

Autorizacao

Authorization: Bearer {access_token}

Parametros de Query String

Campo	Tipo	Obrigatorio	Descricao
`status`	string	Nao	Filtrar por status: `pending`, `paid`, `cancelled`, `reversed`, `refused`, `chargedback`, `in_analysis`
`type`	string	Nao	Filtrar por tipo: `deposit`, `withdraw`, `internal_transfer`
`method`	string	Nao	Filtrar por metodo: `pix`, `boleto`, `card`
`start_date`	date	Nao	Data inicial (YYYY-MM-DD)
`end_date`	date	Nao	Data final (YYYY-MM-DD)
`external_id`	string	Nao	Filtrar por ID externo
`payer_document`	string	Nao	Filtrar por CPF/CNPJ do pagador
`page`	integer	Nao	Pagina (padrao: 1)
`per_page`	integer	Nao	Itens por pagina (padrao: 20, max: 100)

Resposta 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "external_id": "order-123",
      "type": "deposit",
      "method": "pix",
      "status": "paid",
      "amount": 100.00,
      "tax": 2.99,
      "net_amount": 97.01,
      "payer_name": "Joao Silva",
      "payer_document": "12345678900",
      "created_at": "2025-01-01T00:00:00.000Z",
      "confirmed_at": "2025-01-01T00:15:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 150,
    "last_page": 8
  }
}

Paginacao: O objeto meta contem informacoes de paginacao. Use page na query string para navegar entre paginas (ex: ?page=2&per_page=50). O campo last_page indica o total de paginas disponiveis.

Exemplos de Codigo

curl -X GET "https://app.sellxpay.com.br/api/v1/transactions?status=paid&type=deposit&per_page=50" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/transactions?status=paid&type=deposit&per_page=50',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$transactions = $response['data'];
$total = $response['meta']['total'];

const { data } = await axios.get('https://app.sellxpay.com.br/api/v1/transactions', {
  params: { status: 'paid', type: 'deposit', per_page: 50 },
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  }
});

const transactions = data.data;
const total = data.meta.total;

response = requests.get(
    'https://app.sellxpay.com.br/api/v1/transactions',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    },
    params={
        'status': 'paid',
        'type': 'deposit',
        'per_page': 50,
    }
)
data = response.json()
transactions = data['data']
total = data['meta']['total']

Transacao - Consultar Status

Consulta o status e detalhes de uma transacao especifica pelo seu ID.

GET /api/v1/transaction/{id}

Autorizacao

Authorization: Bearer {access_token}

Parametros de URL

Campo	Tipo	Obrigatorio	Descricao
`id`	string	Sim	ID da transacao (UUID retornado na criacao)

Resposta 200 OK

{
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "order-123",
  "type": "deposit",
  "method": "pix",
  "status": "paid",
  "amount": 100.00,
  "tax": 2.99,
  "net_amount": 97.01,
  "created_at": "2025-01-01T00:00:00.000Z",
  "confirmed_at": "2025-01-01T00:15:00.000Z",
  "expires_at": null
}

Exemplos de Codigo

curl -X GET https://app.sellxpay.com.br/api/v1/transaction/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

$transactionId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/transaction/' . $transactionId,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$status = $response['status'];

const transactionId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const { data } = await axios.get(`https://app.sellxpay.com.br/api/v1/transaction/${transactionId}`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  }
});

const status = data.status;

transaction_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
response = requests.get(
    f'https://app.sellxpay.com.br/api/v1/transaction/{transaction_id}',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    }
)
data = response.json()
status = data['status']

Transacao - Reembolsar

Reembolsa uma transacao de deposito ja paga. O valor liquido sera debitado do saldo do merchant.

POST /api/v1/transaction/{id}/refund

Autorizacao

Authorization: Bearer {access_token}

Parametros de URL

Campo	Tipo	Obrigatorio	Descricao
`id`	string	Sim	ID da transacao a ser reembolsada

Atencao: Apenas transacoes com status paid e tipo deposit podem ser reembolsadas. O valor liquido (net_amount) sera debitado do seu saldo.

Resposta 200 OK

{
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "original_transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": 100.00,
  "status": "reversed",
  "refunded_at": "2025-01-02T10:30:00.000Z"
}

Exemplos de Codigo

curl -X POST https://app.sellxpay.com.br/api/v1/transaction/a1b2c3d4-e5f6-7890-abcd-ef1234567890/refund \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

$transactionId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => 'https://app.sellxpay.com.br/api/v1/transaction/' . $transactionId . '/refund',
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $accessToken,
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const transactionId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const { data } = await axios.post(`https://app.sellxpay.com.br/api/v1/transaction/${transactionId}/refund`, {}, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  }
});

transaction_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
response = requests.post(
    f'https://app.sellxpay.com.br/api/v1/transaction/{transaction_id}/refund',
    headers={
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json',
    }
)
data = response.json()

Webhooks - Configurar via API

Gerencie as URLs de webhook (postback) da sua conta diretamente pela API.

Configurar URL de Webhook

POST /api/v1/webhooks

Body

Campo	Tipo	Obrigatorio	Descricao
`url`	string	Sim	URL HTTPS para receber notificacoes
`is_active`	boolean	Nao	Ativar/desativar (padrao: true)

Resposta 201 Created

{
  "id": 1,
  "url": "https://seusite.com/webhook",
  "is_active": true,
  "message": "Webhook configurado com sucesso"
}

Listar Webhooks

GET /api/v1/webhooks

Resposta 200 OK

{
  "data": [
    {
      "id": 1,
      "url": "https://seusite.com/webhook",
      "is_active": true,
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Remover Webhook

DELETE /api/v1/webhooks/{id}

Resposta 200 OK

{
  "message": "Webhook removido com sucesso"
}

Webhooks

Webhooks sao notificacoes HTTP enviadas automaticamente pelo gateway quando o status de uma transacao muda. Configure a URL de webhook no painel administrativo ou envie o campo postback_url em cada requisicao.

Como funciona

Quando uma transacao muda de status, enviamos um POST para a sua URL configurada.
Esperamos uma resposta HTTP 200. Caso contrario, faremos novas tentativas.
Politica de retentativa: 6 tentativas — imediata, 30s, 1min, 5min, 15min e 1h.

Eventos Disponiveis

Evento	Descricao
`transaction.paid`	Transacao confirmada/paga
`transaction.cancelled`	Transacao cancelada
`transaction.reversed`	Transacao estornada/reembolsada
`transaction.refused`	Transacao recusada
`transaction.chargedback`	Chargeback recebido
`transaction.in_analysis`	Transacao em analise antifraude
`transaction.expired`	Transacao expirada

Formato do Payload

O payload enviado via webhook segue o formato abaixo:

{
  "event": "transaction.paid",
  "transaction": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "external_id": "order-123",
    "type": "deposit",
    "method": "pix",
    "status": "paid",
    "amount": 100.00,
    "tax": 2.99,
    "net_amount": 97.01,
    "payer_name": "Joao Silva",
    "payer_document": "12345678900",
    "end2end": "E12345678202501011234abc",
    "confirmed_at": "2025-01-01T00:15:00.000Z"
  }
}

Exemplo: Recebendo um Webhook (PHP)

// webhook.php
$payload = json_decode(file_get_contents('php://input'), true);
$event = $payload['event'] ?? null;
$transaction = $payload['transaction'] ?? null;

if ($event === 'transaction.paid' && $transaction) {
    // Liberar produto/servico para o cliente
    // $transaction['external_id'] e o seu ID de referencia
    // $transaction['amount'] e o valor pago
    // $transaction['net_amount'] e o valor liquido creditado

    // Atualize seu banco de dados aqui...
    atualizarPedido($transaction['external_id'], 'pago');
}

// IMPORTANTE: Sempre retorne HTTP 200 para confirmar recebimento
http_response_code(200);
echo json_encode(['received' => true]);

Postbacks

Postbacks sao as notificacoes que o gateway envia para a URL informada em postback_url na requisicao de criacao da transacao.

A diferenca entre webhook e postback:

Webhook: Notificacao da adquirente para o gateway (interno).
Postback: Notificacao do gateway para o seu sistema (externo).

O formato do payload do postback e identico ao dos webhooks descrito na secao anterior. A mesma politica de retentativas se aplica.

Se voce nao informar postback_url na requisicao, o postback sera enviado para a URL configurada no painel, caso exista.

Codigos de Erro

A API utiliza codigos HTTP padrao para indicar sucesso ou falha nas requisicoes.

HTTP Code	Erro	Descricao
400	`bad_request`	Requisicao mal formatada
401	`unauthorized`	Token invalido ou expirado
403	`forbidden`	Sem permissao (conta inativa, cash-in/out desabilitado)
404	`not_found`	Recurso nao encontrado
422	`validation_error`	Dados invalidos (veja campo `errors`)
422	`insufficient_balance`	Saldo insuficiente
429	`too_many_requests`	Rate limit excedido (aguarde e tente novamente)
500	`server_error`	Erro interno do servidor

Formato da Resposta de Erro

{
  "error": "validation_error",
  "message": "Os dados fornecidos sao invalidos.",
  "errors": {
    "amount": ["O campo valor e obrigatorio."],
    "pix_key": ["O campo chave PIX e obrigatorio."]
  }
}

Exemplos Completos

Exemplo de fluxo completo: autenticar, gerar QR Code PIX, receber webhook e consultar saldo.

Integracao Completa em PHP

<?php
/**
 * Exemplo completo de integracao com o SellxPay
 * Fluxo: Autenticar -> Gerar QR Code PIX -> Consultar Saldo
 */

$baseUrl = 'https://app.sellxpay.com.br/api/v1';
$clientId = 'SEU_CLIENT_ID';
$clientSecret = 'SEU_CLIENT_SECRET';

// ============================================
// PASSO 1: Autenticacao - Obter Token
// ============================================
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "$baseUrl/oauth/token",
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Basic ' . base64_encode("$clientId:$clientSecret"),
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$authResponse = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!isset($authResponse['access_token'])) {
    die('Erro na autenticacao: ' . json_encode($authResponse));
}

$accessToken = $authResponse['access_token'];
echo "Token obtido com sucesso!\n";

// ============================================
// PASSO 2: Gerar QR Code PIX
// ============================================
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "$baseUrl/pix/qrcode",
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $accessToken",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 100.00,
        'external_id' => 'pedido-' . uniqid(),
        'postback_url' => 'https://seusite.com/webhook',
        'payer_name' => 'Joao Silva',
        'payer_document' => '12345678900',
        'description' => 'Pagamento do pedido #123',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$pixResponse = json_decode(curl_exec($ch), true);
curl_close($ch);

if (isset($pixResponse['transaction_id'])) {
    echo "QR Code gerado!\n";
    echo "Transaction ID: " . $pixResponse['transaction_id'] . "\n";
    echo "Valor: R$ " . number_format($pixResponse['amount'], 2, ',', '.') . "\n";
    echo "Taxa: R$ " . number_format($pixResponse['tax'], 2, ',', '.') . "\n";
    echo "Copia e Cola: " . $pixResponse['copy_paste'] . "\n";
} else {
    echo "Erro ao gerar QR Code: " . json_encode($pixResponse) . "\n";
}

// ============================================
// PASSO 3: Consultar Saldo
// ============================================
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "$baseUrl/balance",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $accessToken",
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$balanceResponse = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Saldo disponivel: R$ " . number_format($balanceResponse['available_balance'], 2, ',', '.') . "\n";

// ============================================
// WEBHOOK (arquivo separado: webhook.php)
// ============================================
// Quando o pagamento for confirmado, o gateway
// enviara um POST para sua postback_url:
//
// $payload = json_decode(file_get_contents('php://input'), true);
// if ($payload['event'] === 'transaction.paid') {
//     $externalId = $payload['transaction']['external_id'];
//     // Liberar pedido...
// }
// http_response_code(200);
// echo json_encode(['received' => true]);

Integracao Completa em Node.js

const axios = require('axios');

const BASE_URL = 'https://app.sellxpay.com.br/api/v1';
const CLIENT_ID = 'SEU_CLIENT_ID';
const CLIENT_SECRET = 'SEU_CLIENT_SECRET';

async function main() {
  // Passo 1: Autenticacao
  const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');
  const { data: auth } = await axios.post(`${BASE_URL}/oauth/token`, {}, {
    headers: { 'Authorization': `Basic ${credentials}`, 'Content-Type': 'application/json' }
  });
  const token = auth.access_token;
  console.log('Token obtido!');

  // Passo 2: Gerar QR Code PIX
  const { data: pix } = await axios.post(`${BASE_URL}/pix/qrcode`, {
    amount: 100.00,
    external_id: `pedido-${Date.now()}`,
    postback_url: 'https://seusite.com/webhook',
    payer_name: 'Joao Silva',
    payer_document: '12345678900',
  }, {
    headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }
  });
  console.log('QR Code gerado:', pix.transaction_id);
  console.log('Copia e Cola:', pix.copy_paste);

  // Passo 3: Consultar Saldo
  const { data: balance } = await axios.get(`${BASE_URL}/balance`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  console.log('Saldo disponivel: R$', balance.available_balance);
}

main().catch(console.error);

// Webhook receiver (Express)
// const express = require('express');
// const app = express();
// app.use(express.json());
// app.post('/webhook', (req, res) => {
//   const { event, transaction } = req.body;
//   if (event === 'transaction.paid') {
//     console.log('Pago:', transaction.external_id);
//   }
//   res.json({ received: true });
// });

Integracao Completa em Python

import requests
import base64

BASE_URL = 'https://app.sellxpay.com.br/api/v1'
CLIENT_ID = 'SEU_CLIENT_ID'
CLIENT_SECRET = 'SEU_CLIENT_SECRET'

# Passo 1: Autenticacao
credentials = base64.b64encode(f'{CLIENT_ID}:{CLIENT_SECRET}'.encode()).decode()
auth = requests.post(f'{BASE_URL}/oauth/token', headers={
    'Authorization': f'Basic {credentials}',
    'Content-Type': 'application/json',
}).json()
token = auth['access_token']
print('Token obtido!')

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json',
}

# Passo 2: Gerar QR Code PIX
pix = requests.post(f'{BASE_URL}/pix/qrcode', headers=headers, json={
    'amount': 100.00,
    'external_id': 'pedido-12345',
    'postback_url': 'https://seusite.com/webhook',
    'payer_name': 'Joao Silva',
    'payer_document': '12345678900',
}).json()
print(f'QR Code gerado: {pix["transaction_id"]}')
print(f'Copia e Cola: {pix["copy_paste"]}')

# Passo 3: Consultar Saldo
balance = requests.get(f'{BASE_URL}/balance', headers=headers).json()
print(f'Saldo disponivel: R$ {balance["available_balance"]:.2f}')

# Webhook receiver (Flask)
# from flask import Flask, request, jsonify
# app = Flask(__name__)
# @app.route('/webhook', methods=['POST'])
# def webhook():
#     payload = request.json
#     if payload['event'] == 'transaction.paid':
#         print('Pago:', payload['transaction']['external_id'])
#     return jsonify(received=True)