3D Flow
In a 3D workflow the account holder has to verify the payment. Once the account holder verifies the payment he/she is redirected back to the merchantRedirectUrl. The merchant then can query the status of payment.
The initial request must contain all the required information:
- - authentication credentials
- - mode, brand , type and amount of transaction
- - merchantRedirectUrl
You can perform the following types of initial payments using our Asynchronous Workflow REST API.
Preauthorization (PA):
Preauthorization request has to be sent to our REST endpoint i.e. /transactionServices/REST/v1/payments
using POST method.
The paymentType
for this request will be PA
.
You can also place a capture transaction request against a successful PA using our Backoffice APIs.
Debit (DB):
With the DB request a successfully authorized transaction gets captured immediately.
Debit request has to be sent to our REST endpoint i.e. /transactionServices/REST/v1/payments
using POST method.
The paymentType
for this request will be DB
.
In our API Specifications you can find a full list of parameters that can be sent in the initial request.
Workflow
1. Send a 3D Payment
After you send the request parameters server-to-server you receive the redirected information with all the parameters for ACS check.
2. Redirect the customer
Redirect the consumer to the ACS page with provided parameters.
3. Get the payment status
Now you can check if the payment was successful.
1. Send a 3D Payment
To start the process, the merchant has to send a server-to-server initial payment request. Here merchantRedirectUrl
has to be url-encoded.
Sample Request
Brand:
curl https://preprod.facilero.com/transactionServices/REST/v1/payments \ curl --header "AuthToken:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA" -d "authentication.memberId=11344" \ -d "authentication.accountId=2967" \ -d "authentication.checksum=d05be538a5e4a771a644a50f9f3c6103" \ -d "authentication.terminalId=1106" \ -d "merchantTransactionId=Rest Transaction05" \ -d "amount=1.00" \ -d "currency=EUR" \ -d "orderDescriptor=Test Transaction" \ -d "shipping.country=UK" \ -d "shipping.city=Aston" \ -d "shipping.state=NA" \ -d "shipping.postcode=CH5 3LJ" \ -d "shipping.street1=19 Scrimshire Lane" \ -d "customer.telnocc=+44" \ -d "customer.phone=07730432996" \ -d "customer.email=john.doe@xyz.com" \ -d "customer.givenName=John" \ -d "customer.surname=Doe" \ -d "customer.ip=192.168.0.1" \ -d "customer.birthDate=19890202" \ -d "card.number=40000000000000002" \ -d "card.expiryMonth=12" \ -d "card.expiryYear=2022" \ -d "card.cvv=237" \ -d "paymentBrand=VISA" \ -d "paymentMode=CC" \ -d "paymentType=DB" \ -d "merchantRedirectUrl=https://www.merchantRedirectUrl.com" \ -d "notificationUrl=www.merchantNotificationUrl.com" \ -d "tmpl_amount=1.00" \ -d "tmpl_currency=EUR" \ -d "customer.customerId=12345" \ -d "attemptThreeD=Only3D" \ -d "deviceDetails.user_Agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:80.0) Gecko/20100101 Firefox/80.0" \ -d "deviceDetails.browserLanguage=en-US" \ -d "deviceDetails.browserTimezoneOffset=-330" \ -d "deviceDetails.browserColorDepth=24" \ -d "deviceDetails.browserAcceptHeader=text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8" \ -d "deviceDetails.browserScreenHeight=654" \ -d "deviceDetails.browserScreenWidth=1366" \ -d "deviceDetails.browserJavaEnabled=true"
Sample Response
Brand:
{ "paymentId": "54288", "paymentType": "DB", "paymentBrand": "VISA", "paymentMode": "CC", "amount": "1.00", "currency": "EUR", "result": { "code": "90026", "description": "ThreeD Authentication Pending" }, "card": { "bin": "400000", "last4Digits": "0002", "holder": "John Doe", "expiryMonth": "12", "expiryYear": "2022" }, "timestamp": "2018-04-02 13:57:24", "transactionStatus": "3D", "tmpl_currency": "EUR", "tmpl_amount": "1.00", "redirect": { "url": "https://0eafstag.cardinalcommerce.com/EAFService/jsp/v1/redirect", "method": "POST", "target": "blank", "parameters": [ { "name": "PaReq", "value": "P.2d9582a044da8bed6368e5b80fbc7f286776c6d0d411d4e80134b15cb1d01645ccfca9b921eefb53bc91c10dd87056c4930f67799fe2c045e95aec40a3b633bac8db7f71911a89c702dfc709f2b9c5d4" }, { "name": "launch3D", "value": "https://0eafstag.cardinalcommerce.com/EAFService/jsp/v1/redirect" }, { "name": "TermUrl", "value": "https://preprod.facilero.com/transaction/PVFrontEndServlet?referenceNo=54288-ETLbewAAAWKFd9ByABRBRVMvQ0JDL1BLQ1M1UGFkZGluZwEAABAAEDbfCLaGsUF0tIb9k5sSbGQAAAAQJQ8k50/iWnb38Ch8ZERu1AAUhc2tKQomHvfhLahnxMENub3xq4I=" }, { "name": "MD", "value": "8a829449603181160160359779187ff0" }, { "name": "creq", "value": "eyJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwibWVzc2FnZVR5cGUiOiJDUmVxIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjOTZhODI5Ny04MGZmLTQ3NjItODA4Yi1jNTFmZTJmNTNlZTQiLCJhY3NUcmFuc0lEIjoiOGZjNDhhZWYtMTcyYS00MDg0LWIzYjUtOTQ0ZDAxZmYwMzBhIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0=" } ] } }
Hashing Rule
Facilero is supporting MD5 Cryptographic Hash for the authenticity of payment request send to the server.
Below is the description of fields used for generating checksum:
- memberId <Merchant ID as shared by Facilero>
- secureKey <Secure Key that can be generated through Facilero's dashboard>
- merchantTransactionId <Unique transaction ID provided by merchant>
- amount <Amount of transaction>
How to generate Checksum?
Checksum has to be calculated with following combination & needs to be send along with the authentication parameters in each server-to-server request:
<memberId>|<secureKey>|<merchantTransactionId>|<amount>
Sample Code
import java.security.MessageDigest def generateMD5Checksum() { String values= "11344|secureKey|RestTransaction01|50.00"; MessageDigest digest = MessageDigest.getInstance(MD5) digest.update(values.bytes); new BigInteger(1, digest.digest()).toString(16).padLeft(32, '0') }
2. Redirect the Customer
The account holder has to be redirected to redirect.url
received in the initial payment response. If any parameters are present in the initial payment response than they should be POST in the redirect. If not, it’s enough to forward it straight to the redirect.url
.
Once the payment has been processed, the customer is redirected to your merchantRedirectUrl
along with a POST parameter resourcePath
.
Sample Request
<form action="<redirectUrl>">
<input type="hidden" name=<name1> value=<value1> >
<input type="hidden" name=<name2> value=<value1> >
...
<input type="hidden" name=<nameN> value=<valueN> >
</form>
Sample Response
def response = { def trackingid = params.trackingid def paymentId = params.paymentId def token = params.token def registrationId = params.registrationId def desc = params.desc def merchantTransactionId = params.merchantTransactionId def paymentBrand = params.paymentBrand def paymentMode = params.paymentMode def amount = params.amount def currency = params.currency def status = params.status def splitTransaction = params.splitTransaction def checksum = params.checksum def descriptor = params.descriptor def mandateid = params.mandateid def tmpl_currency = params.tmpl_currency def tmpl_amount = params.tmpl_amount def resultCode = params.resultCode def resultDescription = params.resultDescription def cardBin = params.cardBin def cardLast4Digits = params.cardLast4Digits def custEmail = params.custEmail def custBankId = params.custBankId def custMerchantId = params.custMerchantId def firstName = params.firstName def lastName = params.lastName def eci = params.eci def timestamp = params.timestamp }
3. Get Payment Status
To get the status of the payment you have to use a GET request. The request goes to the baseUrl + resourcePath and includes the authentication parameters.
resourcePath example:
resourcePath=/transactionServices/REST/v1/payments/{id}
Sample Request
curl https://preprod.facilero.com/transactionServices/REST/v1/inquiry/{id} \ curl --header "AuthToken:eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJjb25tZXJjaGFudDEiLCJyb2xlIjoibWVyY2hhbnQiLCJpc3MiOiJQWiIsImV4cCI6MTUwMTE0NjY0MX0.TFmGGKDUgkktmZQvrUTeox1buH1J6lgBVE3Mcy8OVjA" -d "authentication.memberId=11344" \ -d "authentication.checksum=c6e1268421b9b79fffe855b15f256538" \ -d "paymentType=IN" \ -d "idType=PID"
Sample Response
{ "paymentId": "34265", "status": "capturesuccess", "paymentBrand": "VISA", "paymentMode": "CC", "amount": "50.50", "firstName": "John", "lastName": "Doe", "currency": "EUR", "tmpl_amount": "50.50", "tmpl_currency": "EUR", "merchantTransactionId": "425845651", "eci": "05", "result": { "code": "00001", "description": "Your record is found" }, "card": { "bin": "411111", "last4Digits": "1111", "holder": "Jon Doe", "expiryMonth": "12", "expiryYear": "2018" }, "customer": { "email": "john.d@.com", "bankId": "AD345345", "id": "45345345" }, "timestamp": "2016-06-24 23:15:15", "remark": "Transaction succeeded | Approved or completed successfully", "transactionStatus": "Y", "descriptor": "TestBillingDescriptor" }
Hashing Rule for Get Status
Facilero is supporting MD5 Cryptographic Hash for the authenticity of payment request send to the server.
Below are the description of fields used for generating checksum:
- memberId <Merchant ID as shared by Facilero>
- secureKey <Secure Key that can be generated through Facilero's dashboard>
- paymentId <Id of previous transaction>
How to generate Checksum?
Checksum has to be calculated with following combination.
<memberId>|<secureKey>|<paymentId>
Standard Notification/ Callback
Checksum has to be calculated with following combination.
<paymentId>|<merchantTransactionId>|<amount>|<short status of transaction>|<secret key>
Example :
77251|011E1D8A5C034|156.00|N|<merchant secret key>
Sample Code
import java.security.MessageDigest def generateMD5Checksum() { String values= "11344|secureKey|54303|1.00"; MessageDigest digest = MessageDigest.getInstance(MD5) digest.update(values.bytes); new BigInteger(1, digest.digest()).toString(16).padLeft(32, '0') }
Payment Modes and Brands
Below are the list of payment brands for asynchronous workflow which requires the payment data.