POST/api/v1/transactions/create

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>

Identificador único da empresa

X-API-KeyObrigatório

<api_key>

Chave de autenticação da API

Request Body

{
  "paymentMethod": "PIX",
  "amount": 500,
  "description": "Pagamento de produto X",
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678900"
  },
  "metadata": {
    "orderId": "ORD-12345",
    "customField": "valor personalizado"
  }
}

Parâmetros

paymentMethodstring

Método de pagamento. Valores aceitos: "PIX"

amountinteger

Valor em centavos (ex: 500 = R$ 5,00)

descriptionstring

Descrição da transação

customerobject

Dados do cliente

name - Nome completo do cliente

email - Email do cliente

document - CPF ou CNPJ (apenas números)

metadataobject (opcional)

Dados adicionais personalizados

Response

200 - Sucesso

{
  "data": {
    "id": "f2d96218-6635-4839-81d7-9f2d5aaf4f14",
    "status": "WAITING_PAYMENT",
    "paymentMethod": "PIX",
    "amount": 500,
    "description": "Pagamento de produto X",
    "qrCode": "00020126580014br.gov.bcb.pix...",
    "qrCodeUrl": "https://api.splitgames.com.br/qr/f2d96218...",
    "expiresAt": "2024-01-15T23:59:59Z",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678900"
    },
    "metadata": {
      "orderId": "ORD-12345",
      "customField": "valor personalizado"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "status": 200,
  "message": "Transação criada com sucesso."
}

400 - Bad Request

{
  "type": "https://api.splitgames.com.br/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Os dados fornecidos são inválidos.",
  "instance": "/api/v1/transactions/create",
  "errors": [
    {
      "field": "amount",
      "message": "O valor deve ser maior que zero."
    }
  ]
}

401 - Unauthorized

{
  "type": "https://api.splitgames.com.br/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Credenciais inválidas ou ausentes.",
  "instance": "/api/v1/transactions/create"
}

Exemplo de Requisição

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: seu-client-id" \
  -H "X-API-Key: sua-api-key" \
  -d '{
    "paymentMethod": "PIX",
    "amount": 500,
    "description": "Pagamento de produto X",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678900"
    }
  }'