PPS 3D-Secure API

3.0.x
(0 reviews)
Following endpoints have been exposed to customers.

Context

resources/1-all-e2a8590e-001b-4a2f-9dfc-cf99b20f73fb.png

3D-Secure provider (e.g., Stripe) sends Authorisation Challenge request to PPS which is then stored and forwarded to Customer. After successful delivering of the message to Customer, acknowledgement message is immediately send back first to PPS and then forwarded back to 3D-Secure Provider. Customer can then resolve the challenge and send back result to PPS (1) which will be then updated accordingly and forwarded to 3D-Secure provider. In order to do so, Customer has to send PATCH request to:

https://{pps_base_uri}/3d-secure/api/v1/authorisation-challenges/{challenge_id}

with valid HMAC in header and with following example payload:

{
"delegated_result": "AUTHENTICATED",
"verification_method": "BIOMETRIC"
}

The response is sent once PPS has received the response from 3DS Provider. If the response from 3DS Provider contains an error, it will be forwarded to Customer. Example response:

{
   "id":"36144545-5119-4535-a3ff-c5f017325a84",
   "customer_code":"518135249315251419",
   "source":"STRIPE",
   "request_date":"2020-03-13T10:14:53Z",
   "expiry_date":"2020-03-13T10:19:53Z",
   "provider_result":"OK",
   "result_date":"2020-05-13T13:43:14Z",
   "authorisation":{
      "token":"01e96e9bd3c2311e63bcb78db32c3be218899cb2068f787adc5281a63c168c77",
      "request_date":"2020-03-13T10:14:53Z",
      "amount":{
         "amount":26473,
         "currency":{
            "code":"978",
            "exponent":2
         }
      },
      "recurring":{
         "frequency_days":30,
         "end_date":"2020-07-11"
      },
      "installments":{
         "maximum":4
      },
      "merchant":{
         "id":"444444",
         "name":"Amazon",
         "country":"276",
         "url":"https://amazon.de"
      }
   },
   "status":"COMPLETE",
   "card":{
      "serial_no":7100047507,
      "masked_pan":"506303******5057",
      "external_ref":"BQA135-1587406272777",
      "token":"9o4y4rP07lT1fM57n6-20042020-10",
      "account":{
         "product_class":"ER_MEX_BENS_MXN",
         "account_no":"44040100376767",
         "external_ref":"20200420191105371248"
      }
   },
   "delegated_result":"AUTHENTICATED",
   "verification_method":"BIOMETRIC"
}

The "provider_result" field should be set by 3DS Provider and hold a value of OK, ERROR, EXPIRED or ALREADY_PROCESSED. Status field values: PENDING is the initial/active/still in progress state. COMPLETE, FAILED, CANCELLED are the termination states.

Customer can also send request to PPS (2) in order to get some more details about Authorisation Challenge like for example its current status. In order to do so, Customer has to send GET request with valid HMAC in header to:

https://{pps_base_uri}/3d-secure/api/v1/authorisation-challenges/{challenge_id}

Example response:

{
   "id":"36144545-5119-4535-a3ff-c5f017325a84",
   "customer_code":"518135249315251419",
   "source":"STRIPE",
   "request_date":"2020-03-13T10:14:53Z",
   "expiry_date":"2020-03-13T10:19:53Z",
   "provider_result":"OK",
   "result_date":"2020-05-13T13:43:14Z",
   "authorisation":{
      "token":"01e96e9bd3c2311e63bcb78db32c3be218899cb2068f787adc5281a63c168c77",
      "request_date":"2020-03-13T10:14:53Z",
      "amount":{
         "amount":26473,
         "currency":{
            "code":"978",
            "exponent":2
         }
      },
      "recurring":{
         "frequency_days":30,
         "end_date":"2020-07-11"
      },
      "installments":{
         "maximum":4
      },
      "merchant":{
         "id":"444444",
         "name":"Amazon",
         "country":"276",
         "url":"https://amazon.de"
      }
   },
   "status":"COMPLETE",
   "card":{
      "serial_no":7100047507,
      "masked_pan":"506303******5057",
      "external_ref":"BQA135-1587406272777",
      "token":"9o4y4rP07lT1fM57n6-20042020-10",
      "account":{
         "product_class":"ER_MEX_BENS_MXN",
         "account_no":"44040100376767",
         "external_ref":"20200420191105371248"
      }
   },
   "delegated_result":"AUTHENTICATED",
   "verification_method":"BIOMETRIC"
}

PPS has implemented and is responsible only for API involved in receiving requests by (and sending requests from) PPS object on the diagram.

Endpoint

PATCH: /authorisation-challenges/{challenge_id}

Overview

Update the Challenge instance with the delegated result from the Customer.

Security On Endpoint

Request header X-PPS-CustomerCode can't be null

Flow Diagram

resources/PATCH-1-7b89fd7f-b5fe-49b7-9c0d-1d07c7cc9ba1.png

Step through

  • find authorisation challenge with given Id and Customer code
  • if not happened already, send the challenge result to the 3DS provider

Endpoint

GET: /authorisation-challenges/{challenge_id}

Overview

Get an Authorisation Challenge by id.

Security On Endpoint

Request header X-PPS-CustomerCode can't be null

Flow Diagram

resources/GET-1-45c5c27f-9407-40c0-b442-54c1bdab1be1.png

Step through

  • get Authorisation Challenge by Id and Customer Code

Through set of available actions on exposed endpoint, Customer is also able to manage Card Enrolment entities stored in PPS where each represents status of card's enrolment in 3DS Provider. Every change to PPS entities is immediately being propagated to 3DS Provider. Following requests are possible:

resources/2-all-updated-360ee218-a1d1-472c-8367-49e85b853aae.png

To get details of Card Enrolment (1), Customer has to send GET request with valid HMAC in header to:

https://{pps_base_uri}/3d-secure/api/v1/customers/{customercode}/card-enrolments/{cardserialno}

To Create or update Card Enrolment (2), Customer has to send PUT request with valid HMAC in header to the same URL with example payload:

{
   "language":"sk",
   "contact":{
      "phone_number":"+420774567098",
      "email":"test105@example.com"
   }
}

To update existing Card Enrolment (3), Customer has to send PATCH request with valid HMAC in header to the same URL with example payload:

{
   "language":"sk",
   "contact":{
      "phone_number":"+420774567098",
      "email":"test105@example.com"
   }
}

Response to all of above requests is the same and represents Card Enrolment, for example:

{
    "customer_code": "8114121251",
    "card_serial_no": 1010000479,
    "card_masked_pan": "549826******2777",
    "mode": "ISSUER_CHALLENGE",
    "language": "sk",
    "provider": "STRIPE",
    "contact": {
        "phone_number": "+420774567098",
        "email": "test105@example.com"
    },
    "additional_identifiers": {
        "token": "e15322af-ee36-416e-b0d5-9f77fd24ba28",
        "external_ref": "8114121251-1010000479"
    }
}

PPS has implemented and is responsible only for API involved in receiving requests by (and sending requests from) PPS object on the diagram.

Endpoint

GET: /customers/{customer_code}/card-enrolments/{card_serial_no}

Overview

Get the enrolled Card details

Flow Diagram

resources/GET-2-62dc4a55-6216-493d-917c-e62885e4c965.png

Endpoint

PUT: /customers/{customer_code}/card-enrolments/{card_serial_no}

Overview

Create or update an existing Card Enrolment.

Flow Diagram

resources/PUT-2-5e2b67ef-460e-4717-bd7a-24b19c261146.png

Step through

  • if Card Enrolment doesn't exists then create it and enroll
  • if it exists then enroll if not enrolled yet or just update with provided data

Error codes

  • INVALID ENROLMENT OPERATION (400) - update couldn't be done due to incorrect current card's status
  • CARD NOT ALLOWED FOR ENROLMENT (400)- when Bank Identification Number of the card not matching allowed values for customer
  • ENTITY NOT FOUND FOR_ENROLMENT PROCESS (404)- when associated Enrolment Process couldn't be found
  • CARD NOT FOUND FOR ENROLMENT (404) - when a card couldn't be found

Endpoint

PATCH: /customers/{customer_code}/card-enrolments/{card_serial_no}

Overview

Update an existing Card Enrolment

Flow Diagram

resources/PATCH-2-49f29acd-fd44-445d-b7e9-e3944b22fced.png

Step through

  • update Card Enrolment in 3DS Provider
  • update Card Enrolment in the database

Error codes

  • NO 3DS PROFILE CONFIGURED (400) - when associated Enrolment Process is not configured for 3DS
  • INTERNAL SERVER ERROR (500) - when some other errors found during processing
  • ENTITY NOT FOUND FOR ENROLMENT (404) - when Card Enrolment was not found
  • INVALID PHONE NUMBER ERROR (400) - when the new phone number is invalid

Reviews