Documentação da API KeyGift

v1.0 HTTPS
Visão Geral

A API KeyGift permite integrar múltiplos métodos de pagamento através de uma interface unificada. Suportamos PIX, Boleto e Cartão de Crédito/Débito através de diversas adquirentes.

Base URL: https://keygift.store/api/v1
Autenticação

Atualmente a API não requer autenticação para criar pagamentos. Futuramente implementaremos tokens de API.

Métodos de Pagamento
PAGAMENTO PIX POST /payment/pix
Request Body:
{
  "amount": 100.50,
  "customer_name": "João Silva",
  "customer_tax_id": "12345678900",
  "customer_email": "joao@email.com",
  "callback_url": "https://seusite.com/webhook",
  "request_number": "pedido-12345"
}
Response:
{
  "success": true,
  "transaction_id": "txn_123456789",
  "payment_data": {
    "idTransaction": "suitpay_123",
    "qrcode": "data:image/png;base64,...",
    "qrcodeText": "0002010102123456...",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}
PAGAMENTO BOLETO POST /payment/boleto
Request Body:
{
  "amount": 100.50,
  "customer_name": "João Silva",
  "customer_tax_id": "12345678900",
  "customer_email": "joao@email.com",
  "customer_address": {
    "street": "Rua das Flores",
    "number": "123",
    "city": "São Paulo",
    "state": "SP",
    "zip": "01234-567"
  },
  "callback_url": "https://seusite.com/webhook",
  "request_number": "pedido-12345",
  "due_date": "2024-12-31"
}
Response:
{
  "success": true,
  "transaction_id": "txn_123456789",
  "payment_data": {
    "idTransaction": "suitpay_123",
    "barcode": "12345678901234567890123456789012345678901234",
    "digitableLine": "12345678901234567890123456789012345678901234",
    "pdfUrl": "https://...",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}
PAGAMENTO CARTÃO POST /payment/card
Request Body:
{
  "amount": 100.50,
  "customer_name": "João Silva",
  "customer_tax_id": "12345678900",
  "customer_email": "joao@email.com",
  "card_number": "4111111111111111",
  "card_expiry": "12/25",
  "card_cvv": "123",
  "card_holder": "João Silva",
  "installments": 1,
  "callback_url": "https://seusite.com/webhook",
  "request_number": "pedido-12345"
}
Response:
{
  "success": true,
  "transaction_id": "txn_123456789",
  "payment_data": {
    "idTransaction": "suitpay_123",
    "status": "APPROVED",
    "authorizationCode": "123456",
    "nsu": "123456789",
    "installments": 1
  }
}
Consulta de Status
CONSULTAR TRANSAÇÃO GET /transaction/{id}/status
Response:
{
  "success": true,
  "transaction": {
    "id": 1,
    "transaction_id": "txn_123456789",
    "type": "PIX",
    "amount": "100.50",
    "status": "PAID_OUT",
    "created_at": "2024-01-01T12:00:00Z"
  },
  "status": {
    "statusTransaction": "PAID_OUT",
    "paymentDate": "01/01/2024 12:30:00"
  }
}
Webhooks

Receba atualizações de status em tempo real através de webhooks.

WEBHOOK SUITPAY POST /webhook/suitpay
Payload Recebido:
{
  "idTransaction": "suitpay_123",
  "typeTransaction": "PIX",
  "statusTransaction": "PAID_OUT",
  "value": 100.50,
  "payerName": "João Silva",
  "payerTaxId": "12345678900",
  "paymentDate": "01/01/2024 12:30:00",
  "paymentCode": "EMV123456789",
  "requestNumber": "pedido-12345",
  "hash": "sha256_hash_validacao"
}
Importante: Valide sempre o hash SHA256 para garantir que o webhook veio da SuitPay.
Códigos de Status
Status Descrição
PENDINGAguardando pagamento
PAID_OUTPago com sucesso
CANCELEDCancelado
CHARGEBACKChargeback
EXPIREDExpirado
Exemplos de Código
JavaScript/Node.js
// Criar pagamento PIX
const response = await fetch('https://keygift.store/api/v1/payment/pix', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 100.50,
    customer_name: 'João Silva',
    customer_tax_id: '12345678900',
    customer_email: 'joao@email.com',
    request_number: 'pedido-12345'
  })
});

const data = await response.json();
console.log(data.payment_data.qrcode); // Base64 QR Code
PHP
$client = new GuzzleHttp\Client();

$response = $client->post('https://keygift.store/api/v1/payment/pix', [
    'json' => [
        'amount' => 100.50,
        'customer_name' => 'João Silva',
        'customer_tax_id' => '12345678900',
        'customer_email' => 'joao@email.com',
        'request_number' => 'pedido-12345'
    ]
]);

$data = json_decode($response->getBody(), true);
echo $data['payment_data']['qrcode'];
Suporte

Dúvidas sobre a integração? Entre em contato: