3D Secure Configuration

3D Secure (3DS) is a security protocol designed to authenticate cardholders during online transactions, reducing fraud. The process involves the cardholder, merchant (via the acquirer), and card issuer.

On the acquiring side, acquirers must integrate to a Merchant Plug-In (MPI) to facilitate communication between the merchant's systems, card networks, and issuers during the 3D Secure authentication process.

On the issuing side, issuers must operate or integrate to an Access Control Server (ACS) to handle authentication requests from the 3D Secure process, verifying the cardholder's identity and communicating the results back to the acquirer via the card networks. Issuers use OTPs, in-app verification, biometrics, or risk-based authentication to verify identities.

Eclipse supports end-to-end enablement of 3DS for both the acquiring side (via MPI integrations such as Wibmo) and the issuing side (via ACS integrations). The specific integration depends on whether Eclipse is acting as acquirer, issuer, or both for the tenant.

Supported 3DS Providers

Role	Provider	Tenant Config Key	Value
Acquirer (MPI)	Wibmo 3DS	`threeDSProvider`	`wibmo`

Additional MPI and ACS providers are available — contact EFTCorp for details on integrating alternative providers.

Acquirer-Side Enablement

Wibmo 3DS MPI

Wibmo 3DS provides a user-friendly interface for completing customer transaction verifications.

Step 1: Enable the Wibmo 3DS provider

Set the following tenant config item:

Key	Value
`threeDSProvider`	`wibmo`

Step 2: Initiate a 3DS payment

The caller initiates a payment with type set to ZA_THREE_DS and paymentMechanism set to CARD:

- POST /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments

{
  "amount": 100,
  "currency": "ZAR",
  "externalUniqueId": "a512aabc11a",
  "type": "ZA_THREE_DS",
  "landingUrl": "https://www.google.com/",
  "paymentMechanism": "CARD"
}

Step 3: Redirect the cardholder

The Wibmo 3DS customer authentication journey is served through the completionUrl returned in the response. The calling application must redirect the cardholder's browser or webview to this URL to complete authentication. Once the cardholder completes the challenge, they are redirected to the landingUrl specified in the request.

Step 4: Check payment status

After the cardholder completes authentication, poll the payment status endpoint or handle the callback to determine whether the payment succeeded or failed.

{
  "paymentId": 16572,
  "externalUniqueId": "a512aabc11a",
  "status": "PENDING",
  "amount": 100.000000000,
  "currency": "ZAR",
  "additionalFields": [
    
  ],
  "acceptedCardSchemes": [
    
  ],
  "cardPhone": "279726999279",
  "phone": "279726999279",
  "acceptedPaymentMechanisms": [
    
  ],
  "completionUrl": "https://eclipse-java-develop.ukheshe.rocks/t/8BM4D",
  "paymentType": "CARD",
  "created": "2024-10-18T11:58:27.000Z",
  "paymentInstrumentInfo": {
    "cardPhone": "279726999279"
  },
  "fee": 0,
  "customerId": 25,
  "paymentTerminalData": {
    
  },
  "tracingContext": "00-8eb82bd0cca62e57dd1aee65648b8475-892405b22ba9396e-01"
}

The key response fields for the 3DS flow are:

Field	Description
`paymentId`	Eclipse payment ID — use this to poll for the final payment status
`status`	Initially `PENDING` — transitions to `SUCCESSFUL` or `FAILED` after authentication
`completionUrl`	Redirect the cardholder to this URL to complete the 3DS challenge
`tracingContext`	OpenTelemetry W3C trace context — include in support tickets for distributed tracing

Checking payment status after 3DS:

GET /eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/payments/{paymentId}
Authorization: Bearer <JWT>

A status of SUCCESSFUL indicates the cardholder authenticated and the payment was processed. A status of FAILED or ERROR indicates the authentication or payment was declined.