Integre pagamentos PIX sem carregar a complexidade financeira.

O que você precisa

Para produção, sua integração precisa de apenas três credenciais/configurações.

Dois modelos oficiais de integração

Credenciais e base da API

Base URL: https://graffitpay.com/v1
Authorization: Bearer gpk_live_...
Content-Type: application/json
Idempotency-Key: pedido-1001

Para consultar o contrato dinâmico liberado para sua própria conta, use GET /v1/documentation.

A API Key identifica sua conta automaticamente. Não envie merchant_id. Use gpk_test_... apenas no ambiente TEST e gpk_live_... apenas em produção.

01 · DIRECT_SALES — loja, produto e serviço

No DIRECT_SALES, o comprador não precisa passar KYC por padrão para uma compra PIX comum.

Use este modelo quando sua aplicação só precisa cobrar e saber quando o pagamento terminou. Para uma compra PIX comum, o comprador não cria Customer e não passa pelo fluxo de KYC da Graffit. Em DIRECT_SALES, customer_id é opcional.

POST https://graffitpay.com/v1/payment_intents
Authorization: Bearer gpk_live_...
Idempotency-Key: pedido-1001
Content-Type: application/json

{
  "payment_method": "PIX",
  "amount_brl": 10.00,
  "reference": "pedido-1001",
  "payer": {
    "name": "Maria da Silva",
    "cpf": "52998224725",
    "email": "maria@exemplo.com",
    "phone": "+5567999999999"
  },
  "metadata": {
    "order_id": "1001"
  }
}

GET https://graffitpay.com/v1/payment_intents/pi_...

02 · CUSTOMER_BALANCES — cliente persistente + saldo separado

CUSTOMER_BALANCES usa KYC individual aplicável quando o fluxo daquele Customer exigir verificação.

Use quando cada usuário da sua plataforma precisa ficar vinculado a um Customer Graffit fixo. Crie o Customer uma vez e reutilize sempre o mesmo ID.

POST https://graffitpay.com/v1/customers
Authorization: Bearer gpk_live_...
Content-Type: application/json

{
  "display_name": "Maria da Silva",
  "email": "maria@exemplo.com",
  "account_type": "INDIVIDUAL",
  "customer_code": "usuario-123"
}

POST /v1/customers/:id/live/onboarding
GET  /v1/customers/:id/live/status?sync=true

POST /v1/payment_intents
Idempotency-Key: recarga-9001

{
  "customer_id": "cus_...",
  "payment_method": "PIX",
  "amount_brl": 100.00,
  "reference": "recarga-9001",
  "payer": {
    "name": "Maria da Silva",
    "cpf": "52998224725"
  }
}

GET /v1/customers/:id/balances

Resposta do Payment Intent e PIX

Ao criar ou consultar um Intent, use o status do próprio Payment Intent como estado principal da sua aplicação.

{
  "id": "pi_...",
  "object": "payment_intent",
  "mode": "live",
  "payment_method": "PIX",
  "amount_brl": 10,
  "status": "REQUIRES_PAYMENT",
  "reference": "pedido-1001",
  "payment": {
    "id": "pay_...",
    "status": "PIX_PENDING",
    "checkout_url": "https://graffitpay.com/checkout.html?t=...",
    "pix": {
      "mode": "live",
      "txid": "...",
      "br_code": "000201...",
      "status": "pending",
      "qr_url": "https://graffitpay.com/api/public/checkout/.../qr.png",
      "expires_at": "..."
    }
  }
}

Status que sua aplicação deve tratar

Webhook + HMAC

Configure a URL HTTPS e crie o Webhook Secret HMAC na aba API do Portal Parceiro. A Graffit envia os eventos automaticamente.

Headers enviados

X-Graffit-Event: payment.completed
X-Graffit-Event-Id: evt_...
X-Graffit-Timestamp: 178...
X-Graffit-Signature: <hex HMAC SHA-256>
X-Graffit-Webhook-Version: 1

Como validar a assinatura

signed_payload = timestamp + "." + RAW_REQUEST_BODY
expected = HMAC_SHA256(WEBHOOK_SECRET, signed_payload)

compare expected com X-Graffit-Signature usando comparação timing-safe

const crypto = require('crypto');

function validGraffitWebhook({ rawBody, timestamp, signature, secret }) {
  const age = Math.abs(Math.floor(Date.now()/1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(String(signature || ''), 'hex');
  const b = Buffer.from(expected, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Payload final real

{
  "id": "evt_...",
  "type": "payment.completed",
  "created_at": "...",
  "data": {
    "payment": {
      "id": "pay_...",
      "payment_intent_id": "pi_...",
      "reference": "pedido-1001",
      "amount_brl": 10,
      "status": "COMPLETED",
      "intent_status": "SUCCEEDED",
      "payment_method": "PIX",
      "payer": {
        "name": "Maria da Silva",
        "cpf": "52998224725",
        "email": "maria@exemplo.com",
        "phone": "+5567999999999"
      }
    }
  }
}

Responda HTTP 2xx rapidamente depois de validar/persistir o evento. Faça tarefas demoradas em fila/background. Se seu endpoint falhar, a Graffit tenta entregar novamente.

Idempotência — evite cobrança duplicada

Use uma chave única e estável para cada tentativa lógica de pagamento. Se sua aplicação sofrer timeout ou perder a resposta do POST, repita o mesmo request com a mesma chave.

Idempotency-Key: pedido-1001

Não gere uma nova chave só porque houve timeout. A mesma chave com payload diferente retorna conflito.

Erros que sua integração deve tratar

Erros usam JSON com error e code. Em erros transitórios, consulte o Payment Intent antes de criar uma nova cobrança.

TEST — valide sem dinheiro real

Na aba API do Portal Parceiro você pode criar uma TEST API Key, simular pagamento e enviar eventos de webhook assinados. Use TEST para validar sua integração antes de trocar para a chave LIVE.