FPA API Integration guide

The following guide describes information for partners to use Orders API endpoints to integrate with Fraud Protection Advanced (FPA).

APIs for FPA

Use the following endpoints from the Orders v2 API to get information about fraud protection for your merchant's transactions:

Know before you code

Your merchants must meet the following integration requirements:

Have PayPal Complete Payments (PPCP) capability enabled.
Have integrated with Orders v2 API.
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.
- For more information on how to set up FPA for your PayPal business account, see following guides:

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 for processing.

Create order

The following table shows the required parameters for optimal FPA performance when making a POST call to the Create order 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 if they are on a browser. The device ID is sent as PAYPAL-CLIENT-METADATA-ID in the request data.
- Integrate Magnes 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 in the Create order endpoint of the Orders v2 API.

Field name, Description, Type, Notes
Field name	Description	Type	Notes
`PayPal-Client-Metadata-Id`	The device ID for this purchase. See the parameter definition for more information.	String	Minimum characters: 1 Maximum characters: 36

Body

Field name, Description, Type, Notes
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 for more information.	string	Minimum characters: 3 Maximum characters: 254 Pattern: `(?:[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 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 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 for more information.	object
`purchase_units.items`	An array of line items that the customer purchases from the merchant. See the parameter definition 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 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

Field name, Description, Type, Notes
Field name	Description	Type	Notes
`payment_source.card.name`	The cardholder's name as it shows up on the card. See the parameter definition for more information.	string	Minimum characters: 1 Maximum characters: 300
`payment_source.card.number`	The primary account number (PAN) for the payment card. See the parameter definition for more information.	string	Minimum characters: 13 Maximum characters: 19

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 guide for sandbox login credentials and access token information.

Identifying fraud filter activations

Use endpoints 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

{
    "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": "[email protected]",
                            "phone": {
                                "phone_type": "MOBILE",
                                "phone_number": {
                                    "country_code": "1",
                                    "national_number": "4083855946"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

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

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

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.

{
  "request": {
    "method": "GET",
    "path": "v2/checkout/orders/{orderId}",
    "headers": {
      "Content-Type": "application/json",
      "Authorization: "Bearer ACCESS-TOKEN"
    }
  }
}

Modify the request code

Change ACCESS-TOKEN to your access token.
Replace the orderId with the one corresponding to your customer's order.

Sample response for approved transaction

The Orders API returns the following response for an approved transaction:

{
    "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": "[email protected]",
                        "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

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.

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.

{
    "request": {
        "method": "GET",
        "path": "v2/checkout/orders/{orderId}",
        "headers": {
            "Content-Type": "application/json",
            "Authorization": "Bearer ACCESS-TOKEN"
        }
    }
}

Modify the request code

Change ACCESS-TOKEN to your access token.
Replace the orderId with the one corresponding to your customer's order.

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.

If any of the pre-authorization filters fail, the Orders v2 API will return the following response with a status 422 Unprocessable Entity.

"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

Request, 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

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.

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.

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.

{
  "request": {
    "method": "GET",
    "path": "v2/checkout/orders/{orderId}",
    "headers": {
      "Content-Type": "application/json",
      "Authorization: "Bearer ACCESS-TOKEN"
    }
  }
}

Modify the request code

Change ACCESS-TOKEN to your access token.
Replace the orderId with the one corresponding to your customer's order.

Response parameters

The fraud_filter_details contains the following fields:

status of the risk assessment. The following are the possible values:

Status value, Status Description
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.

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.

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

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 page. In case the Post Authorization Filters fail, the API returns the following response:

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

Request, Result
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

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

{
    "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": "[email protected]",
                    "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

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.

For more information on how to upgrade your merchants to from Fraud Protection Standard (FPS) tool to FPA, see Upgrade to FPA.

For more information on how your merchant can set up filters, see Create and set up filters.

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

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:

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

"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

For instructions to go live in PayPal's production environment, see Production Environment.

The following guide describes information for partners to use Orders API endpoints to integrate with Fraud Protection Advanced (FPA).

APIs for FPA

Use the following endpoints from the Orders v2 API to get information about fraud protection for your merchant's transactions:

Know before you code

Your merchants must meet the following integration requirements:

Have PayPal Complete Payments (PPCP) capability enabled.
Have integrated with Orders v2 API.
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.
- For more information on how to set up FPA for your PayPal business account, see following guides:

Essential prerequisites for optimal setup

Create order

The following table shows the required parameters for optimal FPA performance when making a POST call to the Create order 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 if they are on a browser. The device ID is sent as PAYPAL-CLIENT-METADATA-ID in the request data.
- Integrate Magnes 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 in the Create order endpoint of the Orders v2 API.

Field name, Description, Type, Notes
Field name	Description	Type	Notes
`PayPal-Client-Metadata-Id`	The device ID for this purchase. See the parameter definition for more information.	String	Minimum characters: 1 Maximum characters: 36

Body

Field name, Description, Type, Notes
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 for more information.	string	Minimum characters: 3 Maximum characters: 254 Pattern: `(?:[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 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 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 for more information.	object
`purchase_units.items`	An array of line items that the customer purchases from the merchant. See the parameter definition 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 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

Field name, Description, Type, Notes
Field name	Description	Type	Notes
`payment_source.card.name`	The cardholder's name as it shows up on the card. See the parameter definition for more information.	string	Minimum characters: 1 Maximum characters: 300
`payment_source.card.number`	The primary account number (PAN) for the payment card. See the parameter definition for more information.	string	Minimum characters: 13 Maximum characters: 19

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 guide for sandbox login credentials and access token information.

Identifying fraud filter activations

Use endpoints 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

{
    "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": "[email protected]",
                            "phone": {
                                "phone_type": "MOBILE",
                                "phone_number": {
                                    "country_code": "1",
                                    "national_number": "4083855946"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

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

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

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.

{
  "request": {
    "method": "GET",
    "path": "v2/checkout/orders/{orderId}",
    "headers": {
      "Content-Type": "application/json",
      "Authorization: "Bearer ACCESS-TOKEN"
    }
  }
}

Modify the request code

Change ACCESS-TOKEN to your access token.
Replace the orderId with the one corresponding to your customer's order.

Sample response for approved transaction

The Orders API returns the following response for an approved transaction:

{
    "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": "[email protected]",
                        "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

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.

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.

{
    "request": {
        "method": "GET",
        "path": "v2/checkout/orders/{orderId}",
        "headers": {
            "Content-Type": "application/json",
            "Authorization": "Bearer ACCESS-TOKEN"
        }
    }
}

Modify the request code

Change ACCESS-TOKEN to your access token.
Replace the orderId with the one corresponding to your customer's order.

Understanding pre-authorization filters

For more information on how your merchant can set default and custom filters, see Create and set up filters.

If any of the pre-authorization filters fail, the Orders v2 API will return the following response with a status 422 Unprocessable Entity.

"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

Request, 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

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.

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.

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.

{
  "request": {
    "method": "GET",
    "path": "v2/checkout/orders/{orderId}",
    "headers": {
      "Content-Type": "application/json",
      "Authorization: "Bearer ACCESS-TOKEN"
    }
  }
}

Modify the request code

Change ACCESS-TOKEN to your access token.
Replace the orderId with the one corresponding to your customer's order.

Response parameters

The fraud_filter_details contains the following fields:

status of the risk assessment. The following are the possible values:

Status value, Status Description
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.

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

These filters will be evaluated only if your merchant has enabled these on the FPA filters page. In case the Post Authorization Filters fail, the API returns the following response:

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

Request, Result
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

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_detailshas 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 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 event.

{
    "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": "[email protected]",
                    "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

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.

For more information on how to upgrade your merchants to from Fraud Protection Standard (FPS) tool to FPA, see Upgrade to FPA.

For more information on how your merchant can set up filters, see Create and set up filters.

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

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:

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

"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

For instructions to go live in PayPal's production environment, see Production Environment.

FPA API Integration guide

Create and set up filters

Manage lists

Review transactions

Monitor FPA activity

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

FPA API Integration guide

Create and set up filters

Manage lists

Review transactions

Monitor FPA activity

On this page

On this page