● API PIX — Gateway de Pagamentos

xcob Developer Portal

Integre pagamentos PIX em seus aplicativos com a API XCOB. Geração de QR Code, Cash Out e confirmação de pagamentos em segundos.

⚡ Testar API 📖 Ver Documentação

Autenticação

Todas as requisições devem incluir sua api-key no corpo da requisição. Obtenha sua chave no painel xcob.

🔑
Acesse x.xcob.rest → Documentação para gerar sua API Key. Mantenha-a segura e nunca a exponha no frontend — sempre faça chamadas pelo backend.

Base URL

Todas as requisições são feitas para o endpoint base da API xcob.

BASE https://api.xcob.rest/v1/

Cash In — Gerar PIX

Gere um QR Code PIX para receber pagamentos. A requisição retorna o código PIX e o QR Code em base64.

POST https://api.xcob.rest/v1/gateway/
💡
O campo amount é em reais inteiros. Envie 100 para cobrar R$ 100,00. Não use centavos (não envie 10000 para R$ 100,00).

Parâmetros da Requisição

JSON 
{
  "amount": 100,
  "client": {
    "name": "João Silva",
    "document": "12345678901",
    "telefone": "11999999999",
    "email": "joao@email.com"
  },
  "api-key": "sua-api-key-aqui"
}
ParâmetroTipoObrigatórioDescrição
amountnumber✓ SimValor em reais inteiros. Ex: 100 = R$ 100,00
client.namestring✓ SimNome completo do pagador
client.documentstring✓ SimCPF ou CNPJ sem formatação (só números)
client.telefonestringOpcionalTelefone com DDD sem formatação
client.emailstringOpcionalEmail do pagador
api-keystring✓ SimSua chave de API xcob

Exemplo — PHP

PHP 
<?php

// Nunca inclua a api-key diretamente no frontend
// Sempre faça esta chamada pelo seu backend (servidor)

$data = [
  'amount'  => 100,
  'client'  => [
    'name'     => 'João Silva',
    'document' => '12345678901',
    'telefone' => '11999999999',
    'email'    => 'joao@email.com',
  ],
  'api-key' => 'sua-api-key-aqui',
];

$ch = curl_init('https://api.xcob.rest/v1/gateway/');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => json_encode($data),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Exibe o código PIX para o cliente copiar
echo $response['paymentCode'];

// Guarde o idTransaction para consultar o status via webhook
$idTransaction = $response['idTransaction'];
?>

Exemplo — Python

Python 
import requests

# Nunca exponha a api-key no frontend
response = requests.post(
  'https://api.xcob.rest/v1/gateway/',
  json={
    'amount': 100,
    'client': {
      'name': 'João Silva',
      'document': '12345678901',
      'email': 'joao@email.com',
    },
    'api-key': 'sua-api-key-aqui',
  }
)
data = response.json()
print(data['paymentCode'])
print(data['idTransaction'])  # Guarde para consultar status

Cash Out — Transferência PIX

Realize transferências via PIX para contas de terceiros. Requer saldo disponível na sua conta xcob.

POST https://api.xcob.rest/v1/cashout/
⚠️
A operação de Cash Out debita saldo real da sua conta. Valide os dados do beneficiário antes de enviar. Transferências não podem ser estornadas.

Parâmetros da Requisição

JSON 
{
  "amount": 50.00,
  "pixKeyType": "CPF",
  "pixKey": "12345678901",
  "beneficiaryName": "Maria Souza",
  "beneficiaryDocument": "12345678901",
  "api-key": "sua-api-key-aqui"
}
ParâmetroTipoObrigatórioDescrição
amountnumber✓ SimValor em reais. Ex: 50.00 = R$ 50,00
pixKeyTypestring✓ SimTipo da chave PIX: CPF, CNPJ, EMAIL, TELEFONE, EVP
pixKeystring✓ SimChave PIX do beneficiário (sem formatação para CPF/CNPJ)
beneficiaryNamestring✓ SimNome completo do beneficiário
beneficiaryDocumentstring✓ SimCPF ou CNPJ do beneficiário sem formatação
api-keystring✓ SimSua chave de API xcob

Resposta de Sucesso

JSON 
{
  "status": "success",
  "message": "Transferência realizada com sucesso",
  "idTransaction": "52fc5262-4063-4900-933b-55e69850",
  "amount": 50.00
}

Webhook — Consultar Status

Consulte o status de um pagamento usando o idTransaction retornado no Cash In.

POST https://api.xcob.rest/v1/webhook/
💡
Recomendamos fazer polling a cada 2 segundos até o status mudar para PAID_OUT. Pare as consultas após a confirmação para não sobrecarregar a API.

Parâmetros da Requisição

JSON 
{
  "idtransaction": "52fc5262-4063-4900-933b-55e69850"
}

Possíveis valores de status

StatusDescrição
PAID_OUTPagamento confirmado. Libere o produto/serviço.
WAITING_FOR_APPROVALAguardando pagamento. Continue o polling.
EXPIREDPIX expirado. Gere um novo se necessário.

Exemplo de polling — JavaScript

JavaScript 
async function checkPayment(idTransaction) {
  const response = await fetch('https://api.xcob.rest/v1/webhook/', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ idtransaction: idTransaction })
  });
  const data = await response.json();

  if (data.status === 'PAID_OUT') {
    // Pagamento confirmado — libere o produto
    console.log('Pago!');
  } else if (data.status === 'WAITING_FOR_APPROVAL') {
    // Aguarda e tenta novamente em 2 segundos
    setTimeout(() => checkPayment(idTransaction), 2000);
  }
}

Respostas da API

Referência completa dos códigos de status e exemplos de resposta.

JSON 
{
  "status": "success",
  "message": "ok",
  "paymentCode": "00020101021226790014br.gov.bcb.pix...",
  "idTransaction": "52fc5262-4063-4900-933b-55e69850",
  "paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
}

// paymentCode     → string PIX para copiar e colar no app do banco
// idTransaction   → use para consultar status via /webhook/
// paymentCodeBase64 → imagem QR Code em base64 (PNG), exiba com:
//   <img src="data:image/png;base64,{paymentCodeBase64}">
JSON 
{
  "status": "error",
  "message": "API Key inválida ou sem permissão"
}

// Verifique se a api-key está correta e ativa no painel xcob
JSON 
{
  "status": "error",
  "message": "Parâmetros inválidos ou ausentes"
}

// Verifique se todos os campos obrigatórios foram enviados
// e se o Content-Type está como application/json

Testador Interativo

Teste a API diretamente aqui. Preencha os campos e clique em Testar para ver a resposta em tempo real.

💡
Use sua API Key real obtida no painel xcob para realizar testes com transações reais.

Cash In — Gerar PIX

Resposta
—
QR Code PIX

QR Code PIX gerado