Documentacao

Integre USDC e Bitcoin Lightning no seu checkout.

WordFinance Pay cria cobrancas, exibe checkout hospedado com QR/deep link e notifica sua loja quando o pagamento e confirmado. USDC segue o modelo nao-custodial para a carteira Solana do lojista. Lightning usa onboarding e allowlist de merchants.

Baixar plugin WooCommerce Ver status publico Health direto do gateway Prompt integrador completo

URL base

https://wordfinance-gateway-production.up.railway.app

Para WooCommerce, cole esta URL no campo URL do Gateway do plugin.

WooCommerce

1. Instale

Envie a pasta/zip `wordfinance-pay` para o WordPress e ative o plugin.

2. Configure

Em WooCommerce > Pagamentos, cole a URL do gateway e sua carteira Solana.

3. Salve

O plugin registra automaticamente o Merchant ID.

4. Venda

O cliente escolhe Bitcoin & USDC e e redirecionado para a pagina de pagamento.

Registrar lojista

POST /api/gateway/merchant/register
Content-Type: application/json

{
  "name": "Minha loja",
  "solanaWallet": "carteira_solana_do_lojista",
  "lightningAddress": "lojista@dominio.com",
  "webhookUrl": "https://minhaloja.com/wc-api/wf_confirm",
  "platform": "woocommerce",
  "siteUrl": "https://minhaloja.com"
}

Criar cobranca

POST /api/gateway/charge
Content-Type: application/json

{
  "merchantId": "wf_merch_xxx",
  "amountBRL": 99.90,
  "description": "Pedido #123",
  "orderId": "123",
  "customerEmail": "cliente@email.com",
  "preferredMethod": "usdc",
  "webhookUrl": "https://minhaloja.com/wc-api/wf_confirm",
  "returnUrl": "https://minhaloja.com/obrigado"
}

Lightning: use "preferredMethod": "lightning". O merchant precisa estar aprovado na allowlist; enquanto aguarda, mantenha Lightning desabilitado e ofereca USDC.

Resposta

{
  "chargeId": "ch_xxx",
  "status": "pending",
  "paymentUrl": "https://wordfinance-gateway.../pay/ch_xxx",
  "deepLink": "wordfinance://pay?...",
  "totalUsdc": 18.54,
  "merchantUsdc": 18.35,
  "feeUsdc": 0.19
}

Em Lightning, a resposta inclui bolt11, sats, deepLink, paymentUrl e expiresAt.

Webhook enviado para a loja

{
  "chargeId": "ch_xxx",
  "orderId": "123",
  "status": "paid",
  "paymentMethod": "usdc",
  "amountBRL": 99.90,
  "totalUsdc": 18.54,
  "merchantId": "wf_merch_xxx",
  "provider": "wordfinance",
  "txSignature": "assinatura_solana"
}

O gateway pode enviar o header X-WordFinance-Signature. Valide o HMAC com o segredo provisionado no onboarding, usando o corpo bruto recebido. Antes do provisionamento, deixe o webhook vazio e consulte o status pelo backend. Persista eventId e processe cada evento uma unica vez.

Pixcoin (PIXC)

PIXC ainda nao e um metodo de /api/gateway/charge. Para aceitar PIXC, use uma transferencia SPL aprovada pela carteira do usuario e valide no seu backend o mint oficial, destino, valor e assinatura on-chain com idempotencia.

Nao envie preferredMethod: "pixc" ao gateway USDC/Lightning. Veja o contrato publico e o prompt de implementacao em Pixcoin e Torne-se parceiro.

Endpoints

Metodo	Rota	Uso
`GET`	`/api/gateway/health`	Status do gateway
`POST`	`/api/gateway/merchant/register`	Registrar lojista
`POST`	`/api/gateway/charge`	Criar cobranca
`GET`	`/api/gateway/charge/:chargeId`	Consultar cobranca
`GET`	`/pay/:chargeId`	Pagina de pagamento
`POST`	`/api/gateway/charge/:chargeId/check`	Verificar pagamento