AceProtect for Direct Merchants

ACEProtect for Direct Merchants

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 Payvision Payment Gateway (Direct Merchant).
The next picture shows the process to follow:

Steps 1 - Create Fraud Score

Merchant will send the consumer and order details along with custom parameters when sending the payment request.
The merchant submits a fraud score request the Payvision (P.O.) /fraudscore endpoint.

Fraud Score Request

    "header": {
        "businessId": "999999"
    "body": {
        "card": {
            "holderName": "John Doe",
            "number": "4111111111111111",
            "expiryMonth": 12,
            "expiryYear": 2020,
            "cvvPresent": true
        "customer": {
            "customerId": "myCustomerId",
            "email": "[email protected]",
            "givenName": "John",
            "familyName": "Doe",
            "birthDate": "1983-08-01",
            "phoneNumber": "19009990000",
            "mobileNumber": "16879991234",
            "companyName": "",
            "identificationTypeId": 3,
            "identificationNumber": "123456789Z",
            "ipAddress": "",
            "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

Payvision (P.O.)'s response contains a fraud.score and a field called fraud.statusDescription indicating the recommendation over the order (accept, reject, trigger 3DS or manual review).
Also, in the response it is included an unique id which it will be used later to perform the payment.

    "header": {
        "requestTimestamp": "2018-02-26T11:21:41.7268985Z"
    "result": 0,
    "description": "Ok",
    "body": {
        "transaction": {            
            "trackingCode": "7F4BFD5D-55E4-4775-81F7-0784188876C7"
        “fraud”: {
      "scoreId": "e7a246e1-a428-40e4-85d1-089493b2c7fb",
            "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 decisions 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 the goods or service you can perform the payment and once it is validated perform the capture

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".

Technical suggestion

We highly recommend to implement a fallback system that allows your business to continue processing payments and prevent transactions loss in the unlikely case that AceProtect services are temporarily unavailable

Step 3 - Perform the payment

In case the merchant had decided to perform the payment (with 3D Secure or not), merchant will need to submit a standard server to server payment request.

The request to Payvision Payment Gateway will be exactly the same than you would perform in case you are not using AceProtect as it is a completely independent service. The only difference is that you need to submit in the "customParameters" input field a key called "FraudScoreId" using the value returned in field "fraud.scoreId" in the fraud score API call (step 1).

curl \
    -d "authentication.userId=8a8294174b7ecb28014b9699220015cc" \
    -d "authentication.password=sy6KJsT8" \
    -d "authentication.entityId=8a8294174b7ecb28014b9699220015ca" \
    -d "amount=92.00" \
    -d "currency=EUR" \
    -d "paymentBrand=VISA" \
    -d "paymentType=DB" \
    -d "card.number=4200000000000000" \
    -d "card.holder=Jane Jones" \
    -d "card.expiryMonth=05" \
    -d "card.expiryYear=2018" \
    -d "card.cvv=123" \
    -d "customParameters[FraudScoreId]=6a3b3a16-3273-4af8-a214-d094a6678db4"

Updated 2 months ago

AceProtect for Direct Merchants

Suggested Edits are limited on API Reference Pages

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