3D Secure API

1. URL

https://portal.xpresswash.net/rest/v1/transactions

Your API key is: iTsMykEy

The next table describes the request parameters to perform a payment

Field Value Requirement Note
key Alphanumeric API key (64 characters) Required API access key
first_name First Name Required ex. Beverly
last_name Last Name Required ex. Brower
email Email address (100 characters) Required Email address
address Address Required ex. 4987 Asylum Avenue
birthday Date of Birth Required ex. 1983-12-31
country Country Required ex. USA (2 or 3 characters)
name Card Holder Name Required ex. Beverly C. Brower
type Card Type Required 1- Amex
2 - Visa
3 - Mastercard
4 - Discover
number Cardholder's Card Number Required
month Cardholder's Expiry Month (1-2 digits) Required
year Cardholder's Expiry Year (2 digits) Required
cvv Cardholder's Security Code (3-4 digits) Required
phone Cardholder's Phone Number Required This field only accepts numeric strings between 5 and 15 characters long
amount Valid Dollar Amount (2 decimal places) Required ex. 25.00
currency ISO 4217 Currency code that indicates the currency of the transaction Optional (if not specified, processing will default to USD) ex. USD, GBP, EUR
state Cardholder's State/Province/Region of Residence (USA/Canada: 2 characters, Other: 20 characters) Required
city Cardholder's City of Residence (50 characters) Required
zip Cardholder's ZIP or Postal Code (10 characters) Required
orderid Order number specified by you (100 characters) Optional
subscription_status RECURRING FUNCTION optional - if you want to re-bill the client every X period 0=>'None',1=>'Monthly',2=>'Weekly',3=>'Daily',4=>'Quarterly',5=>'Yearly',6=>'5 days',7=>'100 days',8=>'180 days'
ip IPv4 Address of Customer Required

The next table describes the fields returned in the responses.

Field Example
id 28550
status DECLINED, APPORVED, PENDING, AWAITING FOR 3DS VERIFICATION
date Nov 30, 2017 8:44:45 AM
ext_order_id 2UD5UIK9S
information_data R0000:High risk
information_code R0000
descriptor Pay*systempro

Sample Code (PHP):

$url = "https://portal.xpresswash.net/rest/v1/transactions";
$key = "iTsMykEy";

// Fill with real customer info

$data = [
'Authorization' => base64_encode($key),
'userData' => [
'first_name' => 'Beverly',
'last_name' => 'Brower',
'email' => 'test@test.com',
'address' => '123 Coffe Berry Lane',
'country' => 'USA', // 3 characters long
'state' => 'CA',
'city' => 'Anaheim',
'zip' => '92803',
'phone' => '8881234567', // This field only accepts numeric strings between 5 and 15 characters long
'address1' => '',
'ip' => '192.168.0.1',
'birthday' => '1983-02-22',
'username' => '',
],
'cardData' => [
"name" => 'Beverly Brower',
"type" => '2',
"number" => '4242424242424242',
"month" => '12',
"year" => '2018',
"cvv" => '123',
],
'subscription_status' => 0, // 0=>'No RECURRING',1=>'Monthly',2=>'Weekly',3=>'Daily',4=>'Quarterly',5=>'Yearly',6=>'5 days',7=>'100 days',8=>'180 days'
'amount' => '20.00', // set your amount in format 99.99
'currency' => 'GBP', // ISO 4217 Currency code that indicates the currency of the transaction
'ext_order_id' => '123'
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER,
array('Authorization: Basic '.base64_encode($key), 'Content-Type: application/json'));
$response = curl_exec($curl);

curl_close($ch);
2. Callback

Callbacks, also known as “WEBHOOKS”, notify your platform and users of any STATUS changes, helping complete the information loop when using service. Callbacks are a useful way of notifying you when a transaction status has changed. For example; if a “Pending” transaction’s status has changed (one which hasn’t been processed), we will POST a JSON payload with the Item object attributes to the URL provided.

1. You need setup your callback URL. Pass a valid HTTP URL that will accept a POST request.

2. To catch the callback during sandbox mode, we recommend using a service such as http://requestb.in.

3. List of POST filds for callback

ID Transaction ID
Status Current transaction status ('PENDING','APPROVED','DECLINED','CANCELED','CAPTURED','REFUNDED','CHARGEBACK')
Date and time

4. You have ability to check transaction information yourself. Example of code:

$url = "https://portal.xpresswash.net/rest/v1/transactions/123456"; // transaction ID
$merchant_key_gw = "iTsMykEy";

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Authorization: Basic '.base64_encode($merchant_key_gw), 'Content-Type: application/json'));
$response = curl_exec($curl);
$result = json_decode($response, true);
print_r($result);
3. 3D Secure

If the MID you are assigned is 3D Secure or requires the customer to be redirected to the bank's secure page to fill in credit card details, you'll receive the following status= "PROCESSING - PENDING VERIFICATION". This is a token response from a secure payment URL where the customer is redirected to either:

a) Enter their Credit Card Number, Expiry and CVV (Secure Bank Checkout)
b) Enter their Verified by Visa or Mastercard SecureCode Password / PIN (3D Secure)

The redirect will happen in a new window.

Upon validating the information submitted, the transaction will either be APPROVED or DECLINED.

The "PROCESSING - PENDING VERIFICATION" should only appear for no more than 60-120 seconds per transaction. If a transaction is stuck with that error, this means the customer exited out of the Secure Checkout page and chose to not complete the transaction.

Note: If you are processing transactions manually using a Secure Bank Checkout MID, please make sure to use an IP Address which matches the Cardholder's Billing Country. We recommend a VPN such as: IP Vanish, NordVPN, HideMyAss, etc. - only the Country IP needs to match, not the State/ZIP as the bank uses Maxmind minFraud to asses risk.

In case if card needs to be verified by 3DS, you'll receive status='PROCESSING - PENDING VERIFICATION', token of a payment 3ds_url - Address to which customer should be redirected for verification with 3DS.

After you need check status of transaction. Example of code:

$merchant_key_gw = "iTsMykEy";
$url = "https://portal.xpresswash.net/rest/v1/transactions/XXXXX?Authorization=".base64_encode($merchant_key_gw);

//XXXXX - transaction ID

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($curl);
$result = json_decode($response, true);
print_r($result);