Gateway Pagamento API

v1

Documentação da API

Integre pagamentos PIX, saques e outras funcionalidades em seu sistema.

✓ PIX
✓ Cartão de Crédito
✓ Boleto
✓ Saques

Autenticação

Todas as requisições à API v1 requerem autenticação via Public Key e Secret Key. Essas credenciais são obtidas através do painel administrativo.

Headers Obrigatórios:

  • X-Public-Key: Sua chave pública
  • X-Secret-Key: Sua chave secreta
curl -X POST https://api.tulsapagamentos.com/api/v1/transactions \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: sua_public_key_aqui" \
  -H "X-Secret-Key: sua_secret_key_aqui" \
  -d '{
    "amount": 10000,
    "paymentMethod": "pix",
    ...
  }'

Endpoints

POST /api/v1/transactions

Cria uma nova transação de pagamento. Suporta PIX, cartão de crédito e boleto.

Headers:

Content-Type: application/json
X-Public-Key: sua_public_key
X-Secret-Key: sua_secret_key

Payload (PIX):

{
  "amount": 10000,
  "paymentMethod": "pix",
  "items": [
    {
      "title": "Produto Exemplo",
      "unitPrice": 10000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "phone": "11999999999",
    "document": {
      "number": "12345678901",
      "type": "cpf"
    },
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "streetNumber": "1000"
    }
  },
  "pix": {
    "expiresInDays": 1
  },
  "externalRef": "pedido_123"
}

Resposta (201 Created):

{
  "success": true,
  "data": {
    "transaction_id": "TXN123456789",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z",
    "pix": {
      "code": "00020126580014br.gov.bcb.pix...",
      "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
      "payment_link": "https://pix.example.com/pay/TXN123456789",
      "expires_at": "2024-01-16T10:30:00Z",
      "status": "pending"
    },
    "customer": {
      "id": 1,
      "name": "João Silva",
      "email": "joao@exemplo.com"
    },
    "items_count": 1,
    "shipping_fee": 0
  }
}

Importante: Todos os valores devem ser enviados em centavos (ex: R$ 10,00 = 1000).

POST /api/v1/pix/withdrawals

Cria uma nova solicitação de saque PIX com validação de chave PIX.

Headers:

Content-Type: application/json
X-Public-Key: sua_public_key
X-Secret-Key: sua_secret_key

Payload:

{
  "amount": 100.50,
  "pix_key": "usuario@exemplo.com",
  "pix_key_type": "email",
  "external_id": "ext_123456"
}

Tipos de Chave PIX:

  • cpf - CPF (11 dígitos)
  • cnpj - CNPJ (14 dígitos)
  • email - E-mail
  • phone ou telefone - Telefone
  • aleatoria ou random_key - Chave aleatória

Resposta (201 Created):

{
  "success": true,
  "message": "PIX withdrawal request created successfully",
  "data": {
    "id": 1,
    "enterprise_id": 1,
    "amount": 100.50,
    "external_id": "ext_123456",
    "status": {
      "code": 0,
      "label": "Pendente"
    },
    "method": {
      "code": 1,
      "label": "PIX"
    },
    "pix_key": "usuario@exemplo.com",
    "created_at": "2024-01-15T10:30:00Z",
    "fees": {
      "fixed_fee": 0.50,
      "variable_fee": 0.00,
      "total_fee": 0.50,
      "net_amount": 100.00
    }
  },
  "meta": {
    "approval_type": "automatic",
    "daily_limit": {
      "current": 0,
      "limit": 10000,
      "remaining": 10000
    },
    "pix_key_used": "usuario@exemplo.com",
    "pix_key_type_used": "email",
    "allow_any_pix": true
  }
}

Idempotência: Use o campo external_id para garantir que requisições duplicadas não criem saques múltiplos.

POST /api/v1/withdrawals

Cria uma nova solicitação de saque. Suporta PIX e crypto.

Payload (PIX):

{
  "amount": 100.50,
  "method": "pix",
  "pix_key": "usuario@exemplo.com",
  "external_id": "saque_123"
}

Payload (Crypto):

{
  "amount": 0.001,
  "method": "crypto",
  "crypto_key": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "external_id": "crypto_789"
}

Importante: Valores devem ser enviados em formato decimal (ex: 100.50 para R$ 100,50).

Exemplos de Código

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.tulsapagamentos.com/api/v1',
]);

$response = $client->post('/transactions', [
    'headers' => [
        'Content-Type' => 'application/json',
        'X-Public-Key' => 'sua_public_key',
        'X-Secret-Key' => 'sua_secret_key',
    ],
    'json' => [
        'amount' => 10000,
        'paymentMethod' => 'pix',
        'items' => [
            [
                'title' => 'Produto',
                'unitPrice' => 10000,
                'quantity' => 1,
                'tangible' => false,
            ],
        ],
        'customer' => [
            'name' => 'João Silva',
            'email' => 'joao@exemplo.com',
            'phone' => '11999999999',
            'document' => [
                'number' => '12345678901',
                'type' => 'cpf',
            ],
        ],
    ],
]);

$data = json_decode($response->getBody(), true);

JavaScript (Fetch)

const response = await fetch('https://api.tulsapagamentos.com/api/v1/transactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Public-Key': 'sua_public_key',
    'X-Secret-Key': 'sua_secret_key',
  },
  body: JSON.stringify({
    amount: 10000,
    paymentMethod: 'pix',
    items: [
      {
        title: 'Produto',
        unitPrice: 10000,
        quantity: 1,
        tangible: false,
      },
    ],
    customer: {
      name: 'João Silva',
      email: 'joao@exemplo.com',
      phone: '11999999999',
      document: {
        number: '12345678901',
        type: 'cpf',
      },
    },
  }),
});

const data = await response.json();

Python (Requests)

import requests

url = 'https://api.tulsapagamentos.com/api/v1/transactions'
headers = {
    'Content-Type': 'application/json',
    'X-Public-Key': 'sua_public_key',
    'X-Secret-Key': 'sua_secret_key',
}

payload = {
    'amount': 10000,
    'paymentMethod': 'pix',
    'items': [
        {
            'title': 'Produto',
            'unitPrice': 10000,
            'quantity': 1,
            'tangible': False,
        },
    ],
    'customer': {
        'name': 'João Silva',
        'email': 'joao@exemplo.com',
        'phone': '11999999999',
        'document': {
            'number': '12345678901',
            'type': 'cpf',
        },
    },
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

cURL

curl -X POST https://api.tulsapagamentos.com/api/v1/transactions \
  -H "Content-Type: application/json" \
  -H "X-Public-Key: sua_public_key" \
  -H "X-Secret-Key: sua_secret_key" \
  -d '{
    "amount": 10000,
    "paymentMethod": "pix",
    "items": [{
      "title": "Produto",
      "unitPrice": 10000,
      "quantity": 1,
      "tangible": false
    }],
    "customer": {
      "name": "João Silva",
      "email": "joao@exemplo.com",
      "phone": "11999999999",
      "document": {
        "number": "12345678901",
        "type": "cpf"
      }
    }
  }'

Códigos de Status HTTP

201
Created

Recurso criado com sucesso

200
OK

Requisição bem-sucedida (usado para idempotência)

401
Unauthorized

Credenciais inválidas ou ausentes

422
Unprocessable Entity

Erro de validação nos dados enviados

500
Internal Server Error

Erro interno do servidor