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.

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.

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://api.ionea.io/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": "https://assets.key2pays.com/methods/spei.png",
      "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",
      "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
    }
  ]
}