Endpoints

List payment methods

GET/api/v1/payment-methods

List every payment rail the shop can accept — one entry per retailer / bank / native method.

Listing ↔ POST contract. Every entry returned here with routable: true is guaranteed chargeable via POST /api/v1/payments with the same paymentMethodId. If a POST against a listed, routable id ever returns cascade_exhausted with reason: "no_provider_for_method_region", that is a transient cache mismatch on our side — retry once immediately (the cascade engine force-reloads its provider state on this exact failure mode, so the second attempt sees the same truth your listing did). If retry persists, the response will tell you whether the paymentMethodId is actually enabled for your shop or whether you need to contact Key2Pay support. Do not hardcode 4-digit codes from external documentation — always pull them from your own listing.

Method logos (pay-in & pay-out). Every method carries iconUrl (alias logoUrl) — an absolute, public, cacheableURL to that rail's brand icon, hosted by us at /api/payment-method-logo/<key>. Download it or render it directly (<img src={iconUrl}>); it never expires and always resolves (a custom logo when the operator uploaded one, otherwise a generic category icon). The SAME field rides on the charge response (POST /payments → logoUrl/iconUrl + paymentMethod + paymentMethodName) so you can show the exact routed rail's icon in your own checkout, and on the payout side (GET /me/payout/methods and POST /me/payout/send). Logos are assigned in real time — the URL always reflects the operator's latest upload.

GET/api/v1/payment-methodsany key

Returns every distinct payment method enabled for the authenticated shop — one row per retailer, bank or native rail. SPEI, OXXO, Walmart, 7-Eleven, BBVA, Scotiabank all appear as separate entries with their own 4-digit `paymentMethodId`. The id is OURS (assigned starting at 1001, persisted server-side, never reused) and survives provider rotations: when we swap the upstream behind the scenes your stored id keeps working. The exact same field name is used on every surface: read `paymentMethodId` here, pass it back as `paymentMethodId` on POST /api/v1/payments, and the transaction record returned by GET /api/v1/payments echoes it back so the round-trip is fully visible. Use the `routable: boolean` flag (not `enabled`/`online`) to decide whether to surface a method in checkout — it returns `true` only when a real processor is configured for that exact retailer right now. Every entry also carries `iconUrl` — an absolute, public, cacheable URL to the method's icon hosted by us. Render it directly (`<img src={iconUrl}>`); it ALWAYS resolves (a custom logo when we have one, otherwise a generic category icon for the channel — bank, cash or card), so you never get a null or a broken image. Prefer `iconUrl` over the legacy relative `imageUrl`.

Body parameters

countrystring
ISO-2 or ISO-3 — restrict to one country (e.g. MX, BRA).
channelstring
ONLINE | CASH | CREDIT_CARD.
methodstring
Internal slug (e.g. pix, spei, oxxo, voucher, bank_transfer, card).

Request

curl "https://sandbox.key2pay.ai/api/v1/payment-methods?country=MX" \
  -H "Authorization: Bearer sk_test_51N8mP...exampleK3Y"

Response

{
  "shop": { "id": "SHP-MP1STV8W-832A", "name": "Tropical Oficina 1" },
  "environment": "sandbox",
  "filters": { "country": "MX", "channel": null, "method": null },
  "count": 6,
  "totalAvailable": 24,
  "routableCount": 6,
  "methods": [
    {
      "paymentMethodId": "1001",
      "method": "spei",
      "methodLabel": "SPEI",
      "name": "SPEI",
      "country": "MX",
      "countryIso3": "MEX",
      "channel": "ONLINE",
      "imageUrl": "/api/payment-method-logo/spei__mex?v=2026-06-30T00:00:00.000Z",
      "iconUrl": "https://api.key2pays.com/api/payment-method-logo/spei__mex?v=2026-06-30T00:00:00.000Z",
      "currencies": ["MXN", "USD"],
      "currencyLimits": [
        { "currency": "MXN", "min": 20, "max": 1018099.36 },
        { "currency": "USD", "min": 1,  "max": 50000 }
      ],
      "minTxUsd": null,
      "maxTxUsd": null,
      "fee": { "percent": 1, "flat": 0, "currency": "MXN" },
      "enabled": true, "online": true, "routable": true, "unroutableReason": null
    },
    {
      "paymentMethodId": "1002",
      "method": "oxxo",
      "methodLabel": "OXXO",
      "name": "OXXO",
      "country": "MX", "countryIso3": "MEX",
      "channel": "CASH",
      "iconUrl": "https://api.key2pays.com/checkout/logos/cat-cash.svg",
      "currencies": ["MXN"],
      "currencyLimits": [ { "currency": "MXN", "min": 50, "max": 10000 } ],
      "fee": { "percent": 3.0, "flat": 0, "currency": "MXN" },
      "enabled": true, "online": true, "routable": true, "unroutableReason": null
    },
    {
      "paymentMethodId": "1003",
      "method": "voucher",
      "methodLabel": "Cash Voucher",
      "name": "Walmart",
      "country": "MX", "countryIso3": "MEX",
      "channel": "CASH",
      "fee": { "percent": 3.5, "flat": 0, "currency": "MXN" },
      "enabled": true, "online": true, "routable": true, "unroutableReason": null
    },
    {
      "paymentMethodId": "1004",
      "method": "voucher",
      "methodLabel": "Cash Voucher",
      "name": "7-Eleven",
      "country": "MX", "countryIso3": "MEX",
      "channel": "CASH",
      "fee": { "percent": 3.5, "flat": 0, "currency": "MXN" },
      "enabled": true, "online": true, "routable": true, "unroutableReason": null
    },
    {
      "paymentMethodId": "1005",
      "method": "bank_transfer",
      "methodLabel": "Bank Transfer",
      "name": "BBVA",
      "country": "MX", "countryIso3": "MEX",
      "channel": "ONLINE",
      "fee": { "percent": 2.5, "flat": 0, "currency": "MXN" },
      "enabled": true, "online": true, "routable": true, "unroutableReason": null
    },
    {
      "paymentMethodId": "1006",
      "method": "bank_transfer",
      "methodLabel": "Bank Transfer",
      "name": "Scotiabank",
      "country": "MX", "countryIso3": "MEX",
      "channel": "ONLINE",
      "fee": { "percent": 2.5, "flat": 0, "currency": "MXN" },
      "enabled": true, "online": true, "routable": true, "unroutableReason": null
    }
  ]
}