Get All Payment Options

GET 
/accounts/:customerAccountId/paymentOptions

This API method enables you to retrieve the list of the 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 and Bacs pages.

Request

Path Parameters

customerAccountId stringrequired

Possible values: <= 255 characters

Customer identifier

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

name string

Payment option, e.g., 'Mastercard', 'Bank Account', 'SEPA Direct Debit B2B'.

code string

Code representing the payment option type. Used in API requests to identify the option.

carrierNumber string

Account or card number associated with the payment option.

reference string

Unique reference identifier for the stored payment option.

isDefault boolean

Indicates whether this is the default payment option for the account.

isExpired boolean

Indicates whether the payment option has expired.

expiresSoon boolean

Indicates whether the payment option will expire within the next 30 days.

expiryDate string

Expiration date of the payment option in MM/YYYY format. May be far future-dated for accounts (e.g., SEPA).

storedPaymentOptionData

object

nullable

Additional technical data specific to the stored payment option (e.g., mandate or bank info).

mandate

object

SEPA mandate information, if applicable.

mandateReference string

Unique SEPA mandate identifier.

mandateSignedDate date

Date when the mandate was signed (format YYYY-MM-DD).

mandateSignedTime string

Time when the mandate was signed in HHMMSS format.

bankCode string

BIC or sort code of the customer's bank.

bankName string

Name of the customer's bank.

additionalData

object[]

nullable

Optional extended metadata, typically used for direct debit payment options (e.g., SEPA or Bacs).

Array [

name string

Name of the metadata field.

value string

Value assigned to the metadata field.

]

Example (from schema)

{
  "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"
      }
    ]
  }
]

Bacs response

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

{
  "name": "BACS Direct Debit",
  "code": "BACSDD",
  "carrierNumber": "1234****",
  "reference": "YSPO5R...9AHoWNzn",
  "isDefault": false,
  "isExpired": false,
  "expiresSoon": false,
  "expiryDate": "12/2999",
  "storedPaymentOptionData": {
    "bankCode": "500000",
    "bankName": "ACME Bank"
  },
  "additionalData": [
    {
      "name": "dd.mandateStatus",
      "value": "ENABLED"
    },
    {
      "name": "dd.mandateReference",
      "value": "BACS20240515jf56iJ"
    },
    {
      "name": "dd.mandateInitiationDate",
      "value": "15-15-2024"
    },
    {
      "name": "dd.mandateActivationDate",
      "value": "21-05-2024"
    },
    {
      "name": "dd.creditorId",
      "value": "44556677889900"
    },
    {
      "name": "dd.bacsMerchantName",
      "value": "J.P. Morgan Mobility Payments Solutions S.A_GBP"
    },
    {
      "name": "dd.bacsMerchantMandateLabel ",
      "value": "JPM_GBP "
    }
  ]
}

400

Bad Request

info

For error handling, please refer to this section.

application/json

Schema

Schema

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

{
  "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

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

{
  "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

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

{
  "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

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

{
  "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

error string

errorDetails

object

context object

gatewayDescription string

paymentProviderDescription string

message

object

oneOf

MOD1

string

MOD2

Array [

string

]

Example (from schema)

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

Example

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

Loading...