Merchants using 3rd party gateways

AceProtect’s fraud score API provides the possibility of getting the ML fraud score and the fraud status (accept, reject, trigger 3DS or manual review) just before performing the payment with the Payment Gateway.
The next picture shows the process to follow:

Step 1 - Create Fraud Score

The merchant will send the transaction data, consumer data and any other custom parameters before sending the payment request.
The Merchant submits a fraud score request to the AceHub /fraudscore endpoint.

{
	"header": {
		"businessId": "999999"
	},
	"body": {
		"card": {
			"holderName": "John Doe",
			"number": "4111111111111111",
			"expiryMonth": 12,
			"expiryYear": 2020,
			"cvvPresent": true
		},
		"customer": {
			"customerId": "myCustomerId",
			"email": "john.doe@company.com",
			"givenName": "John",
			"familyName": "Doe",
			"birthDate": "1983-08-01",
			"phoneNumber": "19009990000",
			"mobileNumber": "16879991234",
			"companyName": "Company.com",
			"identificationTypeId": 3,
			"identificationNumber": "123456789Z",
			"ipAddress": "12.45.78.90",
			"type": 1,
			"taxNumber": "A987654321",
			"httpUserAgent": "Mozilla Firefox Ultimate",
			"deviceType": 1
		},
		"transaction": {
			"trackingCode": "7F4BFD5D-55E4-4775-81F7-0784188876C7",
			"amount": 1000.65,
			"currencyCode": "EUR",
			"methodId": 1,
			"authorizationMode": "payment",
			"type": "SINGLE",
			"source": "EC",
			"countryCode": "US",
			"languageCode": "EN",
			"sessionId": "123456789"
		}
	}
}

Fraud Score Response

AceHub responds with a fraud score and a field called fraud status indicating the recommendation over the order (accept, reject, trigger 3DS or manual review).

Also, in the response it is included an unique id body.transaction.scoreId which it will be used later to perform the payment.

{
	"header": {
		"requestTimestamp": "2018-02-26T11:21:41.7268985Z"
	},
	"result": 0,
	"description": "Ok",
	"body": {
		"transaction": {
			"scoreId": "e7a246e1-a428-40e4-85d1-089493b2c7fb",
			"trackingCode": "7F4BFD5D-55E4-4775-81F7-0784188876C7"
		},
		“fraud”: {
			"score": 0.65,
			"statusCode": 4,
			"statusDescription": "REVIEW",
			“modelLearning": "true"
		}
	}
}

Step 2 - Take a decision

Once the merchant has received the fraud score and the fraud status, the merchant needs to evaluate this information in order to take a decision (go, no-go) with the order. The score is a value between 0 and 1 that it is informative. The decision must be taken using fraud status field. Depending on this field four decision can be taken:

Accept: merchant can proceed with the payment as the order is considered genuine
Reject: merchant should stop the order as the payment is considered fraudulent
Trigger 3D Secure: as the order is considered suspicious it is recommended that the payment is performed using 3D secure in order to protect the merchant
Manual Review: the order will be evaluated in a manual review queue by a fraud analyst. Depending on the business model and the goods/service, you may perform the 'payment' and once it is validated the 'capture' will follow.

Model Learning

Fraud score API returns a boolean flag called "modelLearning". We recommend merchant to
start using fraud status field to take the decision over the transaction if API returns "modelLearning" as "false".

Step 3 - Perform the payment

In case that the merchant has decided to perform the payment (with 3D Secure or not), the merchant needs to submit a standard request to your payments service.

If you are using Acapture you may want to have a look at the AceProtect for Acapture merchant's Guide.

Step 4 - Send the result of the payment

Once you have performed the transaction, you should inform AceProtect about the result of this transaction by sending a payment event to /fraudScores/{scoreId}/payment. You can see the full API reference for payment event here. AceProtect's machine learning model uses this information to learn and adapt to the fraud scenarios in real-time.

When you submit an event, you will need to work with a fraudScores operation identified by the scoreId that we previously mentioned in Step 1.

https://stagconnect.acehubpaymentservices.com/gateway/v3/fraudscores/

{
 "header": {
  "businessId": "500210004"
 },
 "body": {
   "transaction": {
   "trackingCode": "7F4BFD5D-55E4-4775-81F7-0784188876C7",
   "amount": 1000.65,
   "currencyCode": "EUR",
   "methodId": 1,
   "authorizationMode": "payment",
   "type": "SINGLE",
   "source": "EC",
   "countryCode": "US",
   "languageCode": "EN",
   "sessionId": "123456789"
  },
  "card": {
   "holderName": "John Doe",
   "number": "4111111111111111",
   "expiryMonth": 12,
   "expiryYear": 2020,
   "cvvPresent": true
  },
  "customer": {
   "customerId": "myCustomerId",
   "email": "john.doe@company.com",
   "givenName": "John",
   "familyName": "Doe",
   "birthDate": "1983-08-01",
   "phoneNumber": "19009990000",
   "mobileNumber": "16879991234",
   "companyName": "Company.com",
   "identificationTypeId": 3,
   "identificationNumber": "123456789Z",
   "ipAddress": "12.45.78.90",
   "type": 1,
   "taxNumber": "A987654321",
   "httpUserAgent": "Mozilla Firefox Ultimate",
   "deviceType": 1,
   "billingAddress": "6th Ave, New York, NY, USA",
   "shippingAddres": "6th Ave, New York, NY, USA"
  }
 }
}

Payment response

In all those cases you will receive a response indicating the status of your request. Basically, you only need to know that everything has gone ok (that is to say that you get a 200 OK status code) and that AceProtect has received the message.

{
	"header": {
		"requestTimestamp": "2018-02-26T11:21:41.7268985Z"
	},
	"result": 0,
	"description": "Ok"
}

Step 5* - Dependent transactions

In many cases, the life cycle of your payment is longer than just a payment. AceProtect provides the possibility of keeping track of the whole life cycle of a transaction, so you can inform of different transactions and notify them via our event endpoints. AceProtect’s machine learning models uses this information to learn and adapt to the fraud scenarios in real-time.

There are three types of events that you can send:

Event Name
Description
Refund
/fraudScores/{scoreId}/refund
When you send a refund operation. See the full API reference for refund event here.
Cancel
When you send a cancel transcation. See the full API reference for cancel event here.
Capture
/fraudScores/{scoreId}/capture
When you send a capture transcation. See the full API reference for capture event here.

Response

The response will have the same format that you had on payments.

Step 6 - Provide information about Chargebacks and Fraud

Chargeback and Fraud notifications are crucial feedback loops for AceProtect’s machine learning models to learn and adapt to fraudulent behaviour. You have two endpoints where you can submit those events:

Event Name
Description
Chargebacks
/fraudScores/{scoreId}/chargeback
When you need to notifiy a Chargebacks. See the full API reference for chargeback event here.
Notification of Fraud
/fraudScores/{scoreId}/notificationOfFraud
When you need to notifiy a fraud event. See the full API reference for fraud event here.

Response

In this case, the response will follow the same rules as in a payment, refund, cancel and capture events.

Merchants using 3rd party gateways


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


Top