<< s6xpay .criar conta

[docs] api rest · v1

API REST

PIX, cartão, saques e disputas. Crie cobranças, consulte pagamentos e receba webhooks.

[api rest][webhooks][mcp]

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

LimiteValor
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.

headers
X-Client-Id: seu_client_id
X-Client-Secret: seu_client_secret
Content-Type: application/json

Criar 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.

CampoTipoObrig.Descrição
amountnumberSimValor em reais (mín: R$ 1,00, máx: R$ 1.000,00)
customer.namestringSimNome do cliente
customer.documentstringNãoCPF/CNPJ. Gerado automaticamente se ausente/inválido.
customer.emailstringNãoE-mail do cliente
descriptionstringNãoDescrição do pagamento
product.namestringNãoNome do produto
product.idstringNãoID/SKU do produto na sua plataforma
product.imagestringNãoImagem 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_referencestringNãoReferência do pedido na sua plataforma
metadataobjectNãoDados extras (retornados em todos os webhooks subsequentes)
splitsarrayNãoSplit do valor líquido. Percentual, valor fixo ou os dois. O resíduo fica com o dono da credencial. Veja seção Split.
utmobjectNãoParâmetros UTM para rastreamento. Veja seção UTM.
payment_methodenumNãoMétodo de pagamento. Default pix. card retorna payment_page_url (página de pagamento S6X; requer cartão habilitado na plataforma).
success_urlstring (url)NãoApenas card: URL de retorno após pagamento aprovado (default: home).
cancel_urlstring (url)NãoApenas card: URL de retorno se o pagador cancelar (default: home).
card_modeenumNãocharge/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_intervalenumNãoApenas assinatura: intervalo de cobrança (default month).
card.extra_payment_methodsbooleanNãoAtalho legado: liga todos os métodos extras (wallets, boleto, PicPay) na payment_page_url.
card.payment_methodsobjectNãoMé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.
Request · json
{
  "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"
  }
}
Response (201) · json
{
  "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"
  }
}
Request (cartão avulso) · json
{
  "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
    }
  }
}
Request (cartão assinatura) · json
{
  "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"
}
Response cartão (201) · json
{
  "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.

Response (200) · json
{
  "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.

CampoTipoObrig.Descrição
amountnumberSimValor em reais
pix_keystringSimChave PIX de destino
pix_key_typeenumSimTipo da chave PIX
descriptionstringNãoDescrição do saque
Request · json
{
  "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).

Response (200) · json
{
  "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.

fieldtyperequireddescription
splitsarrayFalseArray de destinatários do split (máx: 10)
splits[].emailstringTrueE-mail do destinatário (credita na wallet se cadastrado)
splits[].percentagenumberFalsePercentual do valor líquido (0,01 a 99,99). Obrigatório se não houver fixed_amount
splits[].fixed_amountnumberFalseValor fixo em reais, somado ao percentual. Obrigatório se não houver percentage
splits[].pix_keystringFalseChave PIX (se não for usuário da plataforma)
splits[].pix_key_typestringFalseCPF, 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.

Exemplo simples: 30% para afiliado
{
  "amount": 100.00,
  "customer": { "name": "João Silva", "document": "12345678900" },
  "splits": [{ "email": "afiliado@email.com", "percentage": 30 }]
}
Valor fixo: R$ 1,50
{
  "amount": 100.00,
  "customer": { "name": "João Silva", "document": "12345678900" },
  "splits": [{ "email": "parceiro@email.com", "fixed_amount": 1.50 }]
}
Percentual e valor fixo juntos
{
  "amount": 100.00,
  "customer": { "name": "João Silva", "document": "12345678900" },
  "splits": [{ "email": "parceiro@email.com", "percentage": 10, "fixed_amount": 1.50 }]
}
Dois destinatários: 25% + 30%
{
  "amount": 100.00,
  "customer": { "name": "João Silva", "document": "12345678900" },
  "splits": [
    { "email": "parceiro1@email.com", "percentage": 25 },
    { "email": "parceiro2@email.com", "percentage": 30 }
  ]
}
Split com PIX externo
{
  "amount": 200.00,
  "customer": { "name": "Maria Santos", "document": "98765432100" },
  "splits": [{
    "email": "parceiro@externo.com",
    "percentage": 20,
    "pix_key": "12345678900",
    "pix_key_type": "CPF"
  }]
}
Response com split
{
  "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)
fieldtypedescription
utm.utm_sourcestringOrigem da campanha (ex.: google, facebook)
utm.utm_mediumstringMeio da campanha (ex.: cpc, orgânico)
utm.utm_campaignstringNome da campanha (ex.: black_friday)
utm.utm_termstringTermo pesquisado (ex.: curso+online)
utm.utm_contentstringConteúdo do anúncio (ex.: banner_topo)
utm.srcstringCódigo especial de origem
utm.sckstringCó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.

Exemplo com UTM e split
{
  "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

HTTPCódigoDescrição
401missing_credentialsHeaders de autenticação não enviados
401invalid_credentialsClient ID ou Secret inválidos
403credential_inactiveCredencial desativada ou revogada
403ip_not_allowedIP não está na whitelist
403permission_deniedPermissão não concedida para esta operação
422transaction_limit_exceededValor excede limite por transação
422daily_limit_exceededLimite diário atingido
422insufficient_balanceSaldo insuficiente para cash-out
404transaction_not_foundTransação não encontrada
422validation_errorDados inválidos (veja campo errors)
500payment_creation_failedFalha ao criar pagamento na plataforma
403card_payments_unavailableCartão indisponível na plataforma no momento
403card_gateway_unavailableCartão temporariamente indisponível na plataforma