Introdução
A API S6XPay permite integrar pagamentos PIX e cartão de crédito (página de pagamento segura na S6X) em aplicações, sistemas e plataformas externas.
- Gerar cobranças PIX avulsas (Cash-in tradicional)
- Cobrança via Cartão de Crédito (página de pagamento S6X)
- Split de pagamentos entre múltiplos destinatários
- Realizar transferências PIX (Cash-out)
- Consultar status de transações
- Receber notificações via webhook
- Rastreamento UTM integrado com UTMify
Base URL: https://s6xpay.com/api/v1
| Limite | Valor |
|---|---|
| Cash-in (mín. / máx.) | R$ 1,00 — R$ 1.000,00 |
| Cash-out (mín. / máx.) | R$ 10,00 — R$ 1.000,00 |
| Taxa fixa por saque (API) | R$ 1,00 |
| Taxa percentual por saque (API) | 1,6% |
Autenticação
Todas as requisições devem incluir os headers abaixo.
X-Client-Id: seu_client_id
X-Client-Secret: seu_client_secret
Content-Type: application/jsonCriar Pagamento (Cash-in PIX / Cartão)
POST /api/v1/payments perm: cash_in
Gera PIX (QR) ou cartão via payment_page_url (página S6X). Use card_mode=charge (única) ou card_mode=subscription (mensal automático). checkout_url é alias da URL. Cartão exige habilitação na plataforma.
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
amount | number | Sim | Valor em reais (mín: R$ 1,00, máx: R$ 1.000,00) |
customer.name | string | Sim | Nome do cliente |
customer.document | string | Não | CPF/CNPJ. Gerado automaticamente se ausente/inválido. |
customer.email | string | Não | E-mail do cliente |
description | string | Não | Descrição do pagamento |
product.name | string | Não | Nome do produto |
product.id | string | Não | ID/SKU do produto na sua plataforma |
product.image | string | Não | Imagem do produto no checkout de cartão: URL https pública ou data URI base64 (data:image/jpeg;base64,... ou png/webp/gif, máx. 500 KB). Base64 é salvo na S6X e exibido automaticamente. |
order_reference | string | Não | Referência do pedido na sua plataforma |
metadata | object | Não | Dados extras (retornados em todos os webhooks subsequentes) |
splits | array | Não | Split do valor líquido. Percentual, valor fixo ou os dois. O resíduo fica com o dono da credencial. Veja seção Split. |
utm | object | Não | Parâmetros UTM para rastreamento. Veja seção UTM. |
payment_method | enum | Não | Método de pagamento. Default pix. card retorna payment_page_url (página de pagamento S6X; requer cartão habilitado na plataforma). |
success_url | string (url) | Não | Apenas card: URL de retorno após pagamento aprovado (default: home). |
cancel_url | string (url) | Não | Apenas card: URL de retorno se o pagador cancelar (default: home). |
card_mode | enum | Não | charge/avulso = cobrança única no cartão; subscription/assinatura = assinatura mensal com renovação automática. Default: charge ou default da API key (card_assinatura). |
card_interval | enum | Não | Apenas assinatura: intervalo de cobrança (default month). |
card.extra_payment_methods | boolean | Não | Atalho legado: liga todos os métodos extras (wallets, boleto, PicPay) na payment_page_url. |
card.payment_methods | object | Não | Métodos na página de pagamento do cartão: { card, apple_pay, google_pay, boleto, picpay } (wallets = atalho legado para os dois). Se omitido, usa card_payment_methods da credencial ou só cartão. |
{
"amount": 99.90,
"customer": {
"name": "João Silva",
"document": "12345678900",
"email": "joao@email.com"
},
"description": "Compra na Loja XYZ",
"product": {
"name": "Curso de Marketing Digital",
"id": "PROD-123",
"image": "https://exemplo.com/imagem.jpg"
},
"order_reference": "PEDIDO-456",
"metadata": {
"custom_field": "valor personalizado"
}
}{
"success": true,
"data": {
"transaction_id": "API-1-1704654321-xYz12AbC",
"status": "pending",
"amount": 99.90,
"fee": 3.99,
"net_amount": 95.91,
"pix": {
"qr_code": "00020126...",
"qr_code_base64": "iVBORw0KGgoAAAANSUhEU...",
"copy_paste": "00020126..."
},
"expires_at": "2026-01-07T11:25:21.000000Z",
"created_at": "2026-01-07T10:55:21.000000Z"
}
}{
"amount": 149.90,
"payment_method": "card",
"customer": {
"name": "João Silva",
"document": "12345678900",
"email": "joao@email.com"
},
"description": "Compra na Loja XYZ",
"order_reference": "PEDIDO-456",
"success_url": "https://seusite.com/obrigado",
"cancel_url": "https://seusite.com/checkout",
"card": {
"payment_methods": {
"card": true,
"wallets": true,
"boleto": false,
"picpay": false
}
}
}{
"amount": 37.99,
"payment_method": "card",
"card_mode": "subscription",
"card_interval": "month",
"customer": {
"name": "Night",
"document": "12345678900",
"email": "cliente@email.com"
},
"description": "Assinatura Mensal — Project Six",
"order_reference": "SUB-P6-001",
"success_url": "https://seusite.com/assinatura/ok",
"cancel_url": "https://seusite.com/assinatura/cancelada"
}{
"success": true,
"data": {
"transaction_id": "API-1-1704654321-xYz12AbC",
"status": "pending",
"payment_method": "card",
"amount": 149.90,
"fee": 7.49,
"net_amount": 142.41,
"card": {
"flow": "s6x_payment_page",
"payment_page_url": "https://s6xpay.com/pagar/cartao/API-1-...?signature=...",
"checkout_url": "https://s6xpay.com/pagar/cartao/API-1-...?signature=...",
"card_mode": "charge",
"card_interval": "month"
},
"expires_at": "2026-01-07T11:25:21.000000Z",
"created_at": "2026-01-07T10:55:21.000000Z"
}
}Consultar Status da Transação
GET /api/v1/payments/{transaction_id} perm: status
Consulta o status atual de uma transação pelo ID.
{
"success": true,
"data": {
"transaction_id": "API-1-1704654321-xYz12AbC",
"type": "cash_in",
"status": "paid",
"amount": 99.90,
"fee": 3.99,
"net_amount": 95.91,
"customer": {
"name": "João Silva",
"email": "joao@email.com",
"document": "12345678900"
},
"pix_data": {
"end2end_id": "E12345678202501071055..."
},
"metadata": {
"order_id": "123",
"product": "Curso Online"
},
"paid_at": "2026-01-07T11:00:15.000000Z",
"expires_at": "2026-01-07T11:25:21.000000Z",
"created_at": "2026-01-07T10:55:21.000000Z"
}
}Realizar Saque PIX (Cash-out)
POST /api/v1/withdrawals perm: cash_out
Realiza transferência PIX do saldo da carteira para qualquer chave PIX.
| Campo | Tipo | Obrig. | Descrição |
|---|---|---|---|
amount | number | Sim | Valor em reais |
pix_key | string | Sim | Chave PIX de destino |
pix_key_type | enum | Sim | Tipo da chave PIX |
description | string | Não | Descrição do saque |
{
"amount": 100.00,
"pix_key": "12345678900",
"pix_key_type": "CPF",
"description": "Saque automático"
}Consultar Saldo
GET /api/v1/balance perm:
Retorna o saldo atual da carteira S6XPay (available, pending, total).
{
"success": true,
"data": {
"available": 1500.00,
"pending": 250.00,
"total": 1750.00
}
}Listar Transações
GET /api/v1/transactions perm:
Lista transações realizadas via API com paginação.
Split de Pagamentos
Divide o valor líquido entre destinatários, por percentual, valor fixo ou os dois juntos. O que sobrar fica com você.
Simples e prático
Cada destinatário pode receber um percentual do líquido, um valor fixo em reais, ou os dois somados. O que sobrar fica com você.
valor = líquido × percentual / 100 + valor fixo
Exemplo: 10% + R$ 1,50 sobre R$ 96,00 líquidos
→ R$ 11,10 para o destinatário
→ o restante fica com vocêCasos de uso
- Afiliado: 30% → você fica com 70%
- Taxa fixa: R$ 1,50 por venda, sem percentual
- Os dois: 10% + R$ 1,00 no mesmo destinatário
- Co-produtores: 50% + 50% → você fica com 0%
Taxa de split externo
Quando o destinatário NÃO é usuário da plataforma e possui chave PIX, as taxas de transferência (R$ 1,00 + 1,60%) são deduzidas do valor do split.
| field | type | required | description |
|---|---|---|---|
| splits | array | False | Array de destinatários do split (máx: 10) |
| splits[].email | string | True | E-mail do destinatário (credita na wallet se cadastrado) |
| splits[].percentage | number | False | Percentual do valor líquido (0,01 a 99,99). Obrigatório se não houver fixed_amount |
| splits[].fixed_amount | number | False | Valor fixo em reais, somado ao percentual. Obrigatório se não houver percentage |
| splits[].pix_key | string | False | Chave PIX (se não for usuário da plataforma) |
| splits[].pix_key_type | string | False | CPF, CNPJ, EMAIL, PHONE, EVP ou RANDOM |
Quando o pagamento é confirmado, o sistema processa os splits automaticamente.
O valor restante (não distribuído via splits) é creditado automaticamente na sua wallet.
Se o e-mail pertence a um usuário cadastrado, o split é creditado na wallet dele (sem taxas adicionais).
Se o e-mail não está cadastrado mas tem chave PIX, a transferência é feita via PIX (taxas de saque deduzidas do split).
O webhook inclui os dados de split com status atualizado de cada recebedor.
// Informe percentage, fixed_amount ou os dois em cada destinatário. A soma dos percentuais pode ir até 100%. A soma dos valores calculados não pode passar do líquido.
// Credencial criada por um parceiro OneTap pode ter um teto menor, em percentual e/ou em reais, imposto pela S6XPay. Acima do teto a API responde 422 e a cobrança não é criada.
{
"amount": 100.00,
"customer": { "name": "João Silva", "document": "12345678900" },
"splits": [{ "email": "afiliado@email.com", "percentage": 30 }]
}{
"amount": 100.00,
"customer": { "name": "João Silva", "document": "12345678900" },
"splits": [{ "email": "parceiro@email.com", "fixed_amount": 1.50 }]
}{
"amount": 100.00,
"customer": { "name": "João Silva", "document": "12345678900" },
"splits": [{ "email": "parceiro@email.com", "percentage": 10, "fixed_amount": 1.50 }]
}{
"amount": 100.00,
"customer": { "name": "João Silva", "document": "12345678900" },
"splits": [
{ "email": "parceiro1@email.com", "percentage": 25 },
{ "email": "parceiro2@email.com", "percentage": 30 }
]
}{
"amount": 200.00,
"customer": { "name": "Maria Santos", "document": "98765432100" },
"splits": [{
"email": "parceiro@externo.com",
"percentage": 20,
"pix_key": "12345678900",
"pix_key_type": "CPF"
}]
}{
"success": true,
"data": {
"transaction_id": "API-1-1704654321-xYz12AbC",
"status": "pending",
"amount": 100.00,
"fee": 4.00,
"net_amount": 96.00,
"owner_amount": 84.90,
"owner_percentage": 90,
"pix": { "qr_code": "00020126...", "copy_paste": "00020126..." },
"splits": [{
"email": "parceiro@email.com",
"percentage": 10,
"fixed_amount": 1.50,
"amount": 11.10,
"status": "pending"
}],
"expires_at": "2026-01-07T11:25:21.000000Z",
"created_at": "2026-01-07T10:55:21.000000Z"
}
}Campos UTM para Tracking
Envie parâmetros de rastreamento junto à criação do pagamento para análise de origem de vendas em plataformas como UTMify.
Integração com UTMify
Com UTMify configurado em Rastreamento → UTMify, os dados de venda são enviados automaticamente incluindo UTMs.
- waiting_payment — ao gerar PIX (configurável)
- paid — ao confirmar pagamento (recomendado)
- refunded — ao reembolsar (configurável)
| field | type | description |
|---|---|---|
| utm.utm_source | string | Origem da campanha (ex.: google, facebook) |
| utm.utm_medium | string | Meio da campanha (ex.: cpc, orgânico) |
| utm.utm_campaign | string | Nome da campanha (ex.: black_friday) |
| utm.utm_term | string | Termo pesquisado (ex.: curso+online) |
| utm.utm_content | string | Conteúdo do anúncio (ex.: banner_topo) |
| utm.src | string | Código especial de origem |
| utm.sck | string | Código especial de sessão |
// Se não forem enviados dados UTM, a integração continua funcionando normalmente.
// Configure UTMify, Pixel ADS e Google Analytics em Rastreamento no painel.
{
"amount": 100.00,
"description": "Compra de Curso Avançado",
"customer": {
"name": "João da Silva",
"document": "123.456.789-00",
"email": "joao@email.com"
},
"order_reference": "pedido_456",
"splits": [
{ "email": "parceiro1@example.com", "percentage": 10.5 },
{ "email": "parceiro2@example.com", "percentage": 5.0 }
],
"utm": {
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "black_friday",
"utm_term": "curso+programacao",
"utm_content": "banner_topo",
"src": "src_valor",
"sck": "sck_valor"
}
}Webhooks
Os eventos, a assinatura e os exemplos de payload estão na página de Webhooks.
Erros
| HTTP | Código | Descrição |
|---|---|---|
| 401 | missing_credentials | Headers de autenticação não enviados |
| 401 | invalid_credentials | Client ID ou Secret inválidos |
| 403 | credential_inactive | Credencial desativada ou revogada |
| 403 | ip_not_allowed | IP não está na whitelist |
| 403 | permission_denied | Permissão não concedida para esta operação |
| 422 | transaction_limit_exceeded | Valor excede limite por transação |
| 422 | daily_limit_exceeded | Limite diário atingido |
| 422 | insufficient_balance | Saldo insuficiente para cash-out |
| 404 | transaction_not_found | Transação não encontrada |
| 422 | validation_error | Dados inválidos (veja campo errors) |
| 500 | payment_creation_failed | Falha ao criar pagamento na plataforma |
| 403 | card_payments_unavailable | Cartão indisponível na plataforma no momento |
| 403 | card_gateway_unavailable | Cartão temporariamente indisponível na plataforma |