Get All Payment Options

GET 
/accounts/:customerAccountId/paymentOptions

This API method enables you to retrieve the list of payment options stored under a specific private or business consumer's account.

info

The Get Payment Options API provides a response containing a variety of parameters in the object additionalData that may change depending on the selected payment method. Each payment option can have distinct fields, and understanding these variations is essential for proper integration. On the distinct payment option pages, we provide a detailed overview of the key parameters, descriptions and their data types. For the examples below, please refer to the respective SEPA page.

Request

Path Parameters

customerAccountId stringrequired
Possible values: <= 255 characters
Customer identifier
Example: john_doe_12345

Header Parameters

Content-Type stringrequired

Must be application/json

Accept-Language stringrequired

Must be be en-US

Origin stringrequired

The origin of the request

User-Agent stringrequired

The client making the request

Responses

201

Payment option successfully stored

application/json

Schema

Schema

namestring
Payment option, e.g., 'Mastercard', 'Bank Account', 'SEPA Direct Debit B2B'.
Example: SEPA Direct Debit core
codestring
Code representing the payment option type. Used in API requests to identify the option.
Example: SEPADDCORE
carrierNumberstring
Account or card number associated with the payment option.
Example: DE8937****3000
referencestring
Unique reference identifier for the stored payment option.
Example: U861vQBGPgSn8iPeNfGH5
isDefaultboolean
Indicates whether this is the default payment option for the account.
Example: true
isExpiredboolean
Indicates whether the payment option has expired.
Example: false
expiresSoonboolean
Indicates whether the payment option will expire within the next 30 days.
Example: false
expiryDatestring
Expiration date of the payment option in MM/YYYY format. May be far future-dated for accounts (e.g., SEPA).
Example: 12/2999
storedPaymentOptionData objectnullable
Additional technical data specific to the stored payment option (e.g., mandate or bank info).
mandate object
SEPA mandate information, if applicable.
mandateReferencestring
Unique SEPA mandate identifier.
Example: SEPA-202430071-NLD7GT499684QMHJ47S4
mandateSignedDatestring<date>
Date when the mandate was signed (format YYYY-MM-DD).
Example: 2024-09-24
mandateSignedTimestring
Time when the mandate was signed in HHMMSS format.
Example: 000000
bankCodestring
BIC or sort code of the customer's bank.
Example: COBADEFFXXX
bankNamestring
Name of the customer's bank.
Example: ACME Bank
additionalData object[]nullable
Optional extended metadata, typically used for direct debit payment options (e.g., SEPA).
Array [
namestring
Name of the metadata field.
Example: dd.creditorIdentifier
valuestring
Value assigned to the metadata field.
Example: LU11ZZ***01491
]

Example (auto)

{
  "name": "SEPA Direct Debit core",
  "code": "SEPADDCORE",
  "carrierNumber": "DE8937****3000",
  "reference": "U861vQBGPgSn8iPeNfGH5",
  "isDefault": true,
  "isExpired": false,
  "expiresSoon": false,
  "expiryDate": "12/2999",
  "storedPaymentOptionData": {
    "mandate": {
      "mandateReference": "SEPA-202430071-NLD7GT499684QMHJ47S4",
      "mandateSignedDate": "2024-09-24",
      "mandateSignedTime": "000000"
    },
    "bankCode": "COBADEFFXXX",
    "bankName": "ACME Bank"
  },
  "additionalData": [
    {
      "name": "dd.creditorIdentifier",
      "value": "LU11ZZ***01491"
    }
  ]
}

SEPA response

Example for SEPA Get SPO.
Please refer here for explanation on the response parameters in the object additionalData.

[
  {
    "name": "Mastercard",
    "code": "MSTRCRD",
    "carrierNumber": "520000****0106",
    "reference": "8ac7a4a08c13ee65018c151c330a26c6",
    "isDefault": true,
    "isExpired": false,
    "expiresSoon": false,
    "expiryDate": "03/2025"
  },
  {
    "name": "Bank Account",
    "code": "BNKACCT",
    "carrierNumber": "DE8937****3000",
    "reference": "05d985b8a7864e9ca71067dc98da5f99",
    "isDefault": true,
    "isExpired": false,
    "expiresSoon": false,
    "expiryDate": "12/2999",
    "storedPaymentOptionData": {
      "mandate": {
        "mandateReference": "SEPA-202430071-NLD7GT499684QMHJ47S4",
        "mandateSignedDate": "2024-09-24",
        "mandateSignedTime": "000000"
      },
      "bankCode": "COBADEFFXXX",
      "bankName": "ACME Bank"
    }
  },
  {
    "name": "SEPA Direct Debit B2B",
    "code": "SEPADDB2B",
    "carrierNumber": "DE******",
    "reference": "U861vQBGPgSn8iPeNfGH5",
    "isDefault": false,
    "isExpired": false,
    "expiresSoon": false,
    "expiryDate": "12/2999",
    "additionalData": [
      {
        "name": "dd.creditorName",
        "value": "J.P. Morgan Mobility Payments Solutions"
      },
      {
        "name": "dd.creditorIdentifier",
        "value": "LU11ZZ***01491"
      },
      {
        "name": "dd.creditorAddressCity",
        "value": "Munich"
      },
      {
        "name": "dd.creditorAddressCountryCode",
        "value": "DE"
      },
      {
        "name": "dd.creditorAddressNumber",
        "value": "456"
      },
      {
        "name": "dd.creditorAddressLine1",
        "value": "Leopoldstr."
      },
      {
        "name": "dd.creditorPostCode",
        "value": "80807"
      },
      {
        "name": "dd.mandateStatus",
        "value": "ACTIVE"
      },
      {
        "name": "dd.mandateReference",
        "value": "HM3BY4***SQDXYZD5"
      },
      {
        "name": "dd.mandateDateOfSignature",
        "value": "2021-02-23"
      },
      {
        "name": "dd.mandateId",
        "value": "224e1e25-12d5-4015-8d18-64383a14d50e"
      },
      {
        "name": "dd.mandateVersionTag",
        "value": "0001"
      },
      {
        "name": "dd.debtorBankName",
        "value": "Banca Frencesa new"
      },
      {
        "name": "dd.debtorBankBic",
        "value": "PSSTFRPPNEW"
      }
    ]
  },
  {
    "name": "SEPA Direct Debit core",
    "code": "SEPADDCORE",
    "carrierNumber": "BE6853****7034",
    "reference": "nuhMFZI81bpqkkwJmDPuF",
    "isDefault": false,
    "isExpired": false,
    "expiresSoon": false,
    "expiryDate": "12/2999",
    "storedPaymentOptionData": {
      "bankCode": "EXBKDE81XXX",
      "bankName": "ACME Bank"
    },
    "additionalData": [
      {
        "name": "dd.creditorName",
        "value": "J.P. Morgan Mobility Payments Solutions"
      },
      {
        "name": "dd.creditorIdentifier",
        "value": "LU11ZZ***001491"
      },
      {
        "name": "dd.creditorAddressCity",
        "value": "Munich"
      },
      {
        "name": "dd.creditorAddressCountryCode",
        "value": "DE"
      },
      {
        "name": "dd.creditorAddressNumber",
        "value": "456"
      },
      {
        "name": "dd.creditorAddressLine1",
        "value": "Leopoldstr."
      },
      {
        "name": "dd.creditorPostCode",
        "value": "80807"
      },
      {
        "name": "dd.mandateStatus",
        "value": "ACTIVE"
      },
      {
        "name": "dd.mandateReference",
        "value": "HM3BY***YZD5"
      },
      {
        "name": "dd.mandateDateOfSignature",
        "value": "2021-02-23"
      },
      {
        "name": "dd.mandateId",
        "value": "224e1e25-12d5-4015-8d18-64383a14d50e"
      },
      {
        "name": "dd.mandateVersionTag",
        "value": "0001"
      },
      {
        "name": "dd.debtorBankName",
        "value": "Banca Frencesa new"
      },
      {
        "name": "dd.debtorBankBic",
        "value": "PSSTFRPPNEW"
      }
    ]
  }
]

400

Bad Request

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Value out of bounds. Value must be between 1 and 100",
      "code": "value_out_of_bounds",
      "property": "someField",
      "context": {
        "minimum": 1,
        "maximum": 100
      }
    }
  ]
}

401

Unauthenticated

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You are not authenticated to perform this request.",
      "code": "unauthorized"
    }
  ]
}

403

Forbidden

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "You do not have permissions to perform this request.",
      "code": "forbidden"
    }
  ]
}

404

Not Found

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Resource not found.",
      "code": "not_found"
    }
  ]
}

500

Internal Server Error

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

{
  "error": "string",
  "errorDetails": {
    "context": {},
    "gatewayDescription": "string",
    "paymentProviderDescription": "string"
  },
  "message": "string"
}

Example

{
  "traceId": "00-1234567890abcdef0123456789abcdef-0123456789abcdef-00",
  "errors": [
    {
      "message": "Internal server error."
    }
  ]
}