SP
SplitPay
POST

Criar Transação (PIX Dinâmico)

Cria uma transação PIX Dinâmico e registra no banco. Valores monetários são sempre em centavos (inteiros).

Atenção: Este endpoint suporta apenas paymentMethod: "PIX" no momento. Boleto e Cartão de Crédito serão adicionados em breve.

Endpoint

POST https://api.splitgames.com.br/api/v1/transactions/create

Headers

Content-TypeObrigatório

application/json

AcceptObrigatório

application/json

X-Client-IdObrigatório

<client_id>

X-API-KeyObrigatório

<api_key>

Idempotency-KeyRecomendado

tx_<unique>

Idempotency-Key: Garante que a transação não será duplicada no provedor (A55). Use um identificador único por requisição (ex: tx_{timestamp}_{random}).

Regras Atuais

  • paymentMethod: apenas "PIX" é suportado neste endpoint
  • amount e unitPrice devem ser informados em centavos (ex: R$ 5,00 = 500)
  • Lead: sempre é criado um novo Lead; o LeadId nunca fica nulo
  • TransactionResponse é salvo como JSON no banco de dados
  • pix.expiresInDays: padrão é 1 dia (mínimo efetivo)

Request Body (PIX)

Importante: Todos os valores monetários (amount, unitPrice, fee) devem ser informados em centavos (inteiros).

{
  "amount": 500,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "installments": 1,
  "customer": {
    "id": "CUST-123",
    "name": "João Teste",
    "email": "joao.teste@example.com",
    "document": { "number": "24577481600", "type": "CPF" },
    "phone": "11987654321",
    "externalRef": "LEAD-1234"
  },
  "shipping": {
    "fee": 0,
    "address": {
      "street": "Rua dos Testes",
      "streetNumber": "123",
      "complement": "Sala 2",
      "zipCode": "01001000",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    }
  },
  "items": [
    {
      "title": "Produto X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true,
      "externalRef": "SKU-001"
    }
  ],
  "pix": { "expiresInDays": 1 },
  "postbackUrl": "",
  "metadata": "{\"origem\":\"n8n\",\"ambiente\":\"homologacao\"}",
  "traceable": false,
  "ip": "177.123.45.67"
}

Campos Importantes

amount

Valor em centavos (obrigatório)

paymentMethod

Deve ser "PIX" (obrigatório)

customer.document.number

Usado como devedorDocumento (somente dígitos)

pix.expiresInDays

Dias para expiração (padrão: 1, mínimo: 1)

postbackUrl

URL para receber notificações de mudança de status (webhook)

metadata

Campo livre em formato string, persistido no retorno

Response 200 (PIX)

Estrutura completa da resposta PIX Dinâmico:

{
  "data": {
    "id": "7e11f5a0b2f8415aac5867514a",
    "externalRef": "EXT-ws8fa2t2",
    "amount": 500,
    "refundedAmount": 0,
    "providerCompanyId": "b6877393-8a98-4e4e-8a20-e086aacf3d8c",
    "companyId": 1,
    "installments": 1,
    "paymentMethod": "PIX",
    "status": "WAITING_PAYMENT",
    "postbackUrl": "",
    "metadata": "{\"rnd\":\"pyzlyg6e\"}",
    "traceable": false,
    "secureId": null,
    "secureUrl": null,
    "pix": {
      "brcode": "00020101021226820014br.gov.bcb.pix2560qrcode.pagsm.com.br/pix/4d9fe52a-e9f3-4967-b4c6-e40c9c1b62115204000053039865802BR5907WLStore6008SaoPaulo61088935491762070503***63044A89",
      "qrcode": null,
      "payloadBase64": "MDAwMjAxMDEwMjEyMjY4MjAwMTRici5nb3YuYmNiLnBpeDI1NjBxcmNvZGUucGFnc20uY29tLmJyL3BpeC80ZDlmZTUyYS1lOWYzLTQ5NjctYjRjNi1lNDBjOWMxYjYyMTE1MjA0MDAwMDUzMDM5ODY1ODAyQlI1OTA3V0xTdG9yZTYwMDhTYW9QYXVsbzYxMDg4OTM1NDkxNzYyMDcwNTAzKioqNjMwNDRBODk",
      "imagemQrCodeInBase64": null,
      "qrcodeBase64": null,
      "txId": "7e11f5a0b2f8415aac5867514a",
      "expiresAt": "2025-11-26T06:12:00.6987973+00:00"
    }
  },
  "status": 200,
  "message": "Transação criada e registrada com sucesso."
}

Campos da Resposta

data.id (providerTxId)

ID da transação no provedor (A55). Guarde este valor para consultas posteriores e reconciliação.

pix.brcode

String BR Code (Copia e Cola). Use para copiar/colar ou renderizar QR Code client-side.

pix.payloadBase64

Payload PIX codificado em Base64. Pode ser usado para gerar QR Code.

pix.txId

Transaction ID único do PIX Dinâmico (TxID da A55).

pix.expiresAt

Data/hora de expiração em formato ISO-8601 UTC.

pix.qrcode / imagemQrCodeInBase64 / qrcodeBase64

Atualmente retornam null. Use o brcode ou payloadBase64 para gerar o QR Code no client-side.

Erros Comuns

400 - Validação

  • "Somente PIX é suportado neste endpoint."
  • "amount inválido (centavos > 0)."
  • Campos obrigatórios ausentes

403 - Acesso Negado

Credenciais válidas, mas sem permissão para acessar a empresa.

500 - Erro Interno

  • Configuração: "Chave Pix não configurada (A55:PixKey)."
  • Erro de banco: problema ao salvar transação
  • Erro de integração com provedor

Exemplo: cURL

curl -X POST https://api.splitgames.com.br/api/v1/transactions/create \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-API-Key: <API_KEY>" \
  -H "Idempotency-Key: tx_$(date +%s)_$RANDOM" \
  -d '{
    "amount": 500,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "installments": 1,
    "customer": {
      "id": "CUST-123",
      "name": "João",
      "email": "joao@ex.com",
      "document": { "number": "24577481600", "type": "CPF" },
      "phone": "11987654321",
      "externalRef": "LEAD-1234"
    },
    "shipping": {
      "fee": 0,
      "address": {
        "street": "Rua dos Testes",
        "streetNumber": "123",
        "complement": "Sala 2",
        "zipCode": "01001000",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    },
    "items": [{
      "title": "Produto X",
      "unitPrice": 500,
      "quantity": 1,
      "tangible": true,
      "externalRef": "SKU-001"
    }],
    "pix": { "expiresInDays": 1 },
    "postbackUrl": "",
    "metadata": "{\"origem\":\"n8n\",\"ambiente\":\"homologacao\"}",
    "traceable": false,
    "ip": "177.123.45.67"
  }'

Exemplo: JavaScript (fetch)

const response = await fetch("https://api.splitgames.com.br/api/v1/transactions/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Client-Id": "<CLIENT_ID>",
    "X-API-Key": "<API_KEY>",
    "Idempotency-Key": `tx_${Date.now()}_${Math.floor(Math.random()*1e6)}`
  },
  body: JSON.stringify({
    amount: 500,
    currency: "BRL",
    paymentMethod: "PIX",
    installments: 1,
    customer: {
      id: "CUST-123",
      name: "João",
      email: "joao@ex.com",
      document: { number: "24577481600", type: "CPF" },
      phone: "11987654321",
      externalRef: "LEAD-1234"
    },
    shipping: {
      fee: 0,
      address: {
        street: "Rua dos Testes",
        streetNumber: "123",
        complement: "Sala 2",
        zipCode: "01001000",
        neighborhood: "Centro",
        city: "São Paulo",
        state: "SP",
        country: "BR"
      }
    },
    items: [{
      title: "Produto X",
      unitPrice: 500,
      quantity: 1,
      tangible: true,
      externalRef: "SKU-001"
    }],
    pix: { expiresInDays: 1 },
    postbackUrl: "",
    metadata: JSON.stringify({ origem: "app", ambiente: "producao" }),
    traceable: false,
    ip: "177.123.45.67"
  })
});

const data = await response.json();
console.log('BR Code PIX:', data.data.pix.brcode);
console.log('Expira em:', data.data.pix.expiresAt);

📌 Observações Importantes

  • Sempre cria um novo Lead - não reutiliza Leads existentes
  • data.id é o providerTxId - guarde para consultas e reconciliação
  • pix.brcode contém o código PIX Copia e Cola completo
  • Use pix.brcode para gerar QR Code no client-side (ex: biblioteca qrcode.js)
  • pix.expiresAt indica quando o PIX expirará (formato ISO-8601 UTC)
  • metadata é retornado exatamente como enviado (não parseado)
  • postbackUrl deve estar configurado para receber webhooks de atualização de status
  • Idempotency-Key evita duplicação de transações no provedor