External 3DS MPI

This document describes how to use your own MPI with our credit card processing API.


Advanced feature

This is an advanced feature that requires custom setup on our end. Please contact your account manager before integrating this feature.


PCI-DSS Required

Since you will be handling card information yourself, you will need to obtain a PCI-DSS certification in order to use this feature.

If you have your own internal 3DS MPI or are using an orchestration platform which centralizes your 3DS logic, then this guide describes how you can use KOMOJU to process the payment, but maintain control over your 3DS flow.

When using External 3DS, you will not be relying on our 3DS system but will instead use your own. Customers will be redirected to the page provided by your MPI. After obtaining the verification values, you can pass these to our API to authorize the payment.

Example API Call

  "capture": true,
  "currency": "JPY",
  "payment_details": {
    "type": "credit_card",
    "number": "4111111111111111",
    "month": 1,
    "year": 2027,
    "verification_value": "111",
    "custom_three_d_secure_params": {
      "version": "2.1.0",
      "eci": "05",
      "authentication_value": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
      "ds_transaction_id": "abb0cb6e-4d36-11ee-be56-0242ac120002",
      "three_ds_server_transaction_id": "6afa6072-9412-446b-9673-2f98b3ee98a2"
  "amount": 1000

In order to use this feature, the additional parameters need to be added to the Payments call. The additional parameters can be found under custom_three_d_secure_params

Parameter Name
versionThe version of 3DS being applied. This is returned by your MPI and usually defined as messageVersion.
eciPayment System specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. Defined by the DS.
authentication_valuePayment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication.
ds_transaction_idUniversal unique transaction identifier assigned by the DS to identify a single transaction, often defined as dsTransID.
three_ds_server_transaction_idUniversal unique transaction identifier assigned by the 3DS Server to identify a single transaction.


You will need to correctly configure your MPI to use the relevant Acquirer BIN and MID values. Since these values are depending on the merchant account being used, please contact your account manager to obtain these values.

Example parameters from 3DS MPI

Most 3DS MPI services will return these parameters in the API responses after a successful authentication. An example can be found below with the description of these parameters.