Create 3DS Session

POST 
/3DS-sessions

This method creates a 3DS authentication session and provides a redirectUrl where the actual authentication takes place.

• Make sure to specify purpose according to the intended interaction as PAYMENT_TRANSACTION for customer-initiated transactions (Create a Payment 3DS Session), or ADD_CARD, for merchant-initiated transactions (Create a Storing 3DS Session).
• The method response contains a redirectUrl, to complete authentication, payer needs to be redirected and complete the challenge.
• Once challenge completed, payer is redirected to returnUrl, this need to be used as trigger to issue GET 3DS-sessions/{id} request to confirm transaction status an retrieve values required for payment / storing endpoints.

important

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

Please refer to two examples below which illustrate Create a Payment 3DS Session and Create a Storing 3DS Session.

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}/3DS-sessions

X-Pcp-Authorization stringrequired

{{pci_base64_public_private}}

X-Pcp-Cc-Path stringrequired

cardDetails.cardToken

application/json

Body

Bodyrequired

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
authenticationAmount objectrequired
Information about the operation amount.
amountnumber<decimal>required
Operation amount.
Possible values: Value must match regular expression ^\d{1,18}(\.\d{1,2})?$
Example: 27.99
currencyCodestringrequired
Operation currency ISO-4217 3-letter code.
Possible values: >= 3 characters and <= 3 characters
Example: EUR
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

shippingAddress object

Consumer's shipping 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

purposestringrequired

Indicates the purpose of 3DS authentication.

Possible values: [ADD_CARD, PAYMENT_TRANSACTION]

returnUrlstringrequired
URL provided by merchant which will be called upon completion of the 3DS authentication.
Example: https://my-webshop.com/3DS-return
Possible values: <= 255 characters
Example: https://my-webshop.com/3DS-return
targetMerchantAccountReferencestringnullable
Indicates the account number or billing reference to be used.
Possible values: <= 127 characters
Example: abcd123
partnerReferencestringnullable
3DS session identifier provided by the merchant.
Possible values: <= 40 characters, Value must match regular expression ^[a-zA-Z0-9\-_\.:]+$
Example: GHssjkauhdaku658702

Payment 3DS Session

Create a Payment 3DS Session

{
  "cardDetails": {
    "cardHolder": "JOHN DOE",
    "cardToken": "5123450000000008",
    "cardExpiryMonth": "09",
    "cardExpiryYear": "2029",
    "cardBrand": "MSTRCRD"
  },
  "authenticationAmount": {
    "amount": 20,
    "currencyCode": "EUR"
  },
  "purpose": "PAYMENT_TRANSACTION",
  "returnUrl": "https://www.example.com",
  "shippingAddress": {
    "addressLine1": "Max-Planck Str",
    "number": "30",
    "city": "Berlin",
    "postCode": "14473",
    "countryCode": "DE"
  },
  "billingAddress": {
    "addressLine1": "Max-Planck Str",
    "number": "30",
    "city": "Berlin",
    "postCode": "14473",
    "countryCode": "DEU"
  }
}

Storing 3DS Session

Create a Storing 3DS Session

{
  "cardDetails": {
    "cardHolder": "JOHN DOE",
    "cardToken": "5123450000000008",
    "cardExpiryMonth": "09",
    "cardExpiryYear": "2029",
    "cardBrand": "MSTRCRD"
  },
  "authenticationAmount": {
    "amount": 20,
    "currencyCode": "EUR"
  },
  "purpose": "ADD_CARD",
  "returnUrl": "https://www.example.com",
  "shippingAddress": {
    "addressLine1": "Max-Planck Str",
    "number": "30",
    "city": "Berlin",
    "postCode": "14473",
    "countryCode": "DE"
  },
  "billingAddress": {
    "addressLine1": "Max-Planck Str",
    "number": "30",
    "city": "Berlin",
    "postCode": "14473",
    "countryCode": "DEU"
  }
}

Responses

201

3DS session successfully created

application/json

Schema

Schema

idstring<uuid>required
sessionId that can be used to obtain 3DS authentication result and details from GET 3DS-sessions/{id}.
Example: cc219fff-2905-42d3-8df9-46c533275386
redirectUrlstringrequired
Url where the 3DS authentication is performed and where the merchant redirects the end user.
Possible values: <= 255 characters
Example: `baseUrl/public/sessions/{id}/payment-form`

Example (auto)

{
  "id": "cc219fff-2905-42d3-8df9-46c533275386",
  "redirectUrl": "`baseUrl/public/sessions/{id}/payment-form`"
}

Example

{
  "id": "d04b5f52-12e2-470c-b38d-26aa06e40dc2",
  "redirectUrl": "https://3DS-api.cons.shared.upcf.jpmmps.com/public/sessions/d04b5f52-12e2-470c-b38d-26aa06e40dc2/payment-form"
}

400

Bad Request

info

For error handling, please refer to this section.

application/json

Schema

Schema

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

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

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

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

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

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

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

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

errorstring
errorDetails object
contextobject
gatewayDescriptionstring
paymentProviderDescriptionstring
message object
oneOf
• string
• string[]
string

Example (auto)

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

Example

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