Skip to main content

Create Card on File

POST 
/accounts/:customerAccountId/paymentOptions/

This methods allows the storing of card details that have already been authenticated and is used to tokenize and store a customer's card for future use. Prior to calling this endpoint, the card must be authenticated through a 3DS session using purpose: ADD_CARD, and sensitive card data must be sent via PCI forwarding to /forwarding/tokenize.

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

    Unique identifier of the customer account.

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

    Authorization stringrequired

    Basic M2lwN2Yx...OGU3Mg==

    X-Pcp-Url stringrequired

    {baseUrl}/accounts/{customerAccountId}/paymentOptions

    X-Pcp-Authorization stringrequired

    {{pci_base64_public_private}}

    X-Pcp-Cc-Path stringrequired

    cardDetails.cardToken

Bodyrequired

    billingAddress objectrequired

    Consumer's billing address data. See Address in Data model.

    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. See businessConsumer in Data model.
    Conditional. Can be present if consumer is missing from the request.

    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. See consumer in Data model.
    Conditional. Can be present if businessConsumer is missing from the request.

    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[]nullable

    List of custom key-value pairs that the merchant can submit.
    The names callBackUrl and redirectUrl will be disregarded.

  • Array [
    • namestringrequired

    name of the parameter. The value must be unique within the criteria array

    Possible values: <= 50 characters

    valuestringrequired

    value of the parameter

    Possible values: <= 100 characters

  • ]
    • customReferences objectnullable

    For external party usage. Please refer to Data Model for more details.

    custom1string

    generic custom reference

    Possible values: <= 255 characters

    custom2string

    generic custom reference

    Possible values: <= 255 characters

    custom3string

    generic custom reference

    Possible values: <= 255 characters

    customerAccountIdstringnullable

    Consumer's account identifier in the merchant's system. To be used as an external account reference. Disregarded when provided as a path parameter.

    Possible values: <= 255 characters

    Example: john-doe-27
    extraInfo objectnullable

    Payment extra information to define the product group, to display different set of payment options (Card, SEPA, PayPal...) for different products.

    customerGroupstring

    In case customer group rule is defined in channel configuration, this value is used for channel evaluation

    Possible values: <= 100 characters

    Example: SilverCustomers
    productGroupstring

    In case customer group rule is defined in channel configuration, this value is used for channel evaluation

    Possible values: <= 100 characters

    Example: tyres
    payment objectrequired

    The payment amount to be charged against the payment option.

    amountnumber<decimal>required

    Transaction modification amount

    Possible values: >= 0.01, Value must match regular expression ^\d{1,18}\.\d{2}$

    Example: 49.99
    currencyCodestringrequired

    Transaction modification currency. The 3-letter currency ISO-4217 code

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

    Example: EUR
    descriptionstringrequired

    A terse description of the good or service being sold i.e., the reason for the payment

    Possible values: <= 127 characters

    Example: windscreen wipers 4 pcs
    shopCountrystringnullable

    The ISO 3166-1 alpha-2 code of the shop country. Must match at least one of the countries configured for the merchant.

    Possible values: <= 2 characters

    Example: FR
    paymentOption objectrequired
    card objectrequired
    3DS objectrequired
    3DS2 object
    acsEcistringrequired

    Indicates the security level of the transaction.

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

    Example: 02
    acsTransactionIdstringrequired

    A unique transaction identifier assigned by the Access Control Server to identify the 3DS transaction.

    Possible values: <= 100 characters

    Example: 57f4e6a3-69a5-4693-b72f-61976e1d679a
    authenticationTokenstringrequired

    A unique identifier for the 3-D Secure authentication transaction.

    Possible values: >= 28 characters and <= 32 characters

    Example: kBIAAAAAqU20mQBkWBjZBpeBGqrD
    dsTransactionIdstringrequired

    A unique transaction identifier assigned by the scheme Directory Server to identify the 3DS transaction.

    Possible values: <= 100 characters

    Example: 118b60da-3c9f-4d97-b508-b84aa4e99646
    protocolVersionstringrequired

    The version of the EMV 3-D Secure protocol used to perform 3-D Secure authentication, in the format specified by EMVCo.

    Possible values: <= 6 characters

    Example: 2.1.0.
    transactionStatusstringrequired

    Indicates the result of payer authentication with the issuer. Possible values:

    • N - Transaction did not qualify as an authenticated transaction or account verification.
    • Y - The transaction qualified as an authenticated transaction.
    • C - 3DS version 2.2.0 only. Transaction requires a challenge.
    • R - 3DS version 2.2.0 only. A challenge is recommended for the transaction.
    • U - 3DS version 2.2.0 only. The transaction is unavailable for authentication.
    • A - 3DS version 2.2.0 only. The transaction is authenticated with a frictionless flow.

    Possible values: non-empty and <= 1 characters, [N, Y, C, R, U, A]

    Example: Y
    cardDetails objectrequired
    cardBrandstringrequired

    Card brand code. Please refer to Data Model.

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

    cardExpiryMonthstringrequired

    Credit card expiration month in format "MM".

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

    Example: 09
    cardExpiryYearstringrequired

    Credit card expiration year in format "YY" or "YYYY"

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

    Example: 2029
    network-tokensstring

    Card holder's name as displayed on the card

    Possible values: <= 100 characters

    Example: JOHN DOE
    cardTokenstringrequired

    PAN token

    Possible values: <= 18 characters

    Example: LLVOXVAJINJWPDDPZA
    cvvTokenstringrequired

    CVV token

    Possible values: <= 18 characters

    Example: UHHTREDDFTTYUIOKMT

Responses​

Card successfully stored

Schema
    storedPaymentOptionReferencestringrequired

    Reference to the created stored payment option.

    Possible values: <= 100 characters

    cardDetails objectrequired
    cardBrandstringrequired

    Card brand code. Please refer to Data Model.

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

    cardExpiryMonthstringrequired

    Credit card expiration month in format "MM".

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

    Example: 09
    cardExpiryYearstringrequired

    Credit card expiration year in format "YY" or "YYYY"

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

    Example: 2029
    network-tokensstring

    Card holder's name as displayed on the card

    Possible values: <= 100 characters

    Example: JOHN DOE
    cardTokenstringrequired

    PAN token

    Possible values: <= 18 characters

    Example: LLVOXVAJINJWPDDPZA
    cvvTokenstringrequired

    CVV token

    Possible values: <= 18 characters

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