Integrate3-D Secure

Run a sale with 3-D Secure

Use our 3-D Secure feature to verify a cardholder’s identity during an e-Commerce transaction.

Integration steps

Step 1. Sign up for 3-D Secure.
Step 2. Convert the cardholder’s payment details into a single-use token.
Step 3. Send a merchant plug-in (MPI) request.
Step 4. Include the MPI reference in a payment request.

Before you begin

Bearer tokens

Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate a Bearer token, complete the following steps:

  1. Include your API key in the x-api-key parameter in the header of a POST request.
  2. Send your request to https://identity.payroc.com/authorize.

Note: You need to generate a new Bearer token before the previous Bearer token expires.

Example request

1curl --location --request POST  'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

Example response

1{
2  "access_token": "eyJhbGc....adQssw5c",
3  "expires_in": 3600,
4  "scope": "service_a service_b",
5  "token_type": "Bearer"
6}

Headers

To create the header of each POST request, you must include the following parameters:

  • Content-Type: Include application/json as the value for this parameter.
  • Authorization: Include your Bearer token in this parameter.
  • Idempotency-Key: Include a UUID v4 to make the request idempotent.
1curl
2  -H "Content-Type: application/json"
3  -H "Authorization: <Bearer token>"
4  -H "Idempotency-Key: <UUID v4>"

Errors

If your request is unsuccessful, we return an error. For more information about errors, see Errors.

Step 1. Sign up for 3-D Secure

To sign up for 3-D Secure, contact our Customer Support team at [email protected].

We use request forwarding to send you the results of the 3-D Secure check. When you sign up for 3-D Secure, provide a URL that we forward the requests to.

Step 2. Convert the cardholder’s payment details into a single-use token

Before you can send a request to our MPI service, you need to convert the cardholder’s payment details into a single-use token.

To create a single-use token, you can use Hosted Fields or you can use our tokenization feature in our API.

Step 3. Send an MPI request

Send the single-use token to our MPI service with information about the transaction in the query parameters.

Query parameters

ParameterTypeRequired?Description
processingTerminalIdstringYesUnique identifier that we assigned to the terminal.
singleUseTokenstringYesUnique token that the gateway assigned to the payment details.
emailstringYesCardholder’s email address.
amountnumber <double>YesTotal amount of the transaction, which includes surcharges. The value is in the currency’s lowest denomination, for example, cents.
currencystringYesISO-4217 currency code of the transaction.
orderIdstringYesUnique identifier that the merchant assigns to the order.
cardholderChallengestringNoIndicates if the merchant wants the issuing bank to challenge the cardholder. Send one of the following values:
• REQUIRED - Merchant wants the issuing bank to challenge the cardholder.
• OPTIONAL - Issuing bank decides whether to challenge the cardholder.

Example request

https://payments.payroc.com/merchant/mpi?processingTerminalId=4479001&amount=100&currency=EUR&orderId=25&email=joe%40adomain.com&singleUseToken=1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d

Response fields

If your request is successful, we send a GET request to your MPI receipt URL with the results of the 3-D Secure check and the MPI reference. The response fields are in the query parameters of the GET request.

FieldDescription
resultIndicates the result of the 3-D Secure check. We return one of the following values:
• A - The issuing bank approved the transaction.
• D - The issuing bank declined the transaction.
mpiReferenceMPI reference of the 3-D Secure check.
orderIdUnique identifier that the merchant assigned to the order.
statusStatus of the 3-D Secure check. We return one of the following values:
• A - Issuing bank attempted to authenticate the cardholder’s identity.
• N - Issuing bank didn’t attempt to authenticate the cardholder’s identity.
• U - Issuing bank was unable to authenticate the cardholder’s identity.
• Y - Issuing bank authenticated the cardholder’s identity.
eciResponse code from 3-D Secure. We return one of the following values:
• 05 - Issuing bank used 3-D Secure to authenticate the cardholder.
• 06 - Issuing bank or cardholder is not enrolled for 3D Secure.
• 07 - 3-D Secure check failed.

Example response

https://{MPI_RECEIPT_URL}?result=A&status=A&eci=06&mpiReference=d01656cf0ec3e62e3754&orderId=25

Step 4. Run a sale

To run a sale, send a POST request to our Payments endpoint.

In your request, send the following parameters in the threeDSecure object:

  • serviceProvider – Provide a value of gateway.
  • mpiReference – Provide the MPI reference that we sent your MPI receipt URL in Step 2.

Request parameters

To create the body of your request, use the following parameters:

Example request

Response fields

If your request is successful, we create the payment and return a response. The response contains the following fields:

Example response