Antifraud
Risk analysis applied to the charge before authorization.
Charges sent with the fraudAnalysis object go through PayZu's antifraud engine in real time before authorization. You control per charge whether the analysis runs and what to do with the result.
The antifraud analysis can:
- Approve the transaction automatically
- Reject the transaction on suspicion of fraud
- Route it to manual review, according to previously defined rules
Sending fraudAnalysis is required for international charges. See
International charge.
How it works
When a charge is created with the fraudAnalysis object, the operation is submitted
to a risk assessment based on several criteria, such as customer data,
purchase behavior, and order characteristics.
To use the antifraud, simply include the fraudAnalysis object inside
creditCardPayment in the transaction creation request. This object carries the device
identifier (fingerPrintId), the browser data (browser) and the MDD
fields (definedFields).
{
"creditCardPayment": {
"fraudAnalysis": {
"fingerPrintId": "xyz123fingerprint",
"browser": {
"cookiesAccepted": true,
"email": "joao.silva@example.com",
"hostName": "host.example.com",
"ipAddress": "192.168.0.1",
"type": "Chrome"
},
"definedFields": [
{
"id": 1,
"value": "Guest"
}
]
}
}
}For the list of values that can be passed in definedFields, see the
MDD table.
The response has no antifraud field of its own. The analysis result arrives in
creditCardPayment.status, reasonCode and reasonMessage:
| Analysis result | Fields in the response |
|---|---|
| Approved | The charge moves on to authorization and status becomes 1 (Authorized) or 2 (PaymentConfirmed) |
| Rejected on suspicion of fraud | status 13 (Aborted) with reasonCode 16 (AbortedByFraud) |
| Not completed | reasonCode 17 (CouldNotAntifraud) |
The full values are in Transaction status and reasons.
Capturing the fingerPrintId
The fingerPrintId is a random session id generated by the client
itself, which must be used in the payment request. Each fingerprint is
unique and valid for 48 hours.
Load the script
To obtain a fingerprint, you will need to load the following script in your HTML page:
<script src="https://static.payzu.io/scripts/antifraud.min.js"></script>Generate the id and activate the fingerprint
After that, you must generate a random id that will be your fingerprint and use our script to activate it.
Complete example:
<head>
<script src="https://static.payzu.io/scripts/antifraud.min.js"></script>
</head>
<script>
// Random id that will be used as the fingerprint
const uuid = self.crypto.randomUUID();
// Production environment
payzuAntiFraud.init({
identifier: uuid,
});
...
// Sandbox environment
payzuAntiFraud.init({
identifier: uuid,
sandbox: true,
});
...
</script>Parameters of the init function:
| Parameter | Default value | Required? |
|---|---|---|
identifier | * | Yes |
sandbox | false | No |
After activating it, you can already use your fingerprint inside the
fraudAnalysis field to create a payment request.
Send fraudAnalysis in the charge
To create a charge using the antifraud, you must provide the
fraudAnalysis field inside creditCardPayment. Inside browser, the
cookiesAccepted and ipAddress fields are required.
{
"customer": {
"name": "João Silva",
"identity": "12345678900",
"identityType": "CPF",
"email": "joao.silva@example.com",
"phone": "5511912345678",
"address": {
"street": "Rua das Flores",
"number": "123",
"zipCode": "01234567",
"city": "São Paulo",
"state": "SP",
"country": "Brasil",
"district": "Centro"
}
},
"creditCardPayment": {
"fraudAnalysis": {
"fingerPrintId": "xyz123fingerprint",
"browser": {
"cookiesAccepted": true,
"email": "joao.silva@example.com",
"hostName": "host.example.com",
"ipAddress": "192.168.0.1",
"type": "Chrome"
},
"definedFields": [
{
"id": 1,
"value": "Guest"
}
]
}
}
}In the schema, customer requires only name. With fraudAnalysis in the
request, the antifraud also requires identity, identityType, email,
phone and address; inside address, only complement is optional.
birthdate stays optional.