Conecte um gateway de pagamento personalizado

O provedor de checkout “Outro” permite que sua loja receba pagamentos pelo seu próprio gateway de pagamento. Na Configuração da Loja, você fornece duas coisas ao MallBasket: um endpoint de URL de pagamento (seu servidor) e um segredo compartilhado. O MallBasket envia uma requisição assinada ao seu endpoint para obter um link de pagamento, e seu gateway envia um webhook assinado de volta ao MallBasket quando o pagamento é concluído. Esta é uma integração para desenvolvedores.

Configure no app

Em Configuração da Loja → Pagamentos Online (Ativado) → Avançado → Provedor de Checkout, escolha “Outro” e informe seu endpoint de URL de pagamento e seu segredo compartilhado (usado para assinar cada mensagem nos dois sentidos). Mantenha o segredo em sigilo: qualquer pessoa que o tenha pode autorizar pedidos.

1. O MallBasket solicita uma URL de pagamento a você

Quando um comprador finaliza a compra, o MallBasket envia um POST assinado ao seu endpoint. Verifique a assinatura, crie do seu lado uma sessão de pagamento com exatamente este valor e esta moeda e retorne a URL dela.

POST → seu endpoint · corpo (application/json)

{
  "orderId": "6f2a…",              // your MallBasket order id
  "transactionId": "o_6f2a…",     // echo this back in the webhook
  "storeId": "store_abc",
  "userId": "user_123",
  "amount": "12.50",              // decimal string, charge exactly this
  "currency": "USD",
  "email": "buyer@example.com",
  "webhookUrl": "https://europe-west3-mallbasket.cloudfunctions.net/otherWebhook",
  "successUrl": "https://www.mallbasket.com/en/payment/complete?orderId=6f2a…&status=success",
  "cancelUrl": "https://www.mallbasket.com/en/payment/complete?orderId=6f2a…&status=cancelled",
  "nonce": "b1d9…",
  "metadata": { "itemId": "item_1" }
}

Cabeçalho

x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

Retorne a URL da página de pagamento hospedada. O MallBasket a abre para o comprador. (data.paymentURL e url também são aceitos.)

Sua resposta · 200 (application/json)

{
  "paymentURL": "https://your-gateway.example.com/pay/abc123"
}

2. Seu gateway notifica o MallBasket (webhook)

Depois que o comprador pagar, envie por POST uma mensagem assinada para o webhookUrl que enviamos a você. O MallBasket verifica a assinatura, confirma que o valor corresponde ao pedido e marca o pedido como pago. Envie o status “success” somente depois que o pagamento tiver sido realmente liquidado.

POST → webhookUrl · corpo (application/json)

{
  "orderId": "6f2a…",           // same order id
  "transactionId": "o_6f2a…",  // the transactionId we sent you
  "status": "success",          // only send this once payment truly succeeded
  "amount": "12.50",            // must equal the amount we sent
  "currency": "USD",
  "reference": "your-gateway-txn-id"   // optional, shown on the receipt
}

Cabeçalho

x-mb-signature: <hex hmac-sha256 of the raw body with your secret>

3. Assinatura (nos dois sentidos)

Toda requisição traz um cabeçalho x-mb-signature: o HMAC-SHA256 em hexadecimal do corpo BRUTO da requisição, calculado com seu segredo compartilhado. Calcule-o sobre os bytes exatos enviados e verifique as requisições recebidas sobre os bytes brutos que chegam (não sobre um objeto reserializado).

// Node.js: sign the EXACT raw body bytes you are about to send
const crypto = require("crypto");

const rawBody = JSON.stringify(payload);          // the bytes you POST
const signature = crypto
  .createHmac("sha256", MALLBASKET_SECRET)        // your restricted key
  .update(rawBody, "utf8")
  .digest("hex");

// send header:  x-mb-signature: <signature>

Verifique uma requisição recebida

// Node.js: verify a request MallBasket sent to your endpoint
const crypto = require("crypto");

function verify(rawBody, headerSig, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")                        // RAW bytes, not re-parsed JSON
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(headerSig || "")
  );
}

Regras e garantias

Os valores devem coincidir: o valor do webhook deve ser igual ao valor enviado pelo MallBasket, na mesma moeda, ou será rejeitado.
Devolva o transactionId exatamente como recebido. É por ele que o MallBasket associa o pagamento ao pedido.
O MallBasket autentica seu webhook apenas com o segredo da sua loja; outra loja não consegue concluir seus pedidos.
A finalização é idempotente: é seguro reenviar o webhook. O MallBasket retorna 2xx assim que o pedido é registrado; tente novamente em qualquer resposta que não seja 2xx.
Nunca envie o status “success” antes de o dinheiro ter sido realmente capturado.