API-only integration journey

Last changes: 12-20-2022

Process Overview

The API-only integration journey consists of four parts:

  • Collect the card details through presenting your own payment form.
  • Submit a tokenization request to our API with the card data you have collected from the end consumer.
  • Initiate a payment request towards our API with the tokenized data received.
  • Orchestrate the 3D secure redirection and authentication using the details received as a response from the previous API request.
  • Complete the payment request 

Collect the card details

As Merchant, you would be collecting the card details from your end consumer, using your own built payment form

Submit a tokenization request for PAN & CVV

By calling both below APIs, you would be able to tokenize both the CardNumber/PAN and the CVV:

  • Tokenize PAN API
  • Tokenize CVV API

Tokenize PAN Request:

Path:

POST https://pci-proxy.cons.tokenization.jpmmps.com/public/v1/tokenization/card

Header:

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

{
    "card_number": "5200000000000015"
}

Response

{
    "temp_token": "ZPJBYAEHQEHZPGQYQE"
}

Tokenize CVV Request:

Path:

POST https://pci-proxy.cons.tokenization.jpmmps.com/public/v1/tokenization/cvv

Header:

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

{
    "cvv": "123"
}

Tokenize CVV Response:

{
    "temp_token": "QPJBBAEHQEHZPGQPWE"
}

Initiate a payment request

Once you've Tokenized the card details you can initiate the payment by calling the "Create Tokenized Payment" API.

 

Request

Path:

POST {Base URL}/payment/init-token-payment

Header:

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

{
    "merchantKey": "3227a1df-1033-46fd-93bd-x01777339e5b",
    "excemptionFlag": "07",
    "payment": {
        "currencyCode": "EUR",
        "amount": 40.11,
        "description": "Purchase 1x product ABC"
    },
    "billingAddress": {
        "customerFullName": "Hells Butcher",
        "emailAddress": "hells.butcher_001@mail.com",
        "address": "Leopoldstrasse",
        "number": "244",
        "city": "Munich",
        "postCode": "80807",
        "countryCode": "DE"
    },
    "shippingAddress": {
        "address": "Leopoldstrasse",
        "number": "244",
        "city": "Munich",
        "postCode": "80807",
        "countryCode": "DE"
    },
    "consumer": {
        "emailAddress": "hells.butcher_001@mail.com",
        "customerGroupId": "VIP",
        "gender": "m",
        "lastName": "Hells",
        "firstName": "Butcher",
        "middleName": "fon",
        "title": "Mr",
        "culture": "de-de",
        "timezone": "<EXAMPLE>",
        "dateOfBirth": "2000-01-01",
        "mobilePhone": "015xx22-2135466",
        "isBusinessUser": false,
        "taxId": "00745948504594"
    },
    "cardDetails": {
        "cardBrand": "visa",
        "cardHolder": "Jimmy Rogers",
        "cardToken": "LLVOXVAJINJWPDDPZA",
        "cvvToken": "VDODFNMCXWMPSQBXJW",
        "cardExpiryMonth": 12,
        "cardExpiryYear": 2024
    }
}

Response

{

    "transactionId": "234d514f-70ef-4980-9b76-6bc86b0268f4",

    "status": "AUTHORIZATION_INITIALIZED",

    "creationDate": "2022-12-19T16:30:05.857Z",

    "threeDSChallenge": "3DSv1",

    "threeDSv1": {

        "url": "https://test.ppipe.net/connectors/demo/simulator.link?ndcid=8ac7a4c872ea49770172eae841fe0597_931ecffdbcb24749a192eb3ac6ea701d",

        "connector": "THREEDSECURE",

        "MD": "8ac7a4a1852afebd01852b389b342e14",

        "PaReq": "IT8ubu+5z4YupUCOEHKsbiPep8UzIAcPKJEjpwGlzD8#NDExMTExMTExMTExMTExMSMzMzc5LjIwIEVVUiM",

        "TermUrl": "https://test.ppipe.net/connectors/asyncresponse_simulator;jsessionid=02860A292BC003BA3B511328D0185F62.uat01-vm-con02?asyncsource=THREEDSECURE&ndcid=8ac7a4c872ea49770172eae841fe0597_931ecffdbcb24749a192eb3ac6ea701d"

    }

}

Orchestrate the 3D secure redirection and authentication

Depending on the response you get from "Create Tokenized Payment", you orchestrate the 3DS flow.

  1. If the parameter "threeDSChallenge" is equal to "3DSv1"
    Perform a POST request to the URL received in threeDSv1.url value with content-type=x-www-form-urlencoded, including the other threeDSv1 object received values in the body.
    Example below: 

Path:

POST

Header:

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

   {
        "connector": "THREEDSECURE",
        "MD": "8ac7a4a1852afebd01852b389b342e14",
        "PaReq": "IT8ubu+5z4YupUCOEHKsbiPep8UzIAcPKJEjpwGlzD8#NDExMTExMTExMTExMTExMSMzMzc5LjIwIEVVUiM",
        "TermUrl": "https://test.ppipe.net/connectors/asyncresponse_simulator;jsessionid=02860A292BC003BA3B511328D0185F62.uat01-vm-con02?asyncsource=THREEDSECURE&ndcid=8ac7a4c872ea49770172eae841fe0597_931ecffdbcb24749a192eb3ac6ea701d"
    }

2. If the parameter "threeDSChallenge" is equal to "3DSv2":
Perform a GET request to the received URL (threeDSv2.url)

Complete the payment request

Once the 3D secure authentication is finalized, or in case it wasn't required (frictionless flow), you can call the "Complete Tokenized Payment" API, to complete the payment process.

POST {Base URL}/payment/complete-token-payment

Header:

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

{
    "merchantKey": "3227a1df-1033-46fd-93bd-x01777339e5b",
    "transactionId": "933a0fab-80a0-42c5-b010-c71174f4ab32"
}
{
    "transactionId": "4e687bcc-053d-47e1-ad15-ae0c30a41d03",
    "uniqueReference": "130skldhipj4ih8g73b4uhgo3s"
    "paymentStatus": "AUTHORISATION_COMPLETED",
}

Document version 1.0 - 2022-12-19