Credit Card Payment with 3DS
Prerequisite
Please contact your relationship manager for the value of orgUnitId
, iss
and secret
.
To proceed with credit card payment in direct model, there are 4 steps required for exchanging payment data to BBMSL Online Payment Gateway and conducting security verification for 3-D Secure (3DS).
There are 3 parties involved in the payment process, i.e., the merchant, BBMSL and Cardinal. The merchant includes both frontend application and backend server depending on the system design. Cardinal is the provider of the 3DS verification service. During the process, payment data will be exchanged over these parties securely. A flow diagram is provided below for reference,
#
1. 3DS Session InitializationBefore proceeding with the payment, a 3DS session is required before requesting to BBMSL Online Payment Gateway. You will need to prepare 3 static values, orgUnitId
, iss
and secret
.
To obtain the SessionId
, you need to place an invisible iframe element on your page for making an HTTP request to Cardinal. The API details are stated below,
- URL:
https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect
- Method:
POST
- Query Parameters:
Parameter | Type | Required/optional | Description |
---|---|---|---|
Bin | string | Required | The card number (PAN). Minimum of first 6-digits |
JWT | string | Required | Generated JWT token |
Bin
We strongly recommend providing the first 9-digits of the PAN, which may increase the authentication success rate.
To generate the JWT token, you may use the following sample code with Java JWT or any external libraries for signing the token,
Below is an example code for requesting Cardinal to submit a form with the above value,
caution
You should embed the above code into an invisible iframe element to request the Cardinal API instead of directly requesting through non-UI code.
You can either use src
or srcdoc
attribute depending on your implementation,
After submitting the form, you will be notified with a JavaScript postMessage
. To proceed to the next step, you must listen to the notification which contains the SessionId
value.
Here is an example code for listening to the event and postMessage
,
Event Listener
The code should be placed outside the iframe to make sure the event can be captured.
You can either use src
or srcdoc
attribute depending on your implementation,
#
2. PayAPI: AuthPass the SessionId
value from the previous session in the field ddcSession
required in PayAPI Auth : /direct/auth
for triggering the sale request through BBMSL. The credit card issuer may require additional authentication from the cardholder, which is indicated in the replied responseCode
. Merchant will need different handling based on the value,
Response Code | Description | Action Required |
---|---|---|
0000 | Payment success | No further action required |
5000 | 3DS Challenge Required, additional object threeDSChallengeDetails will be returned in the response. | Follow the steps below to complete 3DS Challenge |
Others | Payment failed with error | Retry after tackling the error |
As the table mentioned, if the API responds with 0000
, the payment is already succeeded and no further action is needed.
#
3. 3DS ChallengeIf the Auth API responds with 5000
, means the issuing party requires an extra authentication step from the cardholder. The merchant needs to display a webpage to allow inputting verification information. To obtain the webpage, the merchant needs to make an HTTP request to Cardinal with the details provided below,
- URL:
https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp
- Method:
POST
- Query Parameters:
Parameter | Type | Required/optional | Description |
---|---|---|---|
JWT | string | Required | Generated JWT token |
#
Request URL ExampleRequest Parameter
The request parameters are constructed as query parameters instead of the request body as shown in the example.
Similar to 3DS Collect, a signed JWT token is required for obtaining the 3DS Challenge session from Cardinal. The returnUrl
is the URL that will be directed to after the customer completed the 3DS Challenge. The stan
and orderId
will be placed as the query parameters when redirecting to the given returnUrl
. The sample code is attached below,
Cardinal will respond a 3DS challenge webpage from the issuing bank for authentication. Merchant can directly display the Html webpage in the application.
After customers completed the verification process, the browser will be redirected to the provided returnUrl
with the given stan
and orderId
. An example redirects URL of returnUrl='https://merchant-owned-website.com/return'
is given below.
#
4. PayAPI: Complete AuthenticationAfter passing the 3DS Challenge verification step, you need to notify BBMSL that the authentication process is completed. Given the stan
and orderId
from the query parameters mentioned in previous session, merchant need to pass these two values to BBMSL Online Payment Gateway through PayAPI Complete Authentication: /direct/complete-authentication
.
Until this step, the payment process is completed and your order is well recorded by BBMSL. A payment success result notification will also be sent to the merchant's backend URL if provided as well and the application can handle the result accordingly.