Conecta una pasarela de pago personalizada

El proveedor de pago “Otro” permite que tu tienda cobre a través de tu propia pasarela de pago. En Configuración de tienda le das a MallBasket dos cosas: un endpoint de URL de pago (tu servidor) y un secreto compartido. MallBasket firma una solicitud a tu endpoint para obtener un enlace de pago, y tu pasarela firma un webhook de vuelta a MallBasket cuando el pago termina. Es una integración para desarrolladores.

Configúralo en la app

En Configuración de tienda → Pagos en línea (Habilitado) → Avanzado → Proveedor de Checkout, elige “Otro” e introduce tu endpoint de URL de pago y tu secreto compartido (sirve para firmar cada mensaje en ambos sentidos). Mantén el secreto en privado: cualquiera que lo tenga puede autorizar pedidos.

1. MallBasket te pide una URL de pago

Cuando un comprador paga, MallBasket envía un POST firmado a tu endpoint. Verifica la firma, crea en tu lado una sesión de pago por exactamente este importe y esta moneda, y devuelve su URL.

POST → tu endpoint · cuerpo (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" }
}

Cabecera

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

Devuelve la URL de la página de pago alojada. MallBasket la abre para el comprador. (También se aceptan data.paymentURL y url.)

Tu respuesta · 200 (application/json)

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

2. Tu pasarela avisa a MallBasket (webhook)

Cuando el comprador pague, envía por POST un mensaje firmado al webhookUrl que te enviamos. MallBasket verifica la firma, comprueba que el importe coincide con el pedido y marca el pedido como pagado. Envía el estado “success” solo cuando el pago se haya liquidado de verdad.

POST → webhookUrl · cuerpo (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
}

Cabecera

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

3. Firma (en ambos sentidos)

Cada solicitud lleva una cabecera x-mb-signature: el HMAC-SHA256 en hexadecimal del cuerpo EN BRUTO de la solicitud, calculado con tu secreto compartido. Calcúlalo sobre los bytes exactos que se envían y verifica las solicitudes entrantes sobre los bytes en bruto que recibes (no sobre un objeto vuelto a serializar).

// 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>

Verifica una solicitud entrante

// 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 || "")
  );
}

Reglas y garantías

Los importes deben coincidir: el importe del webhook debe ser igual al que envió MallBasket, en la misma moneda, o se rechaza.
Devuelve el transactionId tal cual. MallBasket lo usa para asociar el pago con el pedido.
MallBasket autentica tu webhook solo con el secreto de tu tienda; otra tienda no puede completar tus pedidos.
La finalización es idempotente: puedes reintentar el webhook sin riesgo. MallBasket devuelve 2xx una vez registrado el pedido; reintenta ante cualquier respuesta que no sea 2xx.
Nunca envíes el estado “success” antes de que el dinero se haya capturado realmente.