# FPA API Integration guide (/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/integration)
The following guide describes information for partners to use Orders API endpoints to integrate with Fraud Protection Advanced (FPA).
## APIs for FPA [#apis-for-fpa]
Use the following endpoints from the [Orders v2 API](/api/orders/v2) to get information about fraud protection for your merchant's transactions:
* [Create order](/api/orders/v2/orders-create)
* [Capture payment for order](/api/orders/v2/orders-capture)
* [Authorize payment for order](/api/orders/v2/orders-authorize)
## Know before you code [#know-before-you-code]
> **Info:** Your merchants must meet the following integration requirements:
>
> * Have PayPal Complete Payments (PPCP) capability enabled.
> * Have integrated with [Orders v2 API](/api/orders/v2).
> * Have Risk as a Service (RaaS) product provisioned.
> * Have FPA as the chosen fraud protection tool under RaaS. They should have also set up FPA for their PayPal business account.
> * For more information on how to activate FPA for your PayPal business account, see [Activating FPA through partner merchants](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/getting-started/activate/).
>
> * For more information on how to set up FPA for your PayPal business account, see following guides:
>
> * [Create and set up filter](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/filters/)
> * [Manage list](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/lists/)
> * [Review transaction](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/review/)
> * [Monitor FPA activity](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/monitoring/)
## Essential prerequisites for optimal setup [#essential-prerequisites-for-optimal-setup]
To enhance risk and fraud management, we strongly recommend that your merchants provide additional data. This data is incorporated into PayPal's machine learning models, allowing them to analyze historical transactions and to improve the model's efficiency in detecting fraud. This approach optimizes the performance of your merchant's risk and fraud management processes. To include this data, your merchant must pass the following fields to all requests sent to the [Orders v2 API](/api/orders/v2) for processing.
### Create order [#create-order]
The following table shows the required parameters for optimal FPA performance when making a `POST` call to the [Create order](/api/orders/v2/orders-create) endpoint of the Orders v2 API.
**Device ID**
* If your merchant is integrated through PayPal JS SDK, the device ID will be passed by default.
* If your merchant is integrated through APIs, they would need to do the following so that the device ID is passed in the request:
* [Integrate Fraudnet](/platforms/checkout/apm/pay-upon-invoice/fraudnet/) if they are on a browser. The device ID is sent as `PAYPAL-CLIENT-METADATA-ID` in the request data.
* [Integrate Magnes](/limited-release/magnes/integrate/) if they are on an app.
* If merchants do not want to use Fraudnet or Magnes, they can pass the device ID information directly through the Orders API requests in the `PAYPAL-CLIENT-METADATA-ID` field. For more information, see the [Client-Metadata-Id](/api/orders/v2#orders_create!in=header\&path=PayPal-Client-Metadata-Id\&t=request) in the Create order endpoint of the Orders v2 API.
### Header [#header]
| **Field name** | **Description** | **Type** | **Notes** |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------- |
| `PayPal-Client-Metadata-Id` | The device ID for this purchase. See the [parameter definition](/api/orders/v2#orders_create!in=header\&path=PayPal-Client-Metadata-Id\&t=request) for more information. | String | Minimum characters: 1Maximum characters: 36 |
### Body [#body]
| **Field name** | **Description** | **Type** | **Notes** |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_source.card.attributes.customer.email_address` | Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing, which is offered to select partners and merchants. For all other use cases, we do not expect partners or merchant to send `email_address` of their customer. See the [parameter definition](/api/orders/v2#orders_create!path=payment_source/card/attributes/customer/email_address\&t=request) for more information. | string | Minimum characters: 3Maximum characters: 254Pattern: `(?:[a-zA-Z0-9!#$%&'*+/=?^_`{\|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{\|}~-]+)*\|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]\|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\|\[(?:(?:(2(5[0-5]\|[0-4][0-9])\|1[0-9][0-9]\|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]\|[0-4][0-9])\|1[0-9][0-9]\|[1-9]?[0-9])\|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]\|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])` |
| `payment_source.card.attribues.customer.phone` | The phone number of the buyer as provided to the merchant or on file with the merchant. The `phone.phone_number` supports only `national_number`. See the [parameter definition](/api/orders/v2#orders_create!path=payment_source/card/attributes/customer/phone\&t=request) for more information. | object | |
| `payment_source.card.billing_address` | The billing address for this card. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties. See the [parameter definition](/api/orders/v2#orders_create!path=payment_source/card/billing_address\&t=request) for more information. | object | |
| `purchase_units.shipping.address` | The address of the person to whom to ship the items. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties. See the [parameter definition](/api/orders/v2#orders_create!path=payment_source/card/attributes/customer/phone\&t=request) for more information. | object | |
| `purchase_units.items` | An array of line items that the customer purchases from the merchant. See the [parameter definition](/api/orders/v2#orders_create!path=payment_source/card/billing_address\&t=request) for more information. | array of objects |
|
| `purchase_units[].supplementary_data.risk.customer.ip_address` | An Internet Protocol address (IP address). This address assigns a numerical label to each device that is connected to a computer network through the Internet Protocol. Supports IPv4 and IPv6 addresses.
If your merchant is integrated through PayPal JS SDK, the Customer IP will be passed by default.If your merchant is integrated through APIs, they can send in the Customer IP through [Orders v2 API](/api/orders/v2) requests. In the request object for Orders v2 API, the Customer IP is structured as follows: `"supplementary_data": { "risk": { "customer": { "ip_address": "192.158.1.38" } } }` | string | Minimum characters: 7
Maximum characters: 39
Pattern: `^(([0-9]\|[1-9][0-9]\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])\.){3}([0-9]\|[1-9][0-9]\|1[0-9]{2}\|2[0-4][0-9]\|25[0-5])$\|^(([a-zA-Z]\|[a-zA-Z][a-zA-Z0-9\-]*[a-zA-Z0-9])\.)*([A-Za-z]\|[A-Za-z][A-Za-z0-9\-]*[A-Za-z0-9])$\|^\s*((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}\|:))\|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}\|((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)(\.(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)){3})\|:))\|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})\|:((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)(\.(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)){3})\|:))\|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})\|((:[0-9A-Fa-f]{1,4})?:((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)(\.(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)){3}))\|:))\|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})\|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)(\.(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)){3}))\|:))\|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})\|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)(\.(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)){3}))\|:))\|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})\|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)(\.(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)){3}))\|:))\|(:(((:[0-9A-Fa-f]{1,4}){1,7})\|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)(\.(25[0-5]\|2[0-4]\d\|1\d\d\|[1-9]?\d)){3}))\|:)))(%.+)?\s*$`
|
### Capture payment for order [#capture-payment-for-order]
| **Field name** | **Description** | **Type** | **Notes** |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------- |
| `payment_source.card.name` | The cardholder's name as it shows up on the card. See the [parameter definition](/api/orders/v2#orders_capture!path=payment_source/card/name\&t=request) for more information. | string | Minimum characters: 1Maximum characters: 300 |
| `payment_source.card.number` | The primary account number (PAN) for the payment card. See the [parameter definition](/api/orders/v2#orders_capture!path=payment_source/card/number\&t=request) for more information. | string | Minimum characters: 13Maximum characters: 19 |
## Supported payment methods [#supported-payment-methods]
This integration supports the following payment methods:
* Credit card/Debit card transactions
* Apple Pay
* Google Pay
To test the Orders V2 API, refer to the [Get Started](/api/rest/) guide for sandbox login credentials and access token information.
## Identifying fraud filter activations [#identifying-fraud-filter-activations]
Use [endpoints](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/integration/#apis-for-fpa) from the Orders v2 API to get response which contains the fraud filter failures, if any. For example, use the endpoint `Create Order` with the intent `CAPTURE`.
### Sample request and response for Create Order endpoint [#sample-request-and-response-for-create-order-endpoint]
#### Request
```text lineNumbers
{
"request": {
"method": "POST",
"path": "v2/checkout/orders",
"headers": {
"Content-Type": "application/json",
"PayPal-Request-Id": "7b92603e-77ed-4896-8e78-5dea2050476a",
"PayPal-Client-Metadata-Id": "pay_ses_1pa68ngmzk5"
"Authorization": "Bearer ACCESS-TOKEN"
},
"body": {
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"shipping": {
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "Building 17",
"admin_area_2": "San Jose",
"admin_area_1": "",
"state": "",
"postal_code": "95131",
"country_code": "US"
}
},
"supplementary_data": {
"risk": {
"customer": {
"ip_address": "192.158.1.38"
}
}
}
}
],
"payment_source": {
"card": {
"number": "4111111111111111",
"expiry": "2025-02",
"name": "John Doe",
"billing_address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
},
"attributes": {
"customer": {
"id": "n9a9sd",
"email_address": "test123@gmail.com",
"phone": {
"phone_type": "MOBILE",
"phone_number": {
"country_code": "1",
"national_number": "4083855946"
}
}
}
}
}
}
}
}
}
```
#### Response
```text lineNumbers
{
"response": {
"status": "201 Created",
"headers": {
"Content-Type": "application/json"
},
"body": {
"id": "6XN26427MP990700L",
"status": "COMPLETED",
"payment_source": {
"card": {
"name": "John Doe",
"last_digits": "1111",
"expiry": "2025-02",
"brand": "MASTERCARD",
"available_networks": [
"MASTERCARD",
"INTERLINK"
],
"type": "DEBIT",
"bin_details": {
"bin": "xxxxxx",
"issuing_bank": "CAPITAL ONE, NATIONAL ASSOCIAT ION",
"bin_country_code": "US",
"products": [
"CONSUMER"
]
}
}
},
"purchase_units": [
{
"reference_id": "default",
"payment_instruction": {
"payee_pricing_tier_id": "211IA"
},
"shipping": {
"name": {
"full_name": "*****"
},
"address": {
"address_line_1": "*****",
"admin_area_2": "GLEN ALLEN",
"admin_area_1": "VA",
"postal_code": "23060-9205",
"country_code": "US"
}
},
"payments": {
"captures": [
{
"id": "1C50935658387835P",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "145.17"
},
"final_capture": true,
"disbursement_mode": "INSTANT",
"seller_protection": {
"status": "NOT_ELIGIBLE"
},
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "145.17"
},
"paypal_fee": {
"currency_code": "USD",
"value": "3.20"
},
"net_amount": {
"currency_code": "USD",
"value": "141.97"
}
},
"invoice_id": "102088889-4b7a44bf-9eb0-45f1-b922-947d025eebdc",
"custom_id": "xxxxxx",
"links": [
{
"href": "https://api.paypal.com/v2/payments/captures/1C50935658387835P",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/captures/1C50935658387835P/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api.paypal.com/v2/checkout/orders/6XN26427MP990700L",
"rel": "up",
"method": "GET"
}
],
"create_time": "2024-12-04T03:14:36Z",
"update_time": "2024-12-04T03:14:36Z",
"network_transaction_reference": {
"id": "MDJVU4K66",
"date": "1203",
"network": "MASTERCARD"
},
"processor_response": {
"avs_code": "Y",
"cvv_code": "M",
"response_code": "0000"
}
}
]
}
}
],
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/6XN26427MP990700L",
"rel": "self",
"method": "GET"
}
]
}
}
}
```
### Modify the request code [#modify-the-request-code]
* Change `ACCESS-TOKEN` to your access token.
* Change the value of `PayPal-Client-Metadata-Id` to your Device Id.
* Ensure to send the following data fields to help with better risk evaluation. For more information, see [essential prerequisites for optimal setup](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/integration/#essential-prerequisites-for-optimal-setup).
* Change `email_address` in the customer object to the email address of the customer.
* Change `phone_number` in the `customer.phone` object to the phone number of the customer.
* Change `address` in the shipping object to the shipping address of the customer.
* Change the `billing_address` fields to the billing address information of the customer.
* Change the `number` and `name` in the `payment_source.card` object to the card number and name of the card holder.
* Change `ip_address` in the `supplementary_data.risk.customer` object to your customer's IP address.
### Response parameters [#response-parameters]
* The `status` of the response is set to `201 Created`.
* The `captures.status` is set to `COMPLETED`. In the case of an authorize scenario, `authorizations.status` is set to `CREATED`.
* The `links.href` contains the GET Order URL. Use this URL to get order details.
* No risk assessment object will be returned in the response.
**Note**: If your merchant has not enabled any risk filters, the response will be the same as in a standard `Capture Order` scenario.
## Get order details - no risk filters enabled [#get-order-details---no-risk-filters-enabled]
Use the `Show order details` endpoint to get the details on the failed risk filters along with the rest of the order details. The response will be the same as in a standard `Capture Order` scenario.
#### Sample request
```text lineNumbers
{
"request": {
"method": "GET",
"path": "v2/checkout/orders/{orderId}",
"headers": {
"Content-Type": "application/json",
"Authorization: "Bearer ACCESS-TOKEN"
}
}
}
```
#### Sample response
```text lineNumbers
{
"response": {
"status": "201 Created",
"headers": {
"Content-Type": "application/json"
},
"body": {
"id": "6XN26427MP990700L",
"status": "COMPLETED",
"payment_source": {
"card": {
"name": "John Doe",
"last_digits": "1111",
"expiry": "2025-02",
"brand": "MASTERCARD",
"available_networks": [
"MASTERCARD",
"INTERLINK"
],
"type": "DEBIT",
"bin_details": {
"bin": "xxxxxx",
"issuing_bank": "CAPITAL ONE, NATIONAL ASSOCIAT ION",
"bin_country_code": "US",
"products": [
"CONSUMER"
]
}
}
},
"purchase_units": [
{
"reference_id": "default",
"payment_instruction": {
"payee_pricing_tier_id": "211IA"
},
"shipping": {
"name": {
"full_name": "*****"
},
"address": {
"address_line_1": "*****",
"admin_area_2": "GLEN ALLEN",
"admin_area_1": "VA",
"postal_code": "23060-9205",
"country_code": "US"
}
},
"payments": {
"captures": [
{
"id": "1C50935658387835P",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "145.17"
},
"final_capture": true,
"disbursement_mode": "INSTANT",
"seller_protection": {
"status": "NOT_ELIGIBLE"
},
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "145.17"
},
"paypal_fee": {
"currency_code": "USD",
"value": "3.20"
},
"net_amount": {
"currency_code": "USD",
"value": "141.97"
}
},
"invoice_id": "102088889-4b7a44bf-9eb0-45f1-b922-947d025eebdc",
"custom_id": "xxxxxx",
"links": [
{
"href": "https://api.paypal.com/v2/payments/captures/1C50935658387835P",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/captures/1C50935658387835P/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api.paypal.com/v2/checkout/orders/6XN26427MP990700L",
"rel": "up",
"method": "GET"
}
],
"create_time": "2024-12-04T03:14:36Z",
"update_time": "2024-12-04T03:14:36Z",
"network_transaction_reference": {
"id": "MDJVU4K66",
"date": "1203",
"network": "MASTERCARD"
},
"processor_response": {
"avs_code": "Y",
"cvv_code": "M",
"response_code": "0000"
}
}
]
}
}
],
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/6XN26427MP990700L",
"rel": "self",
"method": "GET"
}
]
}
}
}
```
### Modify the request code [#modify-the-request-code-1]
* Change `ACCESS-TOKEN` to your access token.
* Replace the `orderId` with the one corresponding to your customer's order.
### Sample response for approved transaction [#sample-response-for-approved-transaction]
The Orders API returns the following response for an approved transaction:
```javascript lineNumbers
{
"response": {
"status": "201 Created",
"headers": {
"Content-Type": "application/json"
},
"body": {
"id": "1B3121425K9657222",
"intent": "CAPTURE",
"status": "COMPLETED",
"payment_source": {
"card": {
"name": "txn1",
"last_digits": "6237",
"expiry": "2026-01",
"brand": "VISA",
"available_networks": [
"VISA"
],
"type": "CREDIT",
"bin_details": {
"bin": "430591983",
"issuing_bank": "SIERRA CENTRAL CREDIT UNION",
"bin_country_code": "US"
}
}
},
"purchase_units": [
{
"reference_id": "REF123",
"amount": {
"currency_code": "USD",
"value": "13.00"
},
"payee": {
"email_address": "RaaS-DirectMerchant-FT01@abc.com",
"merchant_id": "YQVPMPGKSQUMW"
},
"soft_descriptor": "NATURESKEEP",
"payments": {
"captures": [
{
"id": "6M8275308Y428715L",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "13.00"
},
"final_capture": true,
"seller_protection": {
"status": "NOT_ELIGIBLE"
},
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "13.00"
},
"paypal_fee": {
"currency_code": "USD",
"value": "0.83"
},
"net_amount": {
"currency_code": "USD",
"value": "12.17"
}
},
"links": [
{
"href": "https://api.paypal.com/v2/payments/captures/6M8275308Y428715L",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/captures/6M8275308Y428715L/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api.paypal.com/v2/checkout/orders/1B3121425K9657222",
"rel": "up",
"method": "GET"
}
],
"create_time": "2024-09-13T14:02:23Z",
"update_time": "2024-09-13T14:02:23Z",
"network_transaction_reference": {
"id": "497635885629824",
"network": "VISA"
},
"processor_response": {
"avs_code": "Y",
"cvv_code": "M",
"response_code": "0000"
}
}
]
},
"risk_assessment": {
"fraud_filter_details": {
"status": "ALLOW",
"filters_applied": [
"Test Approve"
]
}
}
}
],
"create_time": "2024-09-13T14:02:23Z",
"update_time": "2024-09-13T14:02:23Z",
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/1B3121425K9657222",
"rel": "self",
"method": "GET"
}
]
}
}
}
```
### Response parameters for approved transaction [#response-parameters-for-approved-transaction]
* The `status` of the response is set to `201 Created`.
* The `captures.status` is set to `COMPLETED`. In case of an authorize scenario, `authorizations.status` is set to `CREATED`.
* The `links.href` contains the GET Order URL. Use this URL to get order details.
* A `risk_assessment.fraud_filter_details` object will be returned specifying the following fraud filter details:
* `status` of the risk assessment, value of which will always be `ALLOW`.
* `filters_applied` describes filters applied during risk checks. These are typically set up and enabled by your merchants. For more information, see [Create and set up filters](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/filters/).
## Get order details for approved transaction [#get-order-details-for-approved-transaction]
Use the `Show order details` endpoint to get the details on the failed risk filters along with the rest of the order details.
#### Sample request
```text lineNumbers
{
"request": {
"method": "GET",
"path": "v2/checkout/orders/{orderId}",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer ACCESS-TOKEN"
}
}
}
```
#### Sample response
```text lineNumbers
{
"response": {
"status": "200 OK",
"headers": {
"Content-Type": "application/json"
},
"body": {
"id": "1B3121425K9657222",
"status": "COMPLETED",
"payment_source": {
"card": {
"name": "txn1",
"last_digits": "6237",
"expiry": "2026-01",
"brand": "VISA",
"available_networks": [
"VISA"
],
"type": "CREDIT",
"bin_details": {
"bin": "430591983",
"issuing_bank": "SIERRA CENTRAL CREDIT UNION",
"bin_country_code": "US"
}
}
},
"purchase_units": [
{
"reference_id": "REF123",
"amount": {
"currency_code": "USD",
"value": "13.00"
},
"payee": {
"email_address": "RaaS-DirectMerchant-FT01@abc.com",
"merchant_id": "YQVPMPGKSQUMW"
},
"soft_descriptor": "NATURESKEEP",
"payments": {
"captures": [
{
"id": "6M8275308Y428715L",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "13.00"
},
"final_capture": true,
"seller_protection": {
"status": "NOT_ELIGIBLE"
},
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "13.00"
},
"paypal_fee": {
"currency_code": "USD",
"value": "0.83"
},
"net_amount": {
"currency_code": "USD",
"value": "12.17"
}
},
"links": [
{
"href": "https://api.paypal.com/v2/payments/captures/6M8275308Y428715L",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/captures/6M8275308Y428715L/refund",
"rel": "refund",
"method": "POST"
}
],
"create_time": "2024-09-13T14:02:23Z",
"update_time": "2024-09-13T14:02:23Z",
"network_transaction_reference": {
"id": "497635885629824",
"network": "VISA"
},
"processor_response": {
"avs_code": "Y",
"cvv_code": "M",
"response_code": "0000"
}
}
]
},
"risk_assessment": {
"fraud_filter_details": {
"status": "ALLOW",
"filters_applied": [
"Test Approve"
]
}
}
}
],
"create_time": "2024-09-13T14:02:23Z",
"update_time": "2024-09-13T14:02:23Z",
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/1B3121425K9657222",
"rel": "self",
"method": "GET"
}
]
}
}
}
```
### Modify the request code [#modify-the-request-code-2]
* Change `ACCESS-TOKEN` to your access token.
* Replace the `orderId` with the one corresponding to your customer's order.
## Understanding pre-authorization filters [#understanding-pre-authorization-filters]
The filters that your merchant has set up and enabled for their PayPal business account are known as pre-authorization filters. These filters are executed during the transaction planning phase, occurring before the transaction is sent to the card issuer for authentication.
The goal of the pre-authorization flow is to identify potential fraud indicators early, before the payment attempt reaches the card issuer. By doing so, merchants can reduce issuer declines and improve the overall success rate of legitimate transactions.
For more information on how your merchant can set default and custom filters, see [Create and set up filters](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/filters/).
If any of the pre-authorization filters fail, the [Orders v2 API](/api/orders/v2) will return the following response with a status `422 Unprocessable Entity`.
```javascript lineNumbers
"response": {
"status": "422 Unprocessable Entity",
"headers": {
"Content-Type": "application/json"
},
"body": {
"name": "UNPROCESSABLE_ENTITY",
"details": [
{
"issue": "PAYEE_BLOCKED_TRANSACTION",
"description": "Declined by fraud tool ( Fraud Protection / Chargeback Protection ) due to potential fraud risk. Please review your fraud settings.",
"links": [
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}
]
}
],
"message": "The requested action could not be performed, semantically incorrect, or failed business validation",
"debug_id": "9e57901073cf8",
"links": [
{
"href": "https://developer.paypal.com/api/orders/v2/error-messages",
"rel": "information_link",
"method": "GET"
}
]
}
}
```
### Step result [#step-result]
| Request | Result |
| ------------------------------------------ | ------------------------------- |
| Single step payment – Risk filter failures | HTTP `422 UNPROCESSABLE ENTITY` |
| Multi step payment – Risk filter failures | HTTP `422 UNPROCESSABLE ENTITY` |
| Confirm payment - Risk filter failures | HTTP `422 UNPROCESSABLE ENTITY` |
## Response parameters with failed pre-authorization filters [#response-parameters-with-failed-pre-authorization-filters]
* The `status` of the response is set to `422 Unprocessable Entity`.
* The `details` array has the following fields:
* The field `issue` is set to `PAYEE_BLOCKED_TRANSACTION`.
* The `description` is set to `The fraud settings for this seller are such that this payment cannot be executed`.
* The `links` array has a field `href` which contains the GET Order URL. Use the URL to get the order details including the reason for the failure and the risk filters associated with the order. For more information on using the URL to get order details, see [Get filter failure details for preauthorized filters](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/integration/#get-filter-failure-details-for-preauthorized-filters).
Additionally, you can subscribe for a webhook event: `CHECKOUT.ORDER.DECLINED` to get the details on the failed filters. For more information, see [Subscribe to CHECKOUT.ORDER.DECLINED webhook event](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/integration/#subscribe-to-checkoutorderdeclined-webhook-event).
## Get filter failure details for preauthorized filters [#get-filter-failure-details-for-preauthorized-filters]
In case any of the pre-authorized filters fail, use the `Show order details` endpoint to get the details on the failed risk filters along with the rest of the order details.
#### Sample request
```text lineNumbers
{
"request": {
"method": "GET",
"path": "v2/checkout/orders/{orderId}",
"headers": {
"Content-Type": "application/json",
"Authorization: "Bearer ACCESS-TOKEN"
}
}
}
```
#### Sample response
```text lineNumbers
"response": {
"status": "200 OK",
"headers": {
"Content-Type": "application/json"
},
"body": {
"id": "5O190127TN364715T",
"status": "CREATED",
"intent": "CAPTURE",
"payment_source": {
"card": {
"last_digits": "1111",
"expiry": "2025-02",
"brand": "VISA"
}
},
"purchase_units": [
{
"reference_id": "refernece_id_1001",
"amount": {
"currency_code": "USD",
"value": "107.14"
},
"payee": {
"email_address": "merchant@example.com",
"merchant_id": "68B3UCGMFWRBW"
},
"description": "Description of PU1",
"custom_id": "custom_id_1001",
"soft_descriptor": "PP*soft_descr_107.14",
"items": [
{
"name": "VRLens1",
"unit_amount": {
"currency_code": "USD",
"value": "107.14"
},
"quantity": "1",
"description": "VRLens1",
"sku": "259483234816",
"category": "PHYSICAL_GOODS"
}
],
"risk_assessment": {
"fraud_filter_details": {
"status": "DENY",
"filters_applied": [
"CONFIGURED_FILTER_1",
"CONFIGURED_FILTER_2"
]
}
}
}
],
"create_time": "2024-02-18T05:46:26Z",
"update_time": "2024-02-18T05:47:17Z",
"links": [
{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}
]
}
}
```
### Modify the request code [#modify-the-request-code-3]
* Change `ACCESS-TOKEN` to your access token.
* Replace the `orderId` with the one corresponding to your customer's order.
### Response parameters [#response-parameters-1]
The `fraud_filter_details` contains the following fields:
* `status` of the risk assessment. The following are the possible values:
| Status value | Status Description |
| --------------- | ----------------------------------------------- |
| `ALLOW` | Fraud Protection allowed this payment. |
| `DENY/DECLINED` | Fraud Protection denied this payment. |
| `PENDING` | Payment is in the Fraud Protection Review queue |
* `filters_applied` which describes filters applied during risk checks. These are typically enabled by the merchants through Fraud Protection or Fraud Protection Advanced suites. For example, in the response above, the failed filters were `CONFIGURED_FILTER_1` and `CONFIGURED_FILTER_2`.
### Subscribe to CHECKOUT.ORDER.DECLINED Webhook event [#subscribe-to-checkoutorderdeclined-webhook-event]
To receive information about transactions declined due to pre-authorization risk filters, subscribe to the `CHECKOUT.ORDER.DECLINED` Webhook event. A sample response for this event is shown below. In this example, the transaction was declined because the custom `TRANSACTION_AMOUNT_FILTER`, configured by the merchant, failed.
```javascript lineNumbers
{
"response": {
"status": "200 OK",
"headers": {
"Content-Type": "application/json"
},
"body": {
"id": "WH-COC11055RA711503B-3W074927CF383080E",
"create_time": "2024-01-16T21:21:49.000Z",
"event_type": "CHECKOUT.ORDER.DECLINED",
"resource_type": "checkout-order",
"resource_version": "2.0",
"summary": "Checkout Order Declined due to Risk Fraud Filter failures",
"resource": {
"id": "3W074927CF383080E",
"status": "CREATED",
"payment_source": {
"card": {
"last_digits": "1111",
"expiry": "2025-10",
"brand": "VISA",
"type": "CREDIT"
}
},
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"shipping": {
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "Building 17",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
},
"risk_assessment": {
"fraud_filter_details": {
"status": "DENY",
"filters_applied": [
"TRANSACTION_AMOUNT_FILTER"
]
}
}
}
],
"links": [
{
"href": "https://api-m.paypal.com/v2/checkout/orders/3W074927CF383080E",
"rel": "self",
"method": "GET"
}
]
},
"links": [
{
"href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-COC11055RA711503B-3W074927CF383080E",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-COC11055RA711503B-3W074927CF383080E/resend",
"rel": "resend",
"method": "POST"
}
],
"zts": 1494957670,
"event_version": "1.0"
}
}
}
```
## Understanding post authorization filters [#understanding-post-authorization-filters]
Once the payment attempt has been authorized by the issuer, a set of special filters executes on top of the issuer response. They are created on AVS and CVV attributes and are called Post authorization filters in the fraud protection platform. In case the payment attempt is declined by the issuer itself, the post auth filters are skipped from execution.
These filters will be evaluated only if your merchant has enabled these on the [FPA filters](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/filters/) page. In case the Post Authorization Filters fail, the API returns the following response:
```javascript lineNumbers
{
"response": {
"status": "201 Created",
"headers": {
"Content-Type": "application/json"
},
"body": {
"id": "3W074927CF383080E",
"status": "COMPLETED",
"payment_source": {
"card": {
"last_digits": "1111",
"expiry": "2025-10",
"brand": "VISA",
"type": "CREDIT"
}
},
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"shipping": {
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "Building 17",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
},
"risk_assessment": {
"fraud_filter_details": {
"status": "DENY",
"filters_applied": [
"AVS_ZIP_MISMATCH"
]
}
},
"payments": {
"authorizations": [
{
"id": "1FG40628C3275111G",
"status": "DENIED",
"status_details": {
"reason": "DECLINED_BY_RISK_FRAUD_FILTERS"
},
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"invoice_id": "DEMO-472",
"custom_id": "Custom-ID",
"seller_protection": {
"status": "NOT_ELIGIBLE"
},
"links": [
{
"href": "https://api-m.paypal.com/v2/payments/authorizations/1FG40628C3275111G",
"rel": "self",
"method": "GET"
},
{
"href": "https://api-m.paypal.com/v2/checkout/orders/3W074927CF383080E",
"rel": "up",
"method": "GET"
}
],
"processor_response": {
"avs_code": "I",
"cvv_code": "M",
"response_code": "0000"
},
"create_time": "2025-02-18T17:42:03Z",
"update_time": "2025-02-18T17:42:03Z"
}
]
}
}
],
"links": [
{
"href": "https://api-m.paypal.com/v2/checkout/orders/3W074927CF383080E",
"rel": "self",
"method": "GET"
}
]
}
}
}
```
### Step result [#step-result-1]
| Request | Result |
| ------------------------------------------ | ---------- |
| Single step payment – Risk filter failures | HTTP `201` |
| Multi step payment – Risk filter failures | HTTP `200` |
| Confirm payment - Risk filter failures | HTTP `200` |
### Response parameters for failed post authorization filters [#response-parameters-for-failed-post-authorization-filters]
The `fraud_filter_details` contains the following fields:
* `status` of the risk assessment, value of which will always be DENY.
* `filters_applied` describes filters applied during risk checks. These are typically enabled by the merchants through Fraud Protection or Fraud Protection Advanced suites. For post-authorization filters, only possible values for failed filters are: `AVS_ZIP_MISMATCH` or `CVV_MISMATCH`.
For orders created with the `AUTHORIZE` intent, `authorizations` array under `payments` object has the following fields:
* `status` set to `DENIED` since the transaction failed.
* `status_details`has the `reason` field which is set to `DECLINED_BY_RISK_FRAUD_FILTERS` since the transaction failed due to fraud filter failures.
For orders created with the `CAPTURE` intent, captures array underpayments object has the following fields:
* `status` set to `DECLINED` since the transaction failed.
* `status_details` has the reason field which is set to `DECLINED_BY_RISK_FRAUD_FILTERS` since the transaction failed due to fraud filter failures.
The `processor_response` object has the fields `avs_code` and `cvv_code`. For more information on what each of these codes mean, see [processor\_response](/api/orders/v2#definition-authorization_with_additional_data!path=processor_response) descriptions.
**Note**: You don't need a Get Order request to get the filter failure details for post authorized failures, since the above API response for failed post authorization filters provides all details.
Additionally, you can subscribe for a webhook event : `CHECKOUT.ORDER.COMPLETED` to get the details on the failed filters. For more information, see [Subscribe to CHECKOUT.ORDER.COMPLETED](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/integration/#subscribe-to-checkoutordercompleted-webhook-event) event.
### Subscribe to CHECKOUT.ORDER.COMPLETED Webhook event [#subscribe-to-checkoutordercompleted-webhook-event]
To receive information about transactions declined due to post-authorization risk filters, subscribe to the `CHECKOUT.ORDER.COMPLETED` Webhook event. A sample response for this event is shown below. In this example, the transaction was declined because the filters `AVS_ZIP_MISMATCH` and `CVV_MISMATCH`, configured for the merchant, failed.
```javascript lineNumbers
{
"id": "WH-34M010001R114212F-8LR00246M4043391E",
"event_version": "1.0",
"create_time": "2024-09-11T09:11:03.200Z",
"resource_type": "checkout-order",
"resource_version": "2.0",
"event_type": "CHECKOUT.ORDER.COMPLETED",
"summary": "Checkout Order Completed",
"resource": {
"create_time": "2024-09-11T09:10:18Z",
"purchase_units": [
{
"reference_id": "REF123",
"amount": {
"currency_code": "USD",
"value": "6.00",
"breakdown": {
"item_total": {
"currency_code": "USD",
"value": "6.00"
},
"shipping": {
"currency_code": "USD",
"value": "0.00"
},
"handling": {
"currency_code": "USD",
"value": "0.00"
},
"insurance": {
"currency_code": "USD",
"value": "0.00"
},
"shipping_discount": {
"currency_code": "USD",
"value": "0.00"
}
}
},
"payee": {
"email_address": "p4pmp_99c58fac-be6b-48f7-ad20-63e7f9f0268a@paypal.com",
"display_data": {
"brand_name": "INC"
}
},
"soft_descriptor": "DEMO",
"payments": {
"captures": [
{
"id": "7SW18441P6357352M",
"status": "DECLINED",
"status_details": {
"reason": "DECLINED_BY_RISK_FRAUD_FILTERS"
},
"amount": {
"currency_code": "USD",
"value": "6.00"
},
"final_capture": true,
"disbursement_mode": "INSTANT",
"seller_protection": {
"status": "NOT_ELIGIBLE"
},
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "6.00"
},
"net_amount": {
"currency_code": "USD",
"value": "6.00"
}
},
"links": [
{
"href": "https://api.paypal.com/v2/payments/captures/7SW18441P6357352M",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v2/payments/captures/7SW18441P6357352M/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api.paypal.com/v2/checkout/orders/8EY32815388724808",
"rel": "up",
"method": "GET"
}
],
"create_time": "2024-09-11T09:10:27Z",
"update_time": "2024-09-11T09:10:27Z",
"network_transaction_reference": {
"id": "895546237854296",
"network": "VISA"
},
"processor_response": {
"avs_code": "A",
"cvv_code": "D",
"response_code": "0000"
}
}
]
},
"risk_assessment": {
"fraud_filter_details": {
"status": "DENY",
"filters_applied": [
"AVS_ZIP_MISMATCH",
"CVV_MISMATCH"
]
}
}
}
],
"links": [
{
"href": "https://api.paypal.com/v2/checkout/orders/8EY32815388724808",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/checkoutnow?token=8EY32815388724808",
"rel": "approve",
"method": "GET"
},
{
"href": "https://api.paypal.com:18824/v2/checkout/orders/8EY32815388724808",
"rel": "update",
"method": "PATCH"
},
{
"href": "https://api.paypal.com:18824/v2/checkout/orders/8EY32815388724808/capture",
"rel": "capture",
"method": "POST"
},
{
"href": "https://api.paypal.com:18824/v2/checkout/orders/8EY32815388724808/confirm-payment-source",
"rel": "confirm",
"method": "POST"
}
],
"id": "8EY32815388724808",
"payment_source": {
"card": {
"name": "txnREFUND_AND_REVERSAL",
"last_digits": "9084",
"expiry": "2026-01",
"brand": "VISA",
"available_networks": [
"VISA"
],
"type": "CREDIT",
"bin_details": {
"bin": "407055807",
"issuing_bank": "SIERRA CENTRAL CREDIT UNION",
"bin_country_code": "US"
}
}
},
"intent": "CAPTURE",
"status": "CREATED"
},
"links": [
{
"href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-34M010001R114212F-8LR00246M4043391E",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com:14084/v1/notifications/webhooks-events/WH-34M010001R114212F-8LR00246M4043391E/resend",
"rel": "resend",
"method": "POST"
}
]
}
```
## How to test your integration [#how-to-test-your-integration]
You must onboard to the RaaS product and integrate with Advanced card processing before you test this integration.
For more information on how to activate FPA for your merchants, see [Activating FPA through partner merchants](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/getting-started/activate/).
For more information on how to upgrade your merchants to from Fraud Protection Standard (FPS) tool to FPA, see [Upgrade to FPA](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/getting-started/upgrade/).
For more information on how your merchant can set up filters, see [Create and set up filters](/platforms/checkout/advanced/customize/fraud-protection/fraud-protection-advanced/filters/).
### Test for pre-authorization filter failures [#test-for-pre-authorization-filter-failures]
Set up your FPA with the appropriate filters and conditions, and apply these conditions in your request.
An example:
* You can configure a `TRANSACTION_AMOUNT_FILTER` which fails if the transaction amount exceeds 1000.
* Create an order which exceeds the amount 1000.
* Use `Authorize Order/Capture Order/` and you will get a `HTTP 422 UNPROCESSABLE ENTITY` and the risk assessment status will be set to `DENY`.
### Test for post authorization filter failures [#test-for-post-authorization-filter-failures]
**Note**: The following simulation rules will also work if you've integrated with PayPal's SDK and you pass the values through SDK's hosted fields.
Use the simulation rule specific CVV and address names. To ensure the AVS filter fails, set the `address_line_1` in your Orders API request as shown in the following sample:
```javascript lineNumbers
"payment_source": {
"card": {
"number": "4111111111111111",
"expiry": "2025-02",
"name": "John Doe",
"billing_address": {
"address_line_1": "AVS_A_971",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
}
}
}
```
To ensure the CVV filter fails, set the `security_code` in your Orders API as shown in the following sample:
```javascript lineNumbers
"payment_source": {
"card": {
"number": "4111111111111111",
"expiry": "2025-02",
"name": "John Doe",
"security_code" : 116,
"billing_address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_1": "CA",
"admin_area_2": "San Jose",
"postal_code": "95131",
"country_code": "US"
}
}
}
```
## Go live [#go-live]
For instructions to go live in PayPal's production environment, see [Production Environment](/api/rest/production/).
## Related resources [#related-resources]
> **Info:** Create and set up filters
>
> Use filters to decide whether FPA approves, rejects, or puts a transaction into a review queue.
> **Info:** Manage lists
>
> Use the lists feature to manage information and work with their rules to help prevent fraud.
> **Info:** Review transactions
>
> Review transactions that are flagged for review.
> **Info:** Monitor FPA activity
>
> You can track which users made changes and when these changes occurred in your merchant records.