Skip to main content

Store Payment Option

POST 
/accounts/:customerAccountId/paymentOptions

This methods allows the storing of card details that have already been authenticated. The returned storedPaymentOptionReference can be used, for example, in /payment/mit endpoint to authorize a merchant initiated payment without the need of additional 3DS challenges or submission of card details.

important

This endpoint contains PCI data and requires forwarding through /forwarding/tokenize.

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

Bodyrequired

    paymentOption objectrequired

    Details of the payment option to be stored.

    card objectrequired

    Card details including 3DS data and card metadata.

    3DS object

    3D Secure data for the card.

    3DS2 object

    3DS version 2 specific authentication data.

    acsEcistringrequired

    Electronic Commerce Indicator from ACS (e.g., '02').

    Possible values: <= 2 characters

    acsTransactionIdstring<uuid>required

    Transaction ID assigned by ACS.

    authenticationTokenstringrequired

    Token issued after successful 3DS authentication.

    Possible values: <= 64 characters

    dsTransactionIdstring<uuid>required

    Transaction ID from the Directory Server.

    protocolVersionstringrequired

    3DS protocol version used during authentication.

    Possible values: <= 10 characters

    Example: 2.1.0
    transactionStatusstringrequired

    Possible statuses:
    Y = Authenticated,
    N = Not Authenticated,
    U = Unavailable,
    A = Attempted,
    R = Rejected.

    Possible values: <= 1 characters, [Y, N, U, A, R]

    cardDetails objectrequired

    Masked card data for the payment method.

    cardBrandstringrequired

    Brand of the card (e.g., VISA, MASTERCARD).

    Possible values: <= 16 characters

    Example: VISA
    cardExpiryMonthstringrequired

    Expiration month of the card in MM format.

    Possible values: Value must match regular expression ^(0[1-9]|1[0-2])$

    Example: 09
    cardExpiryYearstringrequired

    Expiration year of the card in YYYY format.

    Possible values: Value must match regular expression ^20\d{2}$

    Example: 2029
    cardHolderstringrequired

    Full name of the cardholder.

    Possible values: <= 64 characters

    Example: JOHN DOE
    cardTokenstringrequired

    Tokenized identifier of the card.

    Possible values: <= 32 characters

    Example: LLVOXVAJINJWPDDPZA
    billingAddress objectrequired
    addressLine1stringrequired

    Street name.

    Possible values: <= 60 characters

    Example: Max-Planck-Straße
    addressLine2string

    Apartment, suite, unit, building, floor or other secondary address information.

    Possible values: <= 60 characters

    addressLine3string

    Specific delivery instructions, department names, or additional floor information.

    Possible values: <= 60 characters

    citystringrequired

    The city or localitly of the address.

    Possible values: <= 50 characters

    Example: Berlin
    countryCodestringrequired

    ISO-3 code of the address country (e.g., DEU for Germany).

    Possible values: >= 3 characters and <= 3 characters

    Example: DEU
    numberstring

    The house or building number corresponding to the street address.

    Possible values: <= 10 characters

    Example: 30
    postCodestringrequired

    The postal or ZIP code of the address.

    Possible values: <= 10 characters

    Example: 14473
    statestring

    3-letter code of the address state. Mandatory when countryCode corresponds to Canada or USA.

    Possible values: <= 3 characters

    businessConsumer objectnullable

    Company data, in case the consumer is a business or a legal entity.
    Mandatory, unless consumer is provided.
    consumer and businessConsumer objects may not be submitted together.

    companyNamestringrequired

    Name of the legal entity

    Possible values: <= 100 characters

    companyRegistrationCountryCodestring

    Company registration country ISO2 or ISO3 code

    Possible values: >= 2 characters and <= 3 characters

    companyRegistrationNumberstring

    Company registration number

    Possible values: <= 50 characters

    companyTypestringrequired

    Possible values: <= 100 characters

    culturestring

    Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g., en-de). This field is not case sensitive.

    Possible values: <= 5 characters

    Example: en-EN
    emailAddressstringrequired

    Customer email address for any notification

    Possible values: <= 255 characters

    taxIdstring

    Person's tax identification number

    Possible values: <= 30 characters

    consumer objectnullable

    Consumer's personal data, in case the consumer is a physical person.
    Mandatory, unless businessConsumer is provided.
    consumer and businessConsumer objects may not be submitted together.

    culturestring

    Consists of ISO 639-1 language code and ISO 3166-1 alpha-2 country code separated by dash. If this value is not provided the browser culture is used. Default culture is English (e.g., en-de). This field is not case sensitive.

    Possible values: <= 5 characters

    Example: en-EN
    dateOfBirthstring<date>

    Date of birth. Format - YYYY-MM-DD. Mandatory for payment option registration flow. Minimum date allowed is 1900-01-01

    Possible values: <= 10 characters, Value must match regular expression ^\d{4}-\d{2}-\d{2}$

    Example: 1989-11-08
    emailAddressstring<email>required

    Customer email address for any notification

    Possible values: <= 255 characters

    Example: john.doe@gmail.com
    firstNamestringrequired

    Person first name

    Possible values: <= 60 characters

    Example: John
    genderstring

    Person gender

    Possible values: <= 6 characters

    Example: Mr
    homePhonestring

    Person's home phone number (including the country code)

    Possible values: <= 30 characters

    Example: 496912345678
    lastNamestringrequired

    Person last name

    Possible values: <= 60 characters

    Example: Doe
    merchantCustomerIdstring

    Consumer/Customer Account Id in the merchant system. When provided into the Create Checkout API, SmartPay will request e-wallet account creation which will have external account reference equals to the given merchantCustomerId value.

    Possible values: <= 255 characters

    Example: abcd123
    middleNamestring

    The customer's middle name

    Possible values: <= 60 characters

    Example: Robert
    mobilePhonestring

    Person's mobile phone number (including the country code)

    Possible values: <= 30 characters

    Example: 496912345678
    taxIdstring

    Person's tax identification number

    Possible values: <= 30 characters

    Example: 123456789
    timezonestring

    Preferred timezone name

    Possible values: <= 50 characters

    Example: CET
    titlestring

    Person title

    Possible values: <= 3 characters

    Example: Mr
    workPhonestring

    Person's work phone number (including the country code)

    Possible values: <= 30 characters

    Example: 496912345678
    criteria object[]

    List of name/value pair custom parameters.

  • Array [
    • namestringrequired

    Name of the custom parameter.

    Possible values: <= 64 characters

    valuestringrequired

    Value of the custom parameter.

    Possible values: <= 256 characters

  • ]
    • customReferences object

    Optional custom reference fields used for merchant tracking.

    custom1string

    Possible values: <= 255 characters

    custom2string

    Possible values: <= 255 characters

    custom3string

    Possible values: <= 255 characters

    customerAccountIdstring

    Unique external identifier of the customer account.

    Possible values: <= 255 characters

    extraInfo object

    Additional grouping metadata.

    customerGroupstring

    Possible values: <= 64 characters

    productGroupstring

    Possible values: <= 64 characters

    payment objectrequired

    Transactional metadata for the registration payment.

    amountnumber<decimal>required

    Amount for the registration payment (minimum 0.01).

    Possible values: >= 0.01

    Example: 49.99
    currencyCodestringrequired

    ISO 4217 currency code.

    Possible values: Value must match regular expression ^[A-Z]{3}$

    Example: EUR
    descriptionstringrequired

    Short description of the transaction.

    Possible values: <= 127 characters

    Example: windscreen wipers 4 pcs
    shopCountrystring

    ISO 3166-1 alpha-2 country code of the shop.

    Possible values: Value must match regular expression ^[A-Z]{2}$

    Example: FR

Responses​

Payment option successfully stored

Schema
    storedPaymentOptionReferencestring

    Unique identifier of the stored payment option.

    Possible values: <= 64 characters

    Example: Ky28Mgp5GLauHPmYxUnZO
    cardDetails object

    Metadata about the stored card.

    cardBrandstring

    Brand of the card.

    Possible values: <= 16 characters, [AMEX, BNKACCT, CRTBANCAIR, DISCOVER, GIROPAY, IDEAL, JCB, MSTRCRD, MSTRO, PAYPAL, PAYU, PAYUBLK, PAYUTWST, PAYUINST, PREPMNT, SEPADDB2B, SEPADDCORE, VISA, VISADBIT]

    Example: MSTRCRD
    cardHolderstring

    Name of the cardholder.

    Possible values: <= 64 characters

    Example: JOHN DOE
    cardTokenstring

    Tokenized card identifier used for MIT.

    Possible values: <= 64 characters

    Example: 512345PFITLJFS0008
    cvvTokenstring

    Optional CVV token if stored securely.

    Possible values: <= 32 characters

    Example: WNZSWCUMAAHIDDVUDC
    cardExpiryMonthstring

    Expiration month of the stored card.

    Possible values: Value must match regular expression ^(0[1-9]|1[0-2])$

    Example: 09
    cardExpiryYearstring

    Expiration year of the stored card.

    Possible values: Value must match regular expression ^20\d{2}$

    Example: 2029
 Imprint
|
Data protection and privacy
© 2026 J.P. Morgan Mobility Payments Systems GmbH. All rights reserved.