Una API para todos tus pagos por medio de Punto de Pago

curl -X POST https://sandbox.puntodepago.com.co/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://sandbox.puntodepago.com.co/v1/payments \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

curl -X GET https://sandbox.puntodepago.com.co/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://sandbox.puntodepago.com.co/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://sandbox.puntodepago.com.co/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://sandbox.puntodepago.com.co/v1/payments/{id}/cancel \
  -H "Authorization: Bearer $ACCESS_TOKEN"

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

curl -X GET https://sandbox.puntodepago.com.co/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 GET https://sandbox.puntodepago.com.co/api/banks?country=COL&rail_id=PSE \
  -H "Authorization: Bearer $ACCESS_TOKEN"

[
  { "id": "9957817c-f17e-472b-b531-e3d1490bf757", "name": "BANCOLOMBIA" },
  { "id": "3f2b91ad-5c04-4e7a-9f18-2d6c8a1e4b03", "name": "DAVIVIENDA" }
]

curl -X POST https://sandbox.puntodepago.com.co/v1/payments/intents \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "order_id": "orden-83790",
  "amount": 50000,
  "currency": "COP",
  "rail_id": "NEQUI",
  "rail_type": "WALLET",
  "description": "Orden 83790 - mitienda.com",
  "customer": { "phone_number": "3001234567" }
}

{
  "order_id": "orden-83791",
  "amount": 200000,
  "currency": "COP",
  "rail_id": "PSE",
  "rail_type": "BANK_TRANSFER",
  "return_url": "https://mitienda.com/pagos/resultado",
  "customer": {
    "bank_id": "9957817c-f17e-472b-b531-e3d1490bf757",
    "document": "1234567890",
    "document_type": "CC",
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan@ejemplo.com"
  }
}

{
  "order_id": "orden-83792",
  "amount": 150000,
  "currency": "COP",
  "rail_id": "BRE_B",
  "rail_type": "BANK_TRANSFER"
}

{
  "payment_id": "pay-xxxxxxxxxxxx",
  "transaction": {
    "id": "trx-xxxxxxxxxxxx",
    "type": "PURCHASE",
    "status": "IN_PROGRESS",
    "status_detail": "PENDING",
    "amount": 200000
  },
  "rail": {
    "id": "PSE",
    "payment_link": "https://pse.onepay.com/pay/session-abc123"
  }
}

{
  "payment_id": "pay-xxxxxxxxxxxx",
  "transaction": { "status": "IN_PROGRESS", "status_detail": "PENDING", "amount": 150000 },
  "rail": {
    "id": "BRE_B",
    "alias": "@STORE7X",
    "qr": { "image": "data:image/png;base64,...", "content": "00020101021226..." },
    "payment_link": "https://pay.breb.com.co/t/abc123"
  }
}

{
  "id": "evt-xxxxxxxxxxxx",
  "type": "payment.purchase.succeeded",
  "time": "2025-10-15T15:10:00Z",
  "data": {
    "payment": {
      "id": "pay-xxxxxxxxxxxx",
      "currency": "COP",
      "current_amount": 200000,
      "transaction": { "status": "APPROVED", "status_detail": "SUCCESS" }
    }
  }
}

curl -X POST https://sandbox.puntodepago.com.co/v1/payments/intents \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "order_id": "orden-83793",
  "amount": 75000,
  "currency": "COP",
  "rail_id": "DAVIPLATA",
  "rail_type": "WALLET",
  "customer": {
    "phone_number": "3001234567",
    "document": "1234567890",
    "document_type": "CC"
  }
}
'

curl -X POST https://sandbox.puntodepago.com.co/v1/payments/intents/{payment_id}/confirm \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "otp": "123456"
}
'

curl -X POST https://sandbox.puntodepago.com.co/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://sandbox.puntodepago.com.co/v1/links/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "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"
}