Protectmaxx API Overview #
Overview #
With the Fraud Advice API you can integrate fraud detection functionality into your website/shop. Result of this API is an advice to approve a customers transaction or to decline this customer because of a high risk of fraud. This is easily done by sending HTTP requests between your website/shop and Alphacomm.
This documentation gives an overview of the Fraud Advice API and its current functionalities.
General explanation of the workflow #
- Use Oauth2 authentication
- Send fraud-advice request
- Handle the advice
- Set the final status of the payment
- Send a request to us to set the status of the transaction
Implementation example #
Detailed steps for integration #
1. Authentication
The Fraud Advice API use Oauth2 authentication, which needs to be done before sending a request to the Fraud Advice API. Before starting a request you need to obtain a access_token that you add to your request.
More information about authentication can be found under “API Authorization Info” in the left menu or by clicking here.
2. Fraud advice request
This request contains all the necessary information about the user, the transaction and the data returned by the payment service provider. This is all necessary to enable the fraud checking system to effectively determine whether the transaction is allowed or not.
More information about the advice request can be found under “API documentation” in the left menu or by clicking here.
Let’s see an example request:
{
"id": "7bb6f1f3-d280-4b0c-a74f-90471ea69426", // Auto-generated UUID
"paymentMethod": "creditcard",
"domain": "alphacomm.nl", // The domain of the site.
"targetCountry": "NL" // Country code ISO3166 format
"transaction":{
"reference": "test-1111", // Max 20 characters
"currency": "EUR", // ISO4217 format
"amount": 2000, // The amount is in cents, 2000 = 20 EUR. Has to be sum of amounts * quantity in lines.
"description": "test-1444",
"lines":[
{
"name": "Some Voucher - 20 EUR", // Max 20 characters. Name of product.
"category": "PREPAID-VOUCHER", // Max 100 characters.
"brand": "alphacomm", // Max 100 characters.
"quantity": 1, // Number of items
"amount": 2000 // The amount is in cents, 2000 = 20 EUR
}
]
},
"payer": {
"id": "1337", // Unique numeric value specific per payer
"email": "john@alphacomm.nl", // Max 64 characters.
"deviceId": "a80d683678514df2b3c952f48b095266", // Max 50 characters.
"billing": {
"firstName": "Jhon", // Max 128 characters. To test decline of Fruad check flow set value to DECLINE
"lastName": "Doe", // Max 128 characters
"street": "Scheepmakerspassage 183", // Max 30 characters
"city": "Rotterdam",
"zip": "3011VH", // Max 50 characters. Customer postal code.
"phone": "+31612345678", // Phone number with Country code.
"email": "john@alphacomm.nl", // Max 64 characters.
"country": "NL" // Country code ISO3166 format
},
"shipping": {
"firstName": "John", // Max 128 characters.
"lastName": "Doe", // Max 128 characters.
"street": "Scheepmakerspassage 183", // Max 30 characters
"city": "Rotterdam",
"zip": "3011VH", // Max 50 characters. Customer postal code.
"phone": "+31612345678", // Phone number with Country code.
"email": "john@alphacomm.nl", // Max 64 characters.
"country": "NL" // Country code ISO 3166 format
},
"ipAddress": "127.0.0.1", // Support only ipv4
"language": "nl", // Language code ISO 639-1 format
"status": "registered", // Can be "guest", "registered", "registered-unconfirmed"
"verificationStatus": "phone", // Can be "identification", "phone", "trusted", "otherwise"
"dateRegistration": "2016-01-01T13:56:48+0100", // Date format ISO 8601
"dateLastUpdated": "2016-01-01T13:56:48+0100", // Date format ISO 8601
"dateFirstPurchase": "2016-01-01T13:56:48+0100", // Date format ISO 8601
"channel": "web" // Can be "web" or "app"
},
"creditcard": {
"id": "914891",
"cardBrand": "VISA", // Brand of the card.
"cardHolder": "John Doe", // The name of the card holder
"cardNo": "411111XXXXXX1111", // The bin code of the used card and the last 4 digits concatenated with X-es.
"bin": "411111", // The bin code of the used card (the first 6-8 digits).
"expiryDate": "1024", // In format MMYY.
"3DSecure": "1", // Phone number with Country code.
"3DSecureAuth": "successful", // Phone number with Country code.
"country": "NL" // Country code ISO 3166 format
}
}The last section depends on the payment method. In this example it was a credit card. These data blocks may vary by payment method, so always send the correct one based on the documentation.
3. Handle the advice
After the request has been processed, our system will send back a response indicating what the fraud system thinks should be done with the transaction. Once this has been processed on the merchant’s side and the payment has received its final status, we move on to the next point.
Before that, let’s see an example of the response our system will send in case of successful processing.
{
"id": "7bb6f1f3-d280-4b0c-a74f-90471ea69426", // The ID what we got in the request
"advice": "approve",
"transaction":{
"status": "pending", // The status of the transaction in our system (defaultly it's pending)
}
}4. Send transaction status data
This is where you confirm what happened with the transaction in your system and send the final transaction result to us (success or failure). We need this piece of information to keep track of what happens with the transaction on your system.
This is a necessary step because this information has an important role to play in statistics and possible future investigations.