Risk Assessment

Merchants are required to opt in to let PPRO to perform a Fraud Risk Assessment on their payment charges. Please reach out to your Account Manager to learn more about this service and the opt-in process.

Supported Payment Methods

Category	Payment Method	Status
Cards	Credit & Debit cards	Supported

Mandatory Attributes

For merchants who have opted in to allow PPRO to perform the Risk Assessment, the following attributes must be provided mandatorily. Refer the Quickstart: Cards to learn how to process Card Payments with PPRO.

Request Attributes	Consumer Initiated	Merchant Initiated
`initiator`	Mandatory	Mandatory
`paymentAgreementId`	Optional	Mandatory
`paymentMethod`	Mandatory	Optional
`paymentMedium`	Mandatory	Optional
`amount.currency` & `amount.value`	Mandatory	Mandatory
`consumer.name`	Mandatory	Optional
`consumer.email`	Mandatory	Optional
`consumer.taxIdentification`	Mandatory if country is `BR`	Optional
`consumer.country`	Mandatory	Optional
`consumer.billingAddress` `firstName` `lastName` `street` `postalCode` `city` `region` `country`	Mandatory	Optional
`order.orderItems` `category` `name` `quantity` `amount`	Mandatory	Optional
`order.shippingMethod`	Mandatory	Optional
`order.shippingAddress`	Mandatory when shippingMethod is not `VIRTUAL`	Optional

Card payments can be processed through PPRO in multiple ways. Below is an overview of each mechanism along with the corresponding payloads.

A - Using Payment Charges

The create payment charges request:

POST /v1/payment-charges HTTP/1.1
Host: api.sandbox.eu.ppro.com
Merchant-Id: <your_merchant_id>
Authorization: Bearer <your_token>

{
    "initiator": "CONSUMER",
    "paymentMethod": "CARD",
    "amount": {
        "value": 1000,
        "currency": "BRL"
    },
    "consumer": {
        "name": "Joe Doe",
        "country": "BR",
        "email": "[email protected]",
        "taxIdentification": "30711533229",
        "billingAddress": {
            "firstName": "Joe",
            "lastName": "Doe",
            "street": "R. Rui Barbosa, 153 – Bela Vista",
            "postalCode": "01326-010",
            "city": "São Paulo",
            "region": "São Paulo",
            "country": "BR"
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "White T Shirt",
                "category": "Apparel",
                "quantity": 1,
                "amount": 1000
            }
        ],
        "shippingMethod": "TRACKED_DELIVERY",
        "shippingAddress": {
            "firstName": "Joe",
            "lastName": "Doe",
            "street": "R. Rui Barbosa, 153 – Bela Vista",
            "postalCode": "01326-010",
            "city": "São Paulo",
            "region": "São Paulo",
            "country": "BR"
        }
    },
    "instrument": {
        "type": "RAW_CARD",
        "details": {
            "brand": "VISA",
            "number": "5167883645702800",
            "cvv": "123",
            "holderName": "John Doe",
            "expiryMonth": 12,
            "expiryYear": 2030
        }
    },
    "autoCapture": true
}

B - Payment Agreements

For Link Only, set initialPaymentCharge.amount.value to 0 (for $0 auth there is no autoCapture flag needed).
For Link & Pay, set it to the desired initial payment amount.

The create payment agreement request:

POST /v1/payment-agreements HTTP/1.1
Host: api.sandbox.eu.ppro.com
Merchant-Id: <your_merchant_id>
Authorization: Bearer <your_token>

{
    "paymentMethod": "CARD",
    "amount": {
        "value": 1000,
        "currency": "BRL"
    },
    "consumer": {
        "name": "Joe Doe",
        "country": "BR",
        "email": "[email protected]",
        "taxIdentification": "30711533229",
        "billingAddress": {
            "firstName": "Joe",
            "lastName": "Doe",
            "street": "R. Rui Barbosa, 153 – Bela Vista",
            "postalCode": "01326-010",
            "city": "São Paulo",
            "region": "São Paulo",
            "country": "BR"
        }
    },
    "instrument": {
        "type": "RAW_CARD",
        "details": {
            "brand": "VISA",
            "number": "5167883645702800",
            "cvv": "347",
            "holderName": "John Smith",
            "expiryMonth": 2,
            "expiryYear": 2030
        }
    },
    "initialPaymentCharge": {
        "initiator": "CONSUMER",
        "amount": {
            "value": 0,
            "currency": "BRL"
        },
        "order": {
            "orderItems": [
                {
                    "name": "White T Shirt",
                    "category": "Apparel",
                    "quantity": 1,
                    "amount": 1000
                }
            ],
            "shippingMethod": "TRACKED_DELIVERY",
            "shippingAddress": {
                "firstName": "Joe",
                "lastName": "Doe",
                "street": "R. Rui Barbosa, 153 – Bela Vista",
                "postalCode": "01326-010",
                "city": "São Paulo",
                "region": "São Paulo",
                "country": "BR"
            }
        }
    }
}

The create payment agreement charge request:

POST /v1/payment-agreements/{agreementId}/payment-charges HTTP/1.1
Host: api.sandbox.eu.ppro.com
Merchant-Id: <your_merchant_id>
Authorization: Bearer <your_token>

{
    "initiator": "MERCHANT",
    "amount": {
        "value": 4000,
        "currency": "BRL"
    },
    "order": {
        "orderItems": [
            {
                "name": "White Pant",
                "category": "Apparel",
                "quantity": 1,
                "amount": 4000
            }
        ],
        "shippingMethod": "TRACKED_DELIVERY",
        "shippingAddress": {
            "firstName": "Joe",
            "lastName": "Doe",
            "street": "R. Rui Barbosa, 153 – Bela Vista",
            "postalCode": "01326-010",
            "city": "São Paulo",
            "region": "São Paulo",
            "country": "BR"
        }
    },
    "autoCapture": true
}

C - Payment Session

The create payment session request for charge:

POST /v1/payment-sessions HTTP/1.1
Host: api.sandbox.eu.ppro.com
Merchant-Id: <your_merchant_id>
Authorization: Bearer <your_token>

{
    "recurring": false,
    "amount": {
        "value": 1000,
        "currency": "BRL"
    },
    "consumer": {
        "name": "Joe Doe",
        "country": "BR",
        "email": "[email protected]",
        "taxIdentification": "30711533229",
        "billingAddress": {
            "firstName": "Joe",
            "lastName": "Doe",
            "street": "R. Rui Barbosa, 153 – Bela Vista",
            "postalCode": "01326-010",
            "city": "São Paulo",
            "region": "São Paulo",
            "country": "BR"
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "White T Shirt",
                "category": "Apparel",
                "quantity": 1,
                "amount": 1000
            }
        ],
        "shippingMethod": "TRACKED_DELIVERY",
        "shippingAddress": {
            "firstName": "Joe",
            "lastName": "Doe",
            "street": "R. Rui Barbosa, 153 – Bela Vista",
            "postalCode": "01326-010",
            "city": "São Paulo",
            "region": "São Paulo",
            "country": "BR"
        }
    },
    "merchantPaymentChargeReference": "5c019979-0751-469e-96e0-b67f1d95c577",
    "autoCapture": true
}

The create payment session request for agreement:

POST /v1/payment-sessions HTTP/1.1
Host: api.sandbox.eu.ppro.com
Merchant-Id: <your_merchant_id>
Authorization: Bearer <your_token>

{
    "recurring": true,
    "amount": {
        "value": 1000,
        "currency": "BRL"
    },
    "consumer": {
        "name": "Joe Doe",
        "country": "BR",
        "email": "[email protected]",
        "taxIdentification": "30711533229",
        "billingAddress": {
            "firstName": "Joe",
            "lastName": "Doe",
            "street": "R. Rui Barbosa, 153 – Bela Vista",
            "postalCode": "01326-010",
            "city": "São Paulo",
            "region": "São Paulo",
            "country": "BR"
        }
    },
    "order": {
        "orderItems": [
            {
                "name": "White T Shirt",
                "category": "Apparel",
                "quantity": 1,
                "amount": 1000
            }
        ],
        "shippingMethod": "TRACKED_DELIVERY",
        "shippingAddress": {
            "firstName": "Joe",
            "lastName": "Doe",
            "street": "R. Rui Barbosa, 153 – Bela Vista",
            "postalCode": "01326-010",
            "city": "São Paulo",
            "region": "São Paulo",
            "country": "BR"
        }
    },
    "initialPaymentCharge": {
        "initiator": "CONSUMER",
        "amount": {
            "value": 0,
            "currency": "BRL"
        }
    },
    "autoCapture": true
}

The authorize a session for charge or agreement request:

POST /v1/payment-sessions/{sessionId}/authorizations HTTP/1.1
Host: api.sandbox.eu.ppro.com
Merchant-Id: <your_merchant_id>
Authorization: Bearer <your_token>

{
    "paymentMethod": "CARD",
    "amount": {
        "value": 1000,
        "currency": "BRL"
    }
}

Risk Assessment Outcome

A - Missing Mandatory Attributes

If any mandatory attribute required by PPRO to perform the Risk Assessment is missing from the request payload, the operation will return the following response.

"failure": {
    "failureType": "INTERNAL_DECLINE",
    "failureCode": "RISK_ASSESSMENT_MISSING_REQUIRED_ATTRIBUTES",
    "failureMessage": "consumer.email must not be blank"
}

B - Payment Declined Based on Risk Assessment

If all mandatory attributes required by PPRO are provided and the Risk Assessment is successfully executed, but the payment charge is declined based on the risk rules, the operation will return the following response.

"failure": {
    "failureType": "INTERNAL_DECLINE",
    "failureCode": "RISK_ASSESSMENT_DECLINED",
    "failureMessage": "Payment request declined due to risk assessment"
}

Sandbox Testing

To simulate the Risk Assessment outcomes in Sandbox please use the following:

Risk Assessment Decision	Request attribute `consumer.email`
Approved	[email protected] (or) any
Declined	[email protected]