Prerequisites: Authentication
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. Redirect the browser to the MPI service.
Step 4. Run a sale.
Before you begin
Authenticate your requests before making API calls. If your request fails, see Errors.
Step 1. Sign up for 3-D Secure
To sign up for 3-D Secure, contact our Customer Support team at cs@payroc.com.
When you sign up for 3-D Secure, provide us with the URL of the page on your website that you want us to send the cardholder to after the 3-D Secure check. We refer to this as the MPI receipt URL.
Each processing terminal can have only one MPI receipt URL. You must include the domain of the website and the path, for example, https://{mydomain}.com/Home/MPIResponse. If you need to change the MPI receipt URL, contact cs@payroc.com.
Step 2. Convert the cardholder’s payment details into a single-use token
Before you can redirect the cardholder to our MPI service, you need to convert the cardholder’s payment details into a single-use token. You send the single-use token when you redirect the cardholder to the MPI service URL in Step 3, and when you run the sale in Step 4.
To create a single-use token, you can use Hosted Fields or you can use our tokenization feature in our API. Single-use tokens expire after 30 minutes.
To run a 3-D Secure check, you need to include the cardholder's email address. Hosted Fields doesn’t capture the cardholder’s email address by default, so you need to capture it as part of your checkout. To extend your Hosted Fields integration to capture an email address, go to Add your own fields.
Step 3. Redirect the browser to the MPI service
Important: Don’t call the MPI service URL from your server.
Set up a client-side redirect that sends the cardholder’s browser to the MPI service URL. In the query parameters of the URL, send the single-use token and information about the transaction.
Before you redirect the cardholder, make sure that you save the single-use token and the transaction details. You need them to run the sale in Step 4.
| Environment | URL |
|---|---|
| Test | https://payments.uat.payroc.com/merchant/mpi |
| Production | https://payments.payroc.com/merchant/mpi |
Query parameters
Include the following query parameters in the MPI service URL:
| 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. |
| 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¤cy=EUR&orderId=25&email=joe%40adomain.com&singleUseToken=1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d
Response fields
After the 3-D Secure check, we redirect the cardholder’s browser to the MPI receipt URL that you provided when you signed up for 3-D Secure. We include the following response fields as query parameters to the MPI receipt URL:
| 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 from your server to our Payments endpoint. Use the same single-use token and transaction details that you sent to the MPI service in Step 3.
Endpoint: https://api.payroc.com/v1/payments
Request parameters
For the paymentMethod object, send values for the following parameters:
- type: Send a value of
singleUseToken. - token: Send the single-use token that you used in Step 3.
For the threeDSecure object, send values for the following parameters:
- serviceProvider: Send a value of
gateway. - mpiReference: Send the MPI reference that we sent to your MPI receipt URL in Step 3.
To create the body of your request, use the following parameters:
Schema (request.body)
Request body schema for POST /payments
Example request
Request
POST https://api.payroc.com/v1/payments
curl -X POST https://api.payroc.com/v1/payments \
-H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"channel": "web",
"processingTerminalId": "4479001",
"order": {
"orderId": "25",
"amount": 100,
"currency": "EUR",
"description": "Large Pepperoni Pizza"
},
"paymentMethod": {
"type": "singleUseToken",
"token": "1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d"
},
"threeDSecure": {
"serviceProvider": "gateway",
"mpiReference": "d01656cf0ec3e62e3754"
},
"operator": "Jane",
"customer": {
"firstName": "Sarah",
"lastName": "Hopper",
"contactMethods": [
{
"type": "email",
"value": "joe@adomain.com"
}
],
"billingAddress": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
},
"shippingAddress": {
"recipientName": "Sarah Hopper",
"address": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
}
}
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}'
Card Payment
import requests
url = "https://api.payroc.com/v1/payments"
payload = {
"channel": "web",
"processingTerminalId": "4479001",
"order": {
"orderId": "25",
"amount": 100,
"currency": "EUR",
"description": "Large Pepperoni Pizza"
},
"paymentMethod": {
"type": "singleUseToken",
"token": "1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d"
},
"threeDSecure": {
"serviceProvider": "gateway",
"mpiReference": "d01656cf0ec3e62e3754"
},
"operator": "Jane",
"customer": {
"firstName": "Sarah",
"lastName": "Hopper",
"contactMethods": [
{
"type": "email",
"value": "joe@adomain.com"
}
],
"billingAddress": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
},
"shippingAddress": {
"recipientName": "Sarah Hopper",
"address": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
}
}
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}
headers = {
"Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
Card Payment
const url = 'https://api.payroc.com/v1/payments';
const options = {
method: 'POST',
headers: {
'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: '{"channel":"web","processingTerminalId":"4479001","order":{"orderId":"25","amount":100,"currency":"EUR","description":"Large Pepperoni Pizza"},"paymentMethod":{"type":"singleUseToken","token":"1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d"},"threeDSecure":{"serviceProvider":"gateway","mpiReference":"d01656cf0ec3e62e3754"},"operator":"Jane","customer":{"firstName":"Sarah","lastName":"Hopper","contactMethods":[{"type":"email","value":"joe@adomain.com"}],"billingAddress":{"address1":"1 Example Ave.","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056","address2":"Example Address Line 2","address3":"Example Address Line 3"},"shippingAddress":{"recipientName":"Sarah Hopper","address":{"address1":"1 Example Ave.","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056","address2":"Example Address Line 2","address3":"Example Address Line 3"}}},"customFields":[{"name":"yourCustomField","value":"abc123"}]}'
};
try {
const response = await fetch(url, options);
const data = await response.json();
console.log(data);
} catch (error) {
console.error(error);
}
Card Payment
package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.payroc.com/v1/payments"
payload := strings.NewReader("{\n \"channel\": \"web\",\n \"processingTerminalId\": \"4479001\",\n \"order\": {\n \"orderId\": \"25\",\n \"amount\": 100,\n \"currency\": \"EUR\",\n \"description\": \"Large Pepperoni Pizza\"\n },\n \"paymentMethod\": {\n \"type\": \"singleUseToken\",\n \"token\": \"1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d\"\n },\n \"threeDSecure\": {\n \"serviceProvider\": \"gateway\",\n \"mpiReference\": \"d01656cf0ec3e62e3754\"\n },\n \"operator\": \"Jane\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"joe@adomain.com\"\n }\n ],\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\n }\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
Card Payment
require 'uri'
require 'net/http'
url = URI("https://api.payroc.com/v1/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"channel\": \"web\",\n \"processingTerminalId\": \"4479001\",\n \"order\": {\n \"orderId\": \"25\",\n \"amount\": 100,\n \"currency\": \"EUR\",\n \"description\": \"Large Pepperoni Pizza\"\n },\n \"paymentMethod\": {\n \"type\": \"singleUseToken\",\n \"token\": \"1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d\"\n },\n \"threeDSecure\": {\n \"serviceProvider\": \"gateway\",\n \"mpiReference\": \"d01656cf0ec3e62e3754\"\n },\n \"operator\": \"Jane\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"joe@adomain.com\"\n }\n ],\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\n }\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body
Card Payment
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;
HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/payments")
.header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"channel\": \"web\",\n \"processingTerminalId\": \"4479001\",\n \"order\": {\n \"orderId\": \"25\",\n \"amount\": 100,\n \"currency\": \"EUR\",\n \"description\": \"Large Pepperoni Pizza\"\n },\n \"paymentMethod\": {\n \"type\": \"singleUseToken\",\n \"token\": \"1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d\"\n },\n \"threeDSecure\": {\n \"serviceProvider\": \"gateway\",\n \"mpiReference\": \"d01656cf0ec3e62e3754\"\n },\n \"operator\": \"Jane\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"joe@adomain.com\"\n }\n ],\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\n }\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}")
.asString();
Card Payment
<?php
require_once('vendor/autoload.php');
$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.payroc.com/v1/payments', [
'body' => '{
"channel": "web",
"processingTerminalId": "4479001",
"order": {
"orderId": "25",
"amount": 100,
"currency": "EUR",
"description": "Large Pepperoni Pizza"
},
"paymentMethod": {
"type": "singleUseToken",
"token": "1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d"
},
"threeDSecure": {
"serviceProvider": "gateway",
"mpiReference": "d01656cf0ec3e62e3754"
},
"operator": "Jane",
"customer": {
"firstName": "Sarah",
"lastName": "Hopper",
"contactMethods": [
{
"type": "email",
"value": "joe@adomain.com"
}
],
"billingAddress": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
},
"shippingAddress": {
"recipientName": "Sarah Hopper",
"address": {
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
}
}
},
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}',
'headers' => [
'Authorization' => 'Bearer <token>',
'Content-Type' => 'application/json',
'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
],
]);
echo $response->getBody();
Card Payment
using RestSharp;
var client = new RestClient("https://api.payroc.com/v1/payments");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n \"channel\": \"web\",\n \"processingTerminalId\": \"4479001\",\n \"order\": {\n \"orderId\": \"25\",\n \"amount\": 100,\n \"currency\": \"EUR\",\n \"description\": \"Large Pepperoni Pizza\"\n },\n \"paymentMethod\": {\n \"type\": \"singleUseToken\",\n \"token\": \"1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d\"\n },\n \"threeDSecure\": {\n \"serviceProvider\": \"gateway\",\n \"mpiReference\": \"d01656cf0ec3e62e3754\"\n },\n \"operator\": \"Jane\",\n \"customer\": {\n \"firstName\": \"Sarah\",\n \"lastName\": \"Hopper\",\n \"contactMethods\": [\n {\n \"type\": \"email\",\n \"value\": \"joe@adomain.com\"\n }\n ],\n \"billingAddress\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n },\n \"shippingAddress\": {\n \"recipientName\": \"Sarah Hopper\",\n \"address\": {\n \"address1\": \"1 Example Ave.\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\",\n \"address2\": \"Example Address Line 2\",\n \"address3\": \"Example Address Line 3\"\n }\n }\n },\n \"customFields\": [\n {\n \"name\": \"yourCustomField\",\n \"value\": \"abc123\"\n }\n ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Card Payment
import Foundation
let headers = [
"Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
]
let parameters = [
"channel": "web",
"processingTerminalId": "4479001",
"order": [
"orderId": "25",
"amount": 100,
"currency": "EUR",
"description": "Large Pepperoni Pizza"
],
"paymentMethod": [
"type": "singleUseToken",
"token": "1a8731f50b02e287ac0529fbce352317c089d4adc1178c1867d65114078791d3c3e13962cbab6b574769dfe9ad5397a5aa67a529ceb0b7be17751f076bbe0e4d"
],
"threeDSecure": [
"serviceProvider": "gateway",
"mpiReference": "d01656cf0ec3e62e3754"
],
"operator": "Jane",
"customer": [
"firstName": "Sarah",
"lastName": "Hopper",
"contactMethods": [
[
"type": "email",
"value": "joe@adomain.com"
]
],
"billingAddress": [
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
],
"shippingAddress": [
"recipientName": "Sarah Hopper",
"address": [
"address1": "1 Example Ave.",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3"
]
]
],
"customFields": [
[
"name": "yourCustomField",
"value": "abc123"
]
]
] as [String : Any]
let postData = JSONSerialization.data(withJSONObject: parameters, options: [])
let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/payments")! as URL,
cachePolicy: .useProtocolCachePolicy,
timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data
let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: \{ (data, response, error) -> Void in
if (error != nil) {
print(error as Any)
} else {
let httpResponse = response as? HTTPURLResponse
print(httpResponse)
}
})
dataTask.resume()
```nse fields
If your request is successful, we create the payment and return a response. The response contains the following fields:
### Schema (`response.body`)
[Response body schema for `POST /payments`](/api/payment)
le response
### Response (201)
```json
{
"paymentId": "M2MJOG6O2Y",
"processingTerminalId": "1234001",
"order": {
"orderId": "OrderRef6543",
"amount": 4999,
"currency": "USD",
"dateTime": "2024-07-02T15:30:00Z",
"description": "Large Pepperoni Pizza"
},
"card": {
"type": "MasterCard",
"entryMethod": "keyed",
"cardNumber": "453985******7062",
"expiryDate": "1230",
"securityChecks": {
"cvvResult": "M",
"avsResult": "Y"
}
},
"transactionResult": {
"status": "ready",
"responseCode": "A",
"type": "sale",
"approvalCode": "OK3",
"authorizedAmount": 4999,
"currency": "USD",
"responseMessage": "OK3"
},
"operator": "Jane",
"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"
}
}
},
"supportedOperations": [
"capture",
"fullyReverse",
"partiallyReverse",
"incrementAuthorization",
"adjustTip",
"setAsPending"
],
"customFields": [
{
"name": "yourCustomField",
"value": "abc123"
}
]
}
Test your integration
To test your integration, use the following test cards with the test MPI service URL.
| Card number | Card brand | Expected outcome | Expected status |
|---|---|---|---|
| 4012000000020071 | Visa | 3-D Secure doesn't challenge the cardholder. | Y - Issuing bank authenticated the cardholder’s identity. |
| 4012000000020089 | Visa | 3-D Secure doesn't challenge the cardholder. | A - Issuing bank attempted to authenticate the cardholder’s identity. |
| 5100270000000023 | Mastercard | 3-D Secure doesn't challenge the cardholder. | Y - Issuing bank authenticated the cardholder’s identity. |
| 4012000000020006 | Visa | 3-D Secure requests authentication from the cardholder. | Y - Issuing bank authenticated the cardholder’s identity. |
| 5100270000000031 | Mastercard | 3-D Secure requests authentication from the cardholder. | Y - Issuing bank authenticated the cardholder’s identity. |
| 4012000000020121 | Visa | 3-D Secure doesn't challenge the cardholder. | N - Issuing bank didn’t attempt to authenticate the cardholder’s identity. |
| 5100270000000056 | Mastercard | 3-D Secure requests authentication from the cardholder. | N - Issuing bank didn’t attempt to authenticate the cardholder’s identity. |
| 5555666666662222 | Mastercard | 3-D Secure doesn't challenge the cardholder. | U - Issuing bank was unable to authenticate the cardholder’s identity. |
If a test card triggers a 3-D Secure challenge, the test MPI service redirects the cardholder’s browser to a simulated authentication page where you need to enter a password. Follow the instructions on the page to enter the password. After you submit the password, we redirect the cardholder’s browser to your MPI receipt URL.