External 3DS with your own MPI

If you authenticate the payer with your own MPI (merchant plug-in) or 3DS Server, you can send the 3-D Secure (3DS) result together with the payment in the mpi_data object. Payment Platform then does not start the MPI service configured for your account and passes your values to the acquirer.

External 3DS works on S2S CARD SALE requests, with acquirers that support 3DS data from an external MPI.

Before you start

Your own MPI. Use mpi_data only if you authenticate the payer before you send the payment. Without your own MPI, Payment Platform handles 3DS as described in Redirect / 3DS handling.
Protocols and requests. S2S CARD action=SALE, including a SALE with recurring_init=Y that starts a recurring chain, with or without schedule_id. Checkout, Hosted Payment Fields, the SDKs, and other actions do not support mpi_data.
Authorization. With auth=Y, Payment Platform ignores mpi_data without an error and processes the payment as if you had not sent it.
Wallet payments. With payment_token (Apple Pay or Google Pay), the acquirer receives the wallet data, not your mpi_data values.

Acquirer support

Your values reach the acquirer only if it supports 3DS data from an external MPI. Check with your account manager which of your acquirers support it before you go live.

How it works

Authenticate the payer with your MPI. It returns the ECI, the authentication value (CAVV or AAV), the Directory Server transaction ID, the 3DS version and, if available, the authentication status.
Decide whether to send the payment. If your MPI returns N or R, the payer is not authenticated. Payment Platform does not decline a payment because of trans_status: the acquirer and the issuer decide.
Send the SALE request with the usual parameters and the mpi_data object. Payment Platform checks the format of the fields.
Payment Platform sends the payment to the acquirer. If the acquirer supports 3DS data from an external MPI, your values go with the payment.
You receive the result in the response and in the callback, as for any other SALE.

Keep your REDIRECT handling

An acquirer without this support can still run its own 3DS, and the response then returns result = REDIRECT. Handle REDIRECT and send term_url_3ds as for any SALE.

The `mpi_data` object

Send the fields as mpi_data[field]. If you send the object, eci, authentication_value, ds_trans_id, and 3ds_version are required. The full schema is in Sale / Authorization.

Parameter	Required	Format	Description
`mpi_data[eci]`	Yes	Exactly 2 characters	Electronic Commerce Indicator returned by your MPI. Visa, Amex, and JCB use `05` for fully authenticated, `06` for attempted, and `07` for not authenticated. Mastercard uses `02`, `01`, and `00` for the same outcomes.
`mpi_data[authentication_value]`	Yes	From 28 to 64 characters	Authentication value from your MPI, Base64 encoded: CAVV for Visa, AAV (UCAF) for Mastercard. Payment Platform checks the length only.
`mpi_data[ds_trans_id]`	Yes	UUID	Directory Server transaction ID (dsTransID) of the authentication.
`mpi_data[3ds_version]`	Yes	`X.Y.Z`, 1 or 2 digits in each part	3DS protocol version of the authentication, for example `2.2.0`.
`mpi_data[trans_status]`	No	One uppercase letter	Authentication result (transStatus) from the Directory Server or the ACS.
`mpi_data[xid]`	No	Up to 64 characters	Transaction identifier from 3DS 1. Leave it out for 3DS 2.

Send trans_status whenever your MPI returns it: without it, some acquirers do not receive your 3DS values.

`trans_status`	Meaning
`Y`	Authenticated
`A`	Attempted
`N`	Not authenticated
`U`	Authentication unavailable
`C`	Challenge required
`R`	Rejected by the issuer
`D`	Decoupled authentication
`I`	Informational only

Example request

Calculate the hash as for any SALE, with Formula 1. The mpi_data fields are not part of it. Send the fields URL-encoded: otherwise a + in the authentication value arrives as a space.

curl https://{PAYMENT_URL}/post \
  --data-urlencode "action=SALE" \
  --data-urlencode "client_key=c2b8fb04-110f-11ea-bcd3-0242c0a85004" \
  --data-urlencode "order_id=ORDER-12345" \
  --data-urlencode "order_amount=1.99" \
  --data-urlencode "order_currency=USD" \
  --data-urlencode "order_description=Product" \
  --data-urlencode "card_number=4111111111111111" \
  --data-urlencode "card_exp_month=01" \
  --data-urlencode "card_exp_year=2030" \
  --data-urlencode "card_cvv2=000" \
  --data-urlencode "payer_first_name=John" \
  --data-urlencode "payer_last_name=Doe" \
  --data-urlencode "payer_address=Big street" \
  --data-urlencode "payer_country=US" \
  --data-urlencode "payer_city=City" \
  --data-urlencode "payer_zip=123456" \
  --data-urlencode "[email protected]" \
  --data-urlencode "payer_phone=199999999" \
  --data-urlencode "payer_ip=123.123.123.123" \
  --data-urlencode "term_url_3ds=https://client.site.com/return.php" \
  --data-urlencode "mpi_data[eci]=05" \
  --data-urlencode "mpi_data[authentication_value]=AAABCZIhcQAAAABZlyHRAAAAAAA=" \
  --data-urlencode "mpi_data[ds_trans_id]=6468f138-4287-4df5-a0d4-cbc48b157b49" \
  --data-urlencode "mpi_data[3ds_version]=2.2.0" \
  --data-urlencode "mpi_data[trans_status]=Y" \
  --data-urlencode "hash=<your hash>"

Validation errors

Payment Platform checks the format of the fields, not their values. For example, mpi_data[eci]=99 passes. A missing required field or a wrong format returns an error that names the field:

{
  "result": "ERROR",
  "error_code": 100000,
  "error_message": "Request data is invalid.",
  "errors": [
    {
      "error_code": 100000,
      "error_message": "mpi_data[eci]: This value should have exactly 2 characters."
    }
  ]
}

Where the 3DS data shows up

Payment Platform stores your values when the payment is settled or declined:

Callback. The 3DS attributes dsTransID, xid, transStatus, eci, and protocolVersion carry the values you sent, once they are enabled in Protocol Mapping (Add Data to Callback). authentication_value is not returned. If the acquirer returns its own 3DS data, those values replace yours. See 3DS authentication attributes.
Admin panel. The same values appear in the 3DS data of the transaction details.

Compared with 3DS by Payment Platform

	3DS by Payment Platform	3DS with your own MPI
Who authenticates the payer	Payment Platform, through the acquirer or through an MPI service configured for your account.	You, through your own MPI.
What you send	A regular payment request.	The payment request plus the `mpi_data` object.
Payer not authenticated	Payment Platform can stop the payment, or the acquirer declines it.	The acquirer and the issuer decide.

Without mpi_data, the response returns result = REDIRECT when the payer has to complete authentication. See Redirect / 3DS handling. If the MPI service configured for your account reports that the payer is not authenticated, Payment Platform stops the payment: the response returns result = ERROR with error_code 204021, or the payment is declined with the reason MPI session response code is not authenticated. To find out whether an MPI service can be set up for your account, contact your account manager.

What's next

Redirect / 3DS handling for 3DS run by Payment Platform.
Sale / Authorization for the full request schema.
S2S Card overview for PAYMENT_URL, the request format, and the callback model.

Before you start​

How it works​

The mpi_data object​

Example request​

Validation errors​

Where the 3DS data shows up​

Compared with 3DS by Payment Platform​

What's next​