API-only Integration Journey

SmartPay Standalone 3DS Authentication

SmartPay Standalone 3DS Authentication Services are designed for Integrators / merchants who are:

• able to handle Payer's Credit Card Data directly in PCI compliant way
• requiring Standalone 3DS Sessions for use in own checkout / registration journeys
• wish to perform payments using card data on file.

Preconditions

To use below described APIs, the integrator needs to collect:

• Payer's card details obtained and stored in PCI compliant way.
• Have further data as per schema available (such as amount, currency, shippingAddress and/or billingAddress).

info

The POST endpoints /payment/authorize and /accounts/{customerAccountId}/paymentOptions accept clear credit card CVV.

In addition to previous endpoints, /3ds-sessions also accepts PAN, if this data is present in request body.

It is mandatory to send those requests through our transparent PCI-Proxy's /forwarding/tokenize endpoint.

important

Only our production endpoint https://pci-proxy.tokenization.jpmmps.com/public/v1 is PCI certified. Make sure to not send real credit card data to any other endpoint.

These Standalone 3DS endpoints work together with the SmartPay offering, please also see the following documentation:

• Payment transaction status and history
• Transaction modification APIs (Capture, Cancel, Refund)
• General SmartPay documentation

You may use these APIs with transactionId retrieved in response of financial requests and the below mentioned SmartPay credentials.

Process Overview

The API-only Integration Journey consists of four parts:

1. Collect Card Details

Gather card details through presenting your payment form, ensuring PCI compliance.

2. Create a 3DS session for Payment or Storing Card-On-File

• Customer-Initiated Transactions
  To authenticate the payment transaction, call the POST /3ds-sessions endpoint with "purpose":"PAYMENT_TRANSACTION".

• Merchant-Initiated Transactions
  To authenticate the transaction, call the POST /3ds-sessions endpoint with "purpose":"ADD_CARD".

3. Orchestrate redirection to 3DS Secure challenge and obtain Authentication results

Regardless of the intention (payment or storing) the call POST /3ds-sessions returns a redirectUrl to which the payer needs to be redirected. After the 3DS challenge in the browser, the payer is redirected to the returnUrl.

Upon redirection, the integrator needs to call GET /3ds-sessions/{id}` to retrieve the 3DS challenge result.

4. Submit a payment or storing request

• Payment
  To authorize the charge, the POST /payment/authorize endpoint needs to be called. This call requires the 3ds-session details as received via previous GET /3ds-sessions/{id} endpoint.

• Storing
  Payment Profile or Card on File can be created. To create a storedPaymentOption (Card on File), the POST /accounts/{customerAccountId}/paymentOptions endpoint needs to be called. This call requires the 3ds-session details as received via previous GET /3ds-sessions/{id} endpoint.

To authorize any merchant-initiated transaction, the POST /payment/mit endpoint needs to be called.

The previous endpoint POST /accounts/{customerAccountId}/paymentOptions contains a storedPaymentOptionReference which needs to be passed to all subsequent /payment/mit calls.

Both POST /payment/authorize and POST /payment/mit responses contains a paymentStatus indicating on outcome of authorization attempt and a transactionId which can be used with the SmartPay Modification APIs.

Transparent Tokenization

All SmartPay APIs which contain credit card data must be reached via PCI Proxy Transparent Tokenization endpoint. This endpoint accepts PCI-sensitive data, tokenizes it, and forwards the request with the tokenized data to the specified URL.

Its functionality is controlled via X-Pcp- header parameters:

Name	Description	Type	Required
X-Pcp-Url	Destination request url = SmartPay base URL and request path. Available values: https://api.cons.smartpay.jpmmps.com/3ds-sessions https://api.cons.smartpay.jpmmps.com/payment/authorize https://api.cons.smartpay.jpmmps.com/accounts/{customerAccountId}/paymentOptions	String	Yes
X-Pcp-Authorization	PCI Proxy Basic Auth Value	String	Yes
X-Pcp-Cc-Path	Path to JSON property in request body containing the credit card PAN value.	String	Yes
X-Pcp-Cvv-Path	Path to JSON property in request body containing the credit card CVV value.	String	No

important

Forwarding is only required for POST requests containing credit card PAN and CVV data.
Only the production endpoint https://pci-proxy.tokenization.jpmmps.com/public/v1 is PCI certified. Make sure to not send real credit card data to any other endpoint.

Request

Path:

POST {PCIProxyBaseUrl}/forwarding/tokenize

Header:

Content-Type: application/json
Accept-Language: en-US
Origin: { Origin }
User-Agent: { User-Agent }

X-Pcp-Url: https://api.cons.smartpay.jpmmps.com/payment/authorize
X-Pcp-Authorization: {{pci_base64_public_private}}
X-Pcp-Cvv-Path: paymentOption.card.cardDetails.cvvToken
X-Pcp-CC-Path: paymentOption.card.cardDetails.cardToken

Authorization: Basic M2lwN2Yx...OGU3Mg==

{
  "payment": {
    "description": "OEM APIs Test",
    "amount": 49.99,
    "currencyCode": "EUR"
  },
  "billingAddress": {
    "addressLine1": "Max-Planck-Straße",
    "number": "30",
    "city": "Berlin",
    "postCode": "14473",
    "countryCode": "DE"
  },
  "consumer": {
    "merchantCustomerId": "ID-",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Robert",
    "emailAddress": "test@test.de",
    "title": "Mr",
    "culture": "en-EN",
    "timezone": "CET",
    "dateOfBirth": "1982-03-03",
    "gender": "Mr",
    "mobilePhone": "496912345678",
    "homePhone": "496912345678",
    "workPhone": "496912345678",
    "taxId": "123456789"
  },
  "partnerReference": "9AS9EdK1ySZL5E1bbG",
  "shippingAddress": {
    "addressLine1": "Max-Planck-Straße",
    "number": "30",
    "city": "Berlin",
    "postCode": "14473",
    "countryCode": "DE"
  },
  "paymentOption": {
    "card": {
      "cardDetails": {
        "cardHolder": "JOHN DOE",
        "cardToken": "5123450000000008",
        "cvvToken": "123",
        "cardExpiryMonth": "09",
        "cardExpiryYear": "2029",
        "cardBrand": "MSTRCRD"
      },
      "3ds": {
        "3ds2": {
          "acsEci": "02",
          "authenticationToken": "kHyn+7YFi1EUAREAAAAvNUe6Hv8=",
          "transactionStatus": "Y",
          "protocolVersion": "2.1.0",
          "dsTransactionId": "68f92ff6-c417-40df-bfaf-6518c43f40fb",
          "acsTransactionId": "0571d1c1-df05-4a6b-83c9-b6d1617a64f6"
        }
      }
    }
  }
}

Response

Status Code:

201 (3DS session successfully created)

Header:

Content-Type: application/json
Accept-Language: en-US

{
  "partnerReference": "SOwS1Ir7UluDoJJF0p",
  "description": "OEM APIs Test",
  "paymentStatus": "CAPTURED",
  "creationDate": "2024-03-28T10:02:43.272Z",
  "lastStatusDate": "2024-03-28T10:02:47.507Z",
  "transactionOverview": {
    "transactionId": "a7dd1c65-847e-4b4f-8284-5ed7bed2c84b",
    "paymentMethod": "CARDS",
    "amount": 49.99,
    "currencyCode": "EUR"
  },
  "reconciliationReferenceId": "SdsEh9hCGI434teXG3abz",
  "modificationId": "a7dd1c65-847e-4b4f-8284-5ed7bed2c84b"
}