Procobro

curl -X POST https://quickconnect-sandbox.pro-cobro.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '
{
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>"
}
'

{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 3600
}

curl -X POST https://quickconnect-sandbox.pro-cobro.com/v1/payments \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

curl -X GET https://quickconnect-sandbox.pro-cobro.com/v1/payments/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "pay-dak3bkvudovnsbia9pj0",
  "intent": "authorization",
  "status": "REFUND_CAPTURED",
  "status_detail": "SUCCESS",
  "currency": "USD",
  "country": "URY",
  "initial_amount": 100,
  "current_amount": 0,
  "created_at": "2026-09-14T17:58:43.830183Z",
  "external_client_trace_id": "orden-12345",
  "transactions": [ { "id": "trx-…", "type": "AUTHORIZATION", "status": "APPROVED" } ]
}

curl -X GET https://quickconnect-sandbox.pro-cobro.com/v1/payments?page=1&page_size=50 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [ { "id": "pay-…", "status": "CAPTURED" } ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total": 94,
    "total_found": 94
  }
}

curl -X POST https://quickconnect-sandbox.pro-cobro.com/v1/refunds \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "payment_id": "pay-cu94vq1n8ql8u3v469gg",
  "amount": 1000,
  "currency": "COP"
}
'

curl -X POST https://quickconnect-sandbox.pro-cobro.com/v1/payments/{id}/cancel \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -X POST https://quickconnect-sandbox.pro-cobro.com/v1/payments/{id}/capture \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -X GET https://quickconnect-sandbox.pro-cobro.com/v1/chargebacks \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    {
      "id": "cbk-dak2l26kfdel09fpl9rg",
      "payment_id": "pay-dahebpuuf97kkem2n3fg",
      "transaction_id": "trx-dahebpuuf97kkem2n3f0",
      "status": "PENDING",
      "reason_id": "10_4",
      "reason_description": "Otros Fraudes – Ambiente de Tarjeta Ausente",
      "amount": 100,
      "currency": "URY",
      "created_at": "2026-09-14T17:10:32.26776Z",
      "expires_at": "2026-10-04T05:00:00Z"
    }
  ],
  "pagination": { "page": 1, "page_size": 25, "total": 3, "total_found": 3 }
}

curl -X POST https://quickconnect-sandbox.pro-cobro.com/v1/links \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "type": "payment",
  "expires_in": 3600,
  "data": {
    "amount": {
      "value": 25000,
      "currency": "COP"
    },
    "description": "Orden #12345",
    "payment_methods_source": "merchant",
    "success_url": "https://mitienda.com/success",
    "cancel_url": "https://mitienda.com/cancel",
    "error_url": "https://mitienda.com/error"
  }
}
'

{
  "id": "lnk-a1b2c3d4",
  "url": "https://checkout.akua.la/links/lnk-a1b2c3d4",
  "status": "created",
  "expires_at": "2026-07-02T14:00:00Z"
}

curl -X GET https://quickconnect-sandbox.pro-cobro.com/v1/links/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -X POST https://quickconnect-sandbox.pro-cobro.com/v1/instruments/collect-sessions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "trace_id": "orden-83779",
  "appearance": {
    "locale": "es"
  }
}
'

{
  "id": "ise-davvj6sv88n403qvlp70jicabrmbtv3p5gep",
  "url": "https://sandbox.akua.la/v1/pci-views/collect/ise-davvj6…#s=<capability>",
  "status": "OPEN",
  "expires_at": "2026-10-02T20:37:11Z",
  "view_version": "1.2.0",
  "trace_id": "orden-83779"
}

// Tu base URL. Sale del onboarding, no se hardcodea por ambiente.
const BASE = "https://quickconnect-sandbox.pro-cobro.com";

// El browser llama a ESTA ruta, no a la API de pagos.
app.post("/api/session", async (req, res) => {
  const token = await getMerchantToken();   // cacheado, credencial mer-

  const r = await fetch(`${BASE}/v1/instruments/collect-sessions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ trace_id: order.id, appearance: { locale: "es" } }),
  });
  const s = await r.json();

  await guardarSesion(order.id, s.id);       // el id queda de tu lado
  res.json({ url: s.url });                 // al browser va SOLO la url
});

{
  "trace_id": "orden-83779",
  "appearance": {
    "layout": "two-row",
    "labels": "floating",
    "locale": "es",
    "show_holder": true,
    "submit_button": { "mode": "external" },
    "placeholders": {
      "number": "1234 1234 1234 1234",
      "expiry": "MM/AA",
      "cvc": "CVC",
      "holder": "Nombre en la tarjeta"
    },
    "variables": {
      "colorBackground": "#1d232a",
      "colorText": "#e6e9ed",
      "colorBorder": "#7d8b99",
      "colorPlaceholder": "#98a3af",
      "colorPrimary": "#5aa7f0",
      "colorDanger": "#ff8b8f",
      "borderRadius": "8px",
      "fontSizeBase": "16px",
      "spacingUnit": "8px",
      "fontFamily": "system"
    },
    "styles": {
      "input": {
        "base": { "font-size": "18px", "padding": "12px 14px", "border-width": "1px", "letter-spacing": "1px" },
        "focus": { "border-color": "#5aa7f0" },
        "invalid": { "border-color": "#ff8b8f" }
      },
      "label": { "base": { "font-weight": 600, "text-transform": "uppercase" } },
      "button": { "base": { "border-radius": "12px" } }
    }
  }
}

{
  "styles": {
    "input": {
      "base": { "font-size": "18px", "padding": "12px 14px" },
      "focus": { "border-color": "#5aa7f0" },
      "invalid": { "border-color": "#ff8b8f" }
    },
    "label": { "base": { "font-weight": 600, "text-transform": "uppercase" } }
  }
}

<script src="https://sandbox.akua.la/v1/pci-views/1.2.0/embed.js"
        integrity="sha384-PWjrkxk2wTdMffNYwDW4Ir0+WKiANjvdEwbTVvzZfYVXn7dCawHNSfkGrfwSYfol"
        crossorigin="anonymous"></script>

<form id="checkout">
  <input name="email" type="email" required>
  <div id="card"></div>
  <button type="submit">Pagar</button>
</form>

const card = AkuaCardEntry.mount("#card", {
  // Tu endpoint llama al paso 2 y devuelve { url }.
  // Se vuelve a llamar solo si la sesion vence.
  session: async () => (await fetch("/api/session", { method: "POST" })).json(),
});

const form = document.getElementById("checkout");
form.onsubmit = card.handleSubmit(async ({ sessionId }) => {
  // La tarjeta ya esta en la boveda. Mandas solo el id de sesion:
  // tu backend hace los pasos 4 y 5.
  const r = await fetch("/api/pay", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ sessionId }),
  });
  const out = await r.json();
  if (!r.ok) throw new Error("declined");
  location.assign(`/resultado/${out.order_id}`);
});

card.on("error", (e) => console.warn(e.code, e.source, e.retryable));

<script type="module"
        src="https://sandbox.akua.la/v1/pci-views/1.2.0/embed.mjs"
        integrity="sha384-JQyHgvWEyxR9dSCYmKI9MGzQMH3DXZxl/UBRKtsoaAq8n/3HaDyDIPeYsclJ/5wW"
        crossorigin="anonymous"></script>

curl -X GET https://quickconnect-sandbox.pro-cobro.com/v1/instruments/collect-sessions/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "ise-davvj6…",
  "status": "COMPLETED",
  "trace_id": "orden-83779",
  "merchant_id": "mer-d6g518rbl6sg4fe3a7b0",
  "instrument": {
    "id": "ins-dacercdni7pdrioheibg",
    "type": "CARD",
    "card": {
      "last_four_digits": "1111",
      "expiration_month": "12",
      "expiration_year": "30",
      "bin_data": { "card_brand": "VISA", "card_type": "DEBIT" }
    }
  }
}

curl -X POST https://quickconnect-sandbox.pro-cobro.com/v1/payments/authorizations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "instrument": {
    "id": "ins-dacercdni7pdrioheibg"
  },
  "amount": {
    "value": "1000",
    "currency": "USD"
  },
  "intent": "authorization",
  "entry_mode": "not-present",
  "initiator": "customer",
  "order_type": "purchase",
  "capture": {
    "mode": "AUTOMATIC"
  },
  "installments": {
    "quantity": 12
  },
  "trace_id": "orden-83779"
}
'

{
  "payment_id": "pay-davvj781lhpi4eppkbt0",
  "instrument_id": "ins-dacercdni7pdrioheibg",
  "response_code": "00",
  "response_code_description": "Approval and completed successfully",
  "transaction": { "id": "trx-…", "type": "AUTHORIZATION", "status": "APPROVED" }
}

// Mismo BASE que en /api/session.
const BASE = "https://quickconnect-sandbox.pro-cobro.com";

// El browser manda { sessionId } y nada mas. El monto sale de TU pedido.
app.post("/api/pay", async (req, res) => {
  const { sessionId } = req.body;
  const order = await buscarPedidoPorSesion(sessionId);
  const token = await getMerchantToken();
  const h = { Authorization: `Bearer ${token}` };

  // 1. Leer la sesion: de aca sale el instrumento.
  const s = await (await fetch(
    `${BASE}/v1/instruments/collect-sessions/${sessionId}`, { headers: h }
  )).json();
  if (s.status !== "COMPLETED") return res.status(409).json({ error: "sesion incompleta" });

  // 2. Cobrar. Una Idempotency-Key por intento, guardada con el pedido.
  const r = await fetch(`${BASE}/v1/payments/authorizations`, {
    method: "POST",
    headers: { ...h, "Idempotency-Key": order.payKey, "Content-Type": "application/json" },
    body: JSON.stringify({
      instrument: { id: s.instrument.id },
      amount: { value: order.amountMinor, currency: order.currency },
      intent: "authorization",
      entry_mode: "not-present",
      initiator: "customer",
      order_type: "purchase",
      capture: { mode: "AUTOMATIC" },
      trace_id: order.id,
    }),
  });

  const out = await r.json();
  res.status(r.status).json({ order_id: order.id, payment_id: out.payment_id });
});

{
  "type": "payment.capture.cleared",
  "data": {
    "trace_id": "order-34324366",
    "payment_id": "pay-d07u8e218e1elk12b92g",
    "transaction_id": "trx-d0gv1122dpo29a8d7l4g"
  }
}

POST /webhooks HTTP/1.1
Content-Type: application/json
User-Agent: akua-webhooks/1.0
akua-wh-id: msg_p5jXN8AQM9LWM0D4loKWxJek
akua-wh-timestamp: 1614265330
akua-wh-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

{"type":"payment.authorization.processed","data":{"trace_id":"order-34324366","payment_id":"pay-d07u8e218e1elk12b92g","transaction_id":"trx-d0gv1122dpo29a8d7l4g"}}

import crypto from "crypto";

const TOLERANCIA = 5 * 60;

export function verificarFirma(secret, headers, rawBody) {
  const id = headers["akua-wh-id"];
  const ts = headers["akua-wh-timestamp"];
  const firmas = headers["akua-wh-signature"];
  if (!id || !ts || !firmas) return false;

  // Ventana temporal, contra ataques de repeticion.
  if (Math.abs(Math.floor(Date.now() / 1000) - parseInt(ts, 10)) > TOLERANCIA) {
    return false;
  }

  const clave = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const esperada = crypto
    .createHmac("sha256", clave)
    .update(`${id}.${ts}.${rawBody}`)
    .digest();

  // Comparacion en tiempo constante contra cada firma v1.
  return firmas
    .split(" ")
    .filter((p) => p.startsWith("v1,"))
    .map((p) => Buffer.from(p.slice(3), "base64"))
    .some((f) => f.length === esperada.length && crypto.timingSafeEqual(f, esperada));
}

async function reconciliar(paymentId) {
  const pago = await api.get(`/v1/payments/${paymentId}`);

  // La transaccion mas reciente marca hasta donde llega esta foto del pago.
  const marca = pago.transactions.map((t) => t.timestamp).sort().at(-1);

  // UPDATE ... WHERE marca_aplicada < $marca. Una foto vieja no pisa una nueva.
  await guardarSiEsMasNuevo(paymentId, pago.status, marca);
}

{
  "error_code": "resource_not_found",
  "error_type": "not_found",
  "message": "payment not found",
  "trace_id": "req-dampr99ma4dqhvj1d1p0"
}