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:

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

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

Example request

curl --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

{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}

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.

curl
-H "Content-Type: application/json"
-H "Authorization: <Bearer token>"
-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. Test endpoint: https://payments.uat.payroc.com/merchant/mpi
Production endpoint: https://payments.payroc.com/merchant/mpi

Query parameters

Parameter	Type	Required?	Description
processingTerminalId	string	Yes	Unique identifier that we assigned to the terminal.
singleUseToken	string	Yes	Unique token that the gateway assigned to the payment details.
email	string	Yes	Cardholder’s email address.
amount	number <double>	Yes	Total amount of the transaction, which includes surcharges. The value is in the currency’s lowest denomination, for example, cents.
currency	string	Yes	ISO-4217 currency code of the transaction.
orderId	string	Yes	Unique identifier that the merchant assigns to the order.
cardholderChallenge	string	No	Indicates 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.

Field	Description
result	Indicates 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.
mpiReference	MPI reference of the 3-D Secure check.
orderId	Unique identifier that the merchant assigned to the order.
status	Status 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.
eci	Response 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. Test endpoint: https://api.uat.payroc.com/v1/payments
Production endpoint: https://api.payroc.com/v1/payments 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:

Header parameters

Body parameters

Example request

Request

curl --request post \
	--url https://api.payroc.com/v1/payments \
	--header 'Authorization: Bearer <access token>' \
	--header 'Content-Type: application/json' \
	--header 'Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324' \
	--data '{"channel":"web","processingTerminalId":"1234001","operator":"Postman","order":{"orderId":"OrderRef6543","description":"Large Pepperoni Pizza","currency":"USD","amount":4999},"customer":{"firstName":"Sarah","lastName":"Hopper","billingAddress":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"shippingAddress":{"recipientName":"Sarah Hopper","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"}}},"paymentMethod":{"type":"card","cardDetails":{"entryMethod":"keyed","keyedData":{"dataFormat":"plainText","device":{"model":"paxA80","serialNumber":"WPC202833004712"},"expiryDate":"1225","cardNumber":"4539858876047062"}}},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'

Response fields

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

Response Schema

Status Code 201

Successful request. We processed the transaction.

Response headers

Response body

Example response

Response

application/json

{
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "operator": "Postman",
  "order": {
    "orderId": "OrderRef6543",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "amount": 4999,
    "currency": "USD"
  },
  "customer": {
    "firstName": "Sarah",
    "lastName": "Hopper",
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "state": "Illinois",
      "country": "US",
      "postalCode": "60056"
    },
    "shippingAddress": {
      "recipientName": "Sarah Hopper",
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      }
    }
  },
  "card": {
    "type": "MasterCard",
    "entryMethod": "keyed",
    "cardNumber": "453985******7062",
    "expiryDate": "1225",
    "securityChecks": {
      "cvvResult": "M",
      "avsResult": "Y"
    }
  },
  "supportedOperations": [
    "capture",
    "fullyReverse",
    "partiallyReverse",
    "incrementAuthorization",
    "adjustTip",
    "setAsPending"
  ],
  "transactionResult": {
    "type": "sale",
    "status": "ready",
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK3"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ]
}

Run a sale with 3-D Secure

Example request

Example response

Header parameters

Body parameters

Response Schema

Status Code 201

Response headers

Response body