Una API para todos tus pagos

curl -X POST https://sandbox.payty.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": 43200
}

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

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

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

curl -X GET https://sandbox.payty.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://sandbox.payty.com/v1/links \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "type": "payment",
  "expires_in": 3600,
  "payment_methods_source": "merchant",
  "data": {
    "amount": {
      "value": 25000,
      "currency": "COP"
    },
    "description": "Orden #12345",
    "redirect_url": "https://mitienda.com/gracias",
    "cancel_url": "https://mitienda.com/carrito"
  }
}
'

{
  "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.payty.com/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);
}

curl -X POST https://sandbox.payty.com/v1/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '
{
  "id": "usr-mitienda-00123",
  "metadata": {
    "email": "ana@example.com"
  }
}
'

{
  "id": "usr-mitienda-00123",
  "metadata": { "email": "ana@example.com" },
  "instruments": [],
  "created_at": "2026-09-18T14:02:11Z",
  "updated_at": "2026-09-18T14:02:11Z"
}

curl -X GET https://sandbox.payty.com/v1/users/{id} \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "id": "usr-mitienda-00123",
  "metadata": { "email": "ana@example.com" },
  "instruments": [],
  "created_at": "2026-09-18T14:02:11Z",
  "updated_at": "2026-09-18T14:02:11Z"
}

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