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/ billingAddress).
The POST endpoints/payment/authorize
, /accounts/{customerAccountId}/paymentOptions
accept clear credit card CVV, and 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.
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 aredirectUrl
to which the payer needs to be redirected. After the 3DS challenge in the browser, the payer is redirected to thereturnUrl
.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 previousGET /3ds-sessions/{id}
endpoint.- Storing: Payment Profile or Card on File can be created. To create a
storedPaymentOption
(Card on File), thePOST /accounts/{customerAccountId}/paymentOptions
endpoint needs to be called. This call requires the 3ds-session details as received via previousGET /3ds-sessions/{id}
endpoint.To authorize any merchant-initiated transaction, the
POST /payment/mit
endpoint needs to be called. The previous endpointPOST /accounts/> {customerAccountId}/paymentOptions
contains astoredPaymentOptionReference
which needs to be passed to all subsequent/payment/mit
calls.Both
POST /payment/authorize
andPOST /payment/mit
responses contains apaymentStatus
indicating on outcome of authorization attempt and atransactionId
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 |
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
X-Pcp-Url: https://api.cons.smartpay.jpmmps.com/payment/3ds-sessions
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"
}