Skip to main content

Create 3DS Authenticated Payment

POST 
/payment/authorize

This method initiates a 3D Secure payment authorization.

important

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

Request​

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}/payment/authorize

    X-Pcp-Authorization stringrequired

    {{pci_base64_public_private}}

    X-Pcp-Cc-Path stringrequired

    cardDetails.cardToken

Bodyrequired

    payment objectrequired

    The financial attributes of a transaction, required for all payment operations.

    descriptionstringrequired

    Description of the payment transaction shown to the customer.

    Possible values: <= 127 characters

    amountnumber<decimal>required

    Total amount to be authorized.

    Possible values: >= 0.01

    currencyCodestringrequired

    ISO 4217 three-letter currency code.

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

    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

    shippingAddress object
    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

    consumer objectnullablerequired

    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
    partnerReferencestringrequired

    Transaction identifier provided by the merchant. Must be unique per transaction.

    Possible values: <= 64 characters, Value must match regular expression ^[a-zA-Z0-9._:-]+$

    targetMerchantAccountReferencestring

    If provided, the payment is processed in favour of the indicated submerchant account, and the main merchant account number is ignored.

    Possible values: <= 127 characters

    paymentOption objectrequired

    The customer's selected payment option. This object is used to define the method and necessary data required to complete a transaction. It supports cards and other types (e.g., SEPA, PayPal) depending on context.

    card objectrequired

    Card-specific information used to process a card payment.

    cardDetails objectrequired

    Contains the tokenized cardholder information used for payment authorization. All values must be obtained and tokenized securely via the Web SDK or a PCI-compliance environemnt.

    cardHolderstringrequired

    Full name of the cardholder.

    Possible values: <= 50 characters

    cardTokenstringrequired

    Tokenized representation of the card number.

    Possible values: <= 64 characters

    cvvTokenstringrequired

    Tokenized CVV for the card.

    Possible values: <= 4 characters

    cardExpiryMonthstringrequired

    Two-digit month of card expiry.

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

    cardExpiryYearstringrequired

    Four-digit year of card expiry.

    Possible values: <= 4 characters, Value must match regular expression ^[0-9]{4}$

    cardBrandstringrequired

    Card brand code.

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

    3ds objectrequired

    Wraps the authentication data to prove that Strong Customer Authentication (SCA) has been performed.

    3ds2 object

    Holds the 3-D Secure version 2.x authentication details.

    acsEcistringrequired

    Electronic Commerce Indicator provided by the ACS.

    Possible values: <= 2 characters

    Example: 02
    authenticationTokenstringrequired

    Token confirming successful 3DS challenge.

    Possible values: <= 64 characters

    transactionStatusstringrequired

    Y: Success, N: Failure, U: Unavailable, A: Attempted, R: Rejected.

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

    protocolVersionstringrequired

    3DS protocol version used.

    Possible values: <= 8 characters, [2.1.0, 2.2.0]

    dsTransactionIdstring<uuid>required

    Transaction ID assigned by Directory Server.

    Possible values: <= 36 characters

    acsTransactionIdstring<uuid>required

    Transaction ID assigned by ACS.

    Possible values: <= 36 characters

Responses​

Payment authorization successfully created

Schema
    partnerReferencestring

    Unique reference ID sent by the merchant and echoed back.

    Possible values: <= 64 characters

    descriptionstring

    Description of the transaction.

    Possible values: <= 127 characters

    paymentStatusstring

    Current status of the payment.

    Possible values: <= 16 characters, [CREATED, CAPTURED, AUTHORIZATION_PENDING, AUTHORIZATION_COMPLETED, FAILED, CAPTURE_PENDING, CANCELLATION_PENDING, EXPIRED, CANCELLED, SETTLED, CHARGEBACK]

    creationDatestring<date-time>

    Timestamp when the transaction was created.

    lastStatusDatestring<date-time>

    Timestamp when the payment status was last updated.

    transactionOverview object
    transactionIdstring<uuid>

    SmartPay-assigned ID for the transaction.

    Possible values: <= 36 characters

    paymentMethodstring

    Method used to complete the payment.

    Possible values: <= 16 characters, [CARDS, SEPA, PAYPAL]

    amountnumber<decimal>

    Final authorized or captured amount.

    currencyCodestring

    ISO currency code.

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

    reconciliationReferenceIdstring

    Unique identifier from the payment provider used for settlement and reconciliation.

    Possible values: <= 64 characters

    modificationIdstring<uuid>

    ID of the latest modification (e.g., capture) applied to the transaction.

    Possible values: <= 36 characters

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