Skip to main content

Create 3DS Authenticated Payment

POST 
/payment/authorize

This API method creates a payment authorization directly, without the need of using the SmartPay widget. The payment is based on the assumption that the payment option and authentication details have already been collected by the merchant.

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}}

Body

required

    payment

    object

    required

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

    description stringrequired

    Possible values: <= 127 characters

    Description of the payment transaction shown to the customer.

    amount decimalrequired

    Possible values: >= 0.01

    Total amount to be authorized.

    currencyCode stringrequired

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

    ISO 4217 three-letter currency code.

    billingAddress

    object

    required

    addressLine1 stringrequired

    Possible values: <= 60 characters

    Street name.

    addressLine2 string

    Possible values: <= 60 characters

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

    addressLine3 string

    Possible values: <= 60 characters

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

    city stringrequired

    Possible values: <= 50 characters

    The city or localitly of the address.

    countryCode stringrequired

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

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

    number string

    Possible values: <= 10 characters

    The house or building number corresponding to the street address.

    postCode stringrequired

    Possible values: <= 10 characters

    The postal or ZIP code of the address.

    state string

    Possible values: <= 3 characters

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

    shippingAddress

    object

    addressLine1 stringrequired

    Possible values: <= 60 characters

    Street name.

    addressLine2 string

    Possible values: <= 60 characters

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

    addressLine3 string

    Possible values: <= 60 characters

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

    city stringrequired

    Possible values: <= 50 characters

    The city or localitly of the address.

    countryCode stringrequired

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

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

    number string

    Possible values: <= 10 characters

    The house or building number corresponding to the street address.

    postCode stringrequired

    Possible values: <= 10 characters

    The postal or ZIP code of the address.

    state string

    Possible values: <= 3 characters

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

    consumer

    object

    required

    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.

    culture string

    Possible values: <= 5 characters

    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.

    dateOfBirth date

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

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

    emailAddress emailrequired

    Possible values: <= 255 characters

    Customer email address for any notification

    firstName stringrequired

    Possible values: <= 60 characters

    Person first name

    gender string

    Possible values: <= 6 characters

    Person gender

    homePhone string

    Possible values: <= 30 characters

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

    lastName stringrequired

    Possible values: <= 60 characters

    Person last name

    merchantCustomerId string

    Possible values: <= 255 characters

    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.

    middleName string

    Possible values: <= 60 characters

    The customer's middle name

    mobilePhone string

    Possible values: <= 30 characters

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

    taxId string

    Possible values: <= 30 characters

    Person's tax identification number

    timezone string

    Possible values: <= 50 characters

    Preferred timezone name

    title string

    Possible values: <= 3 characters

    Person title

    workPhone string

    Possible values: <= 30 characters

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

    partnerReference stringrequired

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

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

    paymentOption

    object

    required

    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

    object

    required

    Card-specific information used to process a card payment.

    cardDetails

    object

    required

    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.

    cardHolder stringrequired

    Possible values: <= 50 characters

    Full name of the cardholder.

    cardToken stringrequired

    Possible values: <= 64 characters

    Tokenized representation of the card number.

    cvvToken stringrequired

    Possible values: <= 4 characters

    Tokenized CVV for the card.

    cardExpiryMonth stringrequired

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

    Two-digit month of card expiry.

    cardExpiryYear stringrequired

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

    Four-digit year of card expiry.

    cardBrand stringrequired

    Possible values: <= 16 characters, [VISA, MSTRCRD, AMEX, DISCOVER]

    Card brand code.

    3ds

    object

    required

    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.

    acsEci stringrequired

    Possible values: <= 2 characters

    Electronic Commerce Indicator provided by the ACS.

    authenticationToken stringrequired

    Possible values: <= 64 characters

    Token confirming successful 3DS challenge.

    transactionStatus stringrequired

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

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

    protocolVersion stringrequired

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

    3DS protocol version used.

    dsTransactionId uuidrequired

    Possible values: <= 36 characters

    Transaction ID assigned by Directory Server.

    acsTransactionId uuidrequired

    Possible values: <= 36 characters

    Transaction ID assigned by ACS.

Responses​

Payment authorization successfully created

Schema

    partnerReference string

    Possible values: <= 64 characters

    Unique reference ID sent by the merchant and echoed back.

    description string

    Possible values: <= 127 characters

    Description of the transaction.

    paymentStatus string

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

    Current status of the payment.

    creationDate date-time

    Timestamp when the transaction was created.

    lastStatusDate date-time

    Timestamp when the payment status was last updated.

    transactionOverview

    object

    transactionId uuid

    Possible values: <= 36 characters

    SmartPay-assigned ID for the transaction.

    paymentMethod string

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

    Method used to complete the payment.

    amount decimal

    Final authorized or captured amount.

    currencyCode string

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

    ISO currency code.

    reconciliationReferenceId string

    Possible values: <= 64 characters

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

    modificationId uuid

    Possible values: <= 36 characters

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

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