Customer-Payment-Methods-v2

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/revolut/main/json-schema/revolut-customer-payment-methods-v2-schema.json",
  "title": "Customer-Payment-Methods-v2",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/revolut-customers-api-openapi.yml#/components/schemas/Customer-Payment-Methods-v2",
  "type": "object",
  "required": [
    "payment_methods"
  ],
  "properties": {
    "payment_methods": {
      "type": "array",
      "description": "Saved payment methods associated with this customer. Each entry represents a\npayment method authorised for future charges. Two types are supported: `card`\n(with full card details) and `revolut_pay` (covers both card-backed and\naccount-to-account Revolut Pay variants). Use the `type` field on each item\nto identify the variant.",
      "items": {
        "$ref": "#/$defs/Payment-Method-v4"
      }
    }
  },
  "$defs": {
    "Billing-Address": {
      "title": "Billing address",
      "type": "object",
      "description": "The billing address associated with the payment method.",
      "properties": {
        "street_line_1": {
          "type": "string",
          "description": "Primary address line.",
          "maxLength": 100
        },
        "street_line_2": {
          "type": "string",
          "description": "Secondary address line, such as floor and apartment number.",
          "maxLength": 100
        },
        "region": {
          "type": "string",
          "description": "State or province of the address.",
          "maxLength": 100
        },
        "city": {
          "type": "string",
          "description": "City of the address.",
          "maxLength": 100
        },
        "country_code": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "ISO 2-letter country code.",
          "minLength": 2,
          "maxLength": 2
        },
        "postcode": {
          "type": "string",
          "description": "Postal code of the address.",
          "maxLength": 100
        }
      },
      "required": [
        "country_code",
        "postcode"
      ]
    },
    "Card-Bin": {
      "type": "string",
      "description": "The BIN (Bank Identification Number) of the payment card, typically the first 6-8 digits."
    },
    "Card-Brand-v2": {
      "type": "string",
      "description": "The brand of the payment card.",
      "enum": [
        "visa",
        "mastercard",
        "american_express"
      ]
    },
    "Card-Expiry-Month": {
      "type": "integer",
      "description": "The expiry month of the payment card."
    },
    "Card-Expiry-Year": {
      "type": "integer",
      "description": "The expiry year of the payment card."
    },
    "Card-Funding-v2": {
      "type": "string",
      "description": "The funding type of the payment card.",
      "enum": [
        "debit",
        "credit",
        "prepaid"
      ]
    },
    "Card-Issuer": {
      "type": "string",
      "description": "The name of the card-issuing bank or institution."
    },
    "Card-Issuer-Country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "The ISO 3166-1 alpha-2 country code of the country where the payment card was issued."
    },
    "Card-Last-Four": {
      "type": "string",
      "minLength": 4,
      "maxLength": 4,
      "description": "The last four digits of the payment card number."
    },
    "Card-v2": {
      "title": "Card payment method",
      "type": "object",
      "description": "A saved card payment method.\n\n:::info\nThe `checks` object (3DS, CVV, address verification) is not included as it is specific to the transactional payment context.\n:::",
      "properties": {
        "id": {
          "$ref": "#/$defs/Payment-Method-Id"
        },
        "type": {
          "$ref": "#/$defs/Payment-Method-Type-v2"
        },
        "saved_for": {
          "$ref": "#/$defs/Saved-For"
        },
        "created_at": {
          "$ref": "#/$defs/Payment-Method-Created-At"
        },
        "bin": {
          "$ref": "#/$defs/Card-Bin"
        },
        "last_four": {
          "$ref": "#/$defs/Card-Last-Four"
        },
        "expiry_month": {
          "$ref": "#/$defs/Card-Expiry-Month"
        },
        "expiry_year": {
          "$ref": "#/$defs/Card-Expiry-Year"
        },
        "cardholder_name": {
          "$ref": "#/$defs/Cardholder-Name"
        },
        "brand": {
          "$ref": "#/$defs/Card-Brand-v2"
        },
        "funding": {
          "$ref": "#/$defs/Card-Funding-v2"
        },
        "issuer": {
          "$ref": "#/$defs/Card-Issuer"
        },
        "issuer_country": {
          "$ref": "#/$defs/Card-Issuer-Country"
        },
        "billing_address": {
          "$ref": "#/$defs/Billing-Address"
        },
        "terminal_hardware_id": {
          "$ref": "#/$defs/Terminal-Hardware-Id"
        }
      },
      "required": [
        "id",
        "type",
        "created_at"
      ]
    },
    "Cardholder-Name": {
      "type": "string",
      "description": "The name of the cardholder as it appears on the card."
    },
    "Payment-Method-Created-At": {
      "type": "string",
      "format": "date-time",
      "description": "The date and time the payment method was added."
    },
    "Payment-Method-Id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for the payment method."
    },
    "Payment-Method-Type-v2": {
      "type": "string",
      "description": "The type of the payment method.",
      "enum": [
        "card",
        "revolut_pay",
        "sepa_direct_debit"
      ]
    },
    "Payment-Method-v4": {
      "title": "Payment method",
      "description": "A saved payment method on a customer profile.\n\nUse the `type` field to determine the specific payment method variant.\n\n:::note\nThis schema represents a stored credential available for future charges and supports three types: `card`, `revolut_pay`, and `sepa_direct_debit`.\n\nIt differs from the `payment_method` object on a Payment, which is a transactional snapshot of how a specific charge was executed and includes additional detail such as wallet wrappers (`apple_pay`, `google_pay`) and Revolut Pay funding source (`revolut_pay_card` vs `revolut_pay_account`).\n:::",
      "oneOf": [
        {
          "$ref": "#/$defs/Card-v2"
        },
        {
          "$ref": "#/$defs/Revolut-Pay-v2"
        },
        {
          "$ref": "#/$defs/Sepa-Direct-Debit-v2"
        }
      ]
    },
    "Revolut-Pay-v2": {
      "title": "Revolut Pay payment method",
      "type": "object",
      "description": "A saved Revolut Pay payment method on a customer profile.\n\nBoth Revolut Pay card-backed and account-to-account (A2A) variants are\nrepresented by this single type at the saved payment method level.\nNo underlying card details are exposed here; use the order-level\n`payments[].payment_method` object (types `revolut_pay_card` /\n`revolut_pay_account`) for per-transaction details.",
      "properties": {
        "id": {
          "$ref": "#/$defs/Payment-Method-Id"
        },
        "type": {
          "$ref": "#/$defs/Payment-Method-Type-v2"
        },
        "saved_for": {
          "$ref": "#/$defs/Saved-For"
        },
        "created_at": {
          "$ref": "#/$defs/Payment-Method-Created-At"
        }
      },
      "required": [
        "id",
        "type",
        "created_at"
      ]
    },
    "Saved-For": {
      "type": "string",
      "enum": [
        "customer",
        "merchant"
      ],
      "description": "Indicates in which case this saved payment method can be used for payments.\n\n| Value | Description |\n| ----- | ----------- |\n| `customer` | This payment method can be used only when the customer is on the checkout page. |\n| `merchant` | This payment method can be used without the customer being on the checkout page, and the merchant can initiate transactions, for example, to take payments for recurring transactions. |"
    },
    "Sepa-Direct-Debit-Debtor-Iban-Last-Four": {
      "type": "string",
      "description": "The last four digits of the debtor's IBAN.",
      "minLength": 4,
      "maxLength": 4
    },
    "Sepa-Direct-Debit-Debtor-Name": {
      "type": "string",
      "description": "The full name of the debtor as provided in the mandate."
    },
    "Sepa-Direct-Debit-Mandate-Reference": {
      "type": "string",
      "description": "The unique mandate reference generated by Revolut. Include this in pre-debit notifications sent to your customers."
    },
    "Sepa-Direct-Debit-v2": {
      "title": "SEPA Direct Debit payment method",
      "type": "object",
      "description": "A saved SEPA Direct Debit payment method on a customer profile.\n\n:::info\nFor more information, see: [SEPA Direct Debit server-to-server integration](https://developer.revolut.com/docs/guides/merchant/accept-payments/payment-methods/sepa-direct-debit/server-to-server)\n:::",
      "properties": {
        "id": {
          "$ref": "#/$defs/Payment-Method-Id"
        },
        "type": {
          "$ref": "#/$defs/Payment-Method-Type-v2"
        },
        "saved_for": {
          "$ref": "#/$defs/Saved-For"
        },
        "debtor_iban_last_four": {
          "$ref": "#/$defs/Sepa-Direct-Debit-Debtor-Iban-Last-Four"
        },
        "debtor_name": {
          "$ref": "#/$defs/Sepa-Direct-Debit-Debtor-Name"
        },
        "mandate_reference": {
          "$ref": "#/$defs/Sepa-Direct-Debit-Mandate-Reference"
        },
        "billing_address": {
          "$ref": "#/$defs/Billing-Address"
        },
        "created_at": {
          "$ref": "#/$defs/Payment-Method-Created-At"
        }
      },
      "required": [
        "id",
        "type",
        "created_at"
      ]
    },
    "Terminal-Hardware-Id": {
      "type": "string",
      "description": "The hardware identifier of the Revolut Terminal device used to process the payment.\n\n:::note\nOnly present for card-present transactions processed via Revolut Terminal.\n:::"
    }
  }
}