Integrate Fraud Protection Advanced

Use this guide to integrate Fraud Protection Advanced (FPA) with the Orders v2 API and identify fraud filter activations in your merchant's transactions.

This guide covers how to pass the required fields for FPA, read fraud filter results from order responses, and handle pre-authorization and post-authorization filter failures.

Before you begin

Before you begin, make sure you have completed Getting Started for platforms and marketplaces.

For this guide specifically, your merchants must also meet the following requirements:

PayPal Complete Payments (PPCP) capability enabled
Integration with the Orders v2 API
Risk as a Service (RaaS) product provisioned
FPA selected as the fraud protection tool under RaaS and set up for their PayPal business account

For more information on activating FPA for a merchant's PayPal business account, see Activating FPA through partner merchants.

For more information on setting up FPA, see the following guides:

Endpoints used

Method, Endpoint, Description
Method	Endpoint	Description
POST	/v2/checkout/orders	Create an order
GET	/v2/checkout/orders/{orderId}	Show order details
POST	/v2/checkout/orders/{orderId}/capture	Capture payment for order
POST	/v2/checkout/orders/{orderId}/authorize	Authorize payment for order

Recommended fields for optimal FPA performance

To enhance risk and fraud management, pass the following fields on all requests to the Orders v2 API. This data is incorporated into PayPal's machine learning models and improves fraud detection accuracy.

Device ID

If your merchant is integrated through the PayPal JS SDK, the device ID is passed by default.
If your merchant is integrated through APIs, pass the device ID using one of the following methods:
- Integrate Fraudnet for browser-based integrations. The device ID is sent as PAYPAL-CLIENT-METADATA-ID in the request header.
- Integrate Magnes for app-based integrations.
- Pass the device ID directly through the PAYPAL-CLIENT-METADATA-ID header field. See the PayPal-Client-Metadata-Id parameter definition for more information.

Create order fields

Header

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. Required if processing via PayPal Guest Processing, which is offered to select partners and merchants. For all other use cases, partners and merchants are not expected to send `email_address`. See the parameter definition for more information.	string	Minimum characters: 3. Maximum characters: 254.
`payment_source.card.attributes.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 `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code`. 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 `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code`. 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 assigned to the customer's device. Supports IPv4 and IPv6 addresses. If integrated through the PayPal JS SDK, the customer IP is passed by default. If integrated through APIs, pass it as shown below. See the Orders v2 API for more information.	string	Minimum characters: 7. Maximum characters: 39.

Pass ip_address in the request object as follows:

"supplementary_data": {
  "risk": {
    "customer": {
      "ip_address": "192.158.1.38"
    }
  }
}

Capture payment for order fields

Field name, Description, Type, Notes
Field name	Description	Type	Notes
`payment_source.card.name`	The cardholder's name as it appears 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 and debit card transactions, Apple Pay, and Google Pay.

Step-by-step guide

Take the following steps to integrate Fraud Protection Advanced with the Orders v2 API.

1. Create an order

Send a POST request to v2/checkout/orders. Include the recommended fields for FPA as described in the Recommended fields for optimal FPA performance section.

Before sending, make the following substitutions:

Replace ACCESS-TOKEN with your access token.
Replace the value of PayPal-Client-Metadata-Id with your device ID.
Replace email_address with the customer's email address.
Replace phone_number with the customer's phone number.
Replace address in the shipping object with the customer's shipping address.
Replace the billing_address fields with the customer's billing address.
Replace number and name in payment_source.card with the card number and cardholder name.
Replace ip_address in supplementary_data.risk.customer with the customer's IP address.

{
  "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": "2028-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"
              }
            }
          }
        }
      }
    }
  }
}

{
  "status": "201 Created",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "6XN26427MP990700L",
    "status": "COMPLETED",
    "payment_source": {
      "card": {
        "name": "John Doe",
        "last_digits": "1111",
        "expiry": "2028-02",
        "brand": "MASTERCARD",
        "available_networks": ["MASTERCARD", "INTERLINK"],
        "type": "DEBIT",
        "bin_details": {
          "bin": "xxxxxx",
          "issuing_bank": "CAPITAL ONE, NATIONAL ASSOCIATION",
          "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" }
    ]
  }
}

Results: The API returns a 201 Created response. captures.status is set to COMPLETED. For an authorize scenario, authorizations.status is set to CREATED. The links.href field contains the GET order URL. No risk_assessment object is returned in this response.

Note: If your merchant has not enabled any risk filters, the response is the same as a standard Capture Order response.

2. Get filter failure details for pre-authorization filter failures

Pre-authorization filters execute during the transaction planning phase, before the transaction is sent to the card issuer. If any pre-authorization filter fails, the Orders v2 API returns a 422 Unprocessable Entity response.

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

The response contains the following fields:

status is set to 422 Unprocessable Entity.
details[].issue is set to PAYEE_BLOCKED_TRANSACTION.
details[].description is set to The fraud settings for this seller are such that this payment cannot be executed.
details[].links[].href contains the GET order URL. Use this URL to retrieve order details including the reason for failure and the associated risk filters.

To get the filter failure details, send a GET request to v2/checkout/orders/{orderId}. Replace ACCESS-TOKEN with your access token and replace orderId with the order ID for your customer's order.

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

{
  "status": "200 OK",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "5O190127TN364715T",
    "status": "CREATED",
    "intent": "CAPTURE",
    "payment_source": {
      "card": {
        "last_digits": "1111",
        "expiry": "2028-02",
        "brand": "VISA"
      }
    },
    "purchase_units": [
      {
        "reference_id": "reference_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" }
    ]
  }
}

The fraud_filter_details object contains the following fields:

status indicates the risk assessment outcome. Possible values:

Status value, Description
Status value	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 lists the filters that executed during risk checks. These are enabled by merchants through Fraud Protection or Fraud Protection Advanced. For more information, see Create and set up filters.

You can also subscribe to the CHECKOUT.ORDER.DECLINED webhook event to receive notifications about transactions declined due to pre-authorization filter failures. A sample response for this event is shown below. In this example, the transaction was declined because the merchant-configured TRANSACTION_AMOUNT_FILTER failed.

{
  "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": "2028-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"
  }
}

3. Get filter failure details for post-authorization filter failures

Post-authorization filters execute after the issuer responds to the payment attempt. They are evaluated on AVS and CVV attributes. Post-authorization filters are skipped if the issuer declines the payment. These filters execute only if your merchant has enabled them on the FPA filters page.

If a post-authorization filter fails, the API returns a 201 Created response with a DENY status in fraud_filter_details.

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

{
  "status": "201 Created",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "3W074927CF383080E",
    "status": "COMPLETED",
    "payment_source": {
      "card": {
        "last_digits": "1111",
        "expiry": "2028-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": "2028-02-18T17:42:03Z",
              "update_time": "2028-02-18T17:42:03Z"
            }
          ]
        }
      }
    ],
    "links": [
      { "href": "https://api-m.paypal.com/v2/checkout/orders/3W074927CF383080E", "rel": "self", "method": "GET" }
    ]
  }
}

The fraud_filter_details object contains the following fields:

status is always DENY for post-authorization filter failures.
filters_applied lists the filters that failed. For post-authorization filters, the only possible values are AVS_ZIP_MISMATCH and CVV_MISMATCH.

For orders created with the AUTHORIZE intent, the authorizations array under the payments object contains the following fields:

status is set to DENIED.
status_details.reason is set to DECLINED_BY_RISK_FRAUD_FILTERS.

For orders created with the CAPTURE intent, the captures array under the payments object contains the following fields:

status is set to DECLINED.
status_details.reason is set to DECLINED_BY_RISK_FRAUD_FILTERS.

The processor_response object contains avs_code and cvv_code fields. For code definitions, see processor_response in the Orders v2 API reference.

Note: A GET order request is not required for post-authorization filter failures. The response above contains all failure details.

You can also subscribe to the CHECKOUT.ORDER.COMPLETED webhook event to receive notifications about transactions declined due to post-authorization filter failures. A sample response for this event is shown below. In this example, the transaction was declined because the AVS_ZIP_MISMATCH and CVV_MISMATCH filters 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": "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" }
  ]
}

4. Retrieve approved transaction details

For approved transactions, use the Show order details endpoint to confirm the filter results alongside the rest of the order details. Replace ACCESS-TOKEN with your access token and replace orderId with the order ID for your customer's order.

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

{
  "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" },
                { "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" }
    ]
  }
}

The risk_assessment.fraud_filter_details object contains the following fields:

status is set to ALLOW for approved transactions.
filters_applied lists the filters that executed during risk checks.

Errors

Feature-specific errors for this task:

Error code, HTTP status, Cause, Resolution
Error code	HTTP status	Cause	Resolution
`PAYEE_BLOCKED_TRANSACTION`	422	A pre-authorization risk filter failed.	Check `details[].links[].href` in the response for the GET order URL. Use it to retrieve the order details and identify the failed filters. Review your merchant's fraud filter configuration. See Create and set up filters.

Test your integration

You must onboard to the RaaS product and integrate with Advanced card processing before testing.

For more information on activating FPA for your merchants, see Activating FPA through partner merchants.

For more information on upgrading merchants from Fraud Protection Standard to FPA, see Upgrade to FPA.

For more information on setting up filters, see Create and set up filters.

Test pre-authorization filter failures

Set up FPA with the appropriate filters and conditions. For example:

Configure a TRANSACTION_AMOUNT_FILTER that fails if the transaction amount exceeds 1000.
Create an order exceeding that amount.
Send an Authorize Order or Capture Order request.

Results: The API returns HTTP 422 UNPROCESSABLE ENTITY. The risk_assessment.status is set to DENY.

Test post-authorization filter failures

Note: The following simulation rules also apply if you have integrated with PayPal's SDK and pass values through SDK hosted fields.

To trigger an AVS filter failure, set address_line_1 in your Orders API request as follows:

"payment_source": {
  "card": {
    "number": "4111111111111111",
    "expiry": "2028-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 trigger a CVV filter failure, set security_code in your Orders API request as follows:

"payment_source": {
  "card": {
    "number": "4111111111111111",
    "expiry": "2028-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.

Use this guide to integrate Fraud Protection Advanced (FPA) with the Orders v2 API and identify fraud filter activations in your merchant's transactions.

This guide covers how to pass the required fields for FPA, read fraud filter results from order responses, and handle pre-authorization and post-authorization filter failures.

Before you begin

Before you begin, make sure you have completed Getting Started for platforms and marketplaces.

For this guide specifically, your merchants must also meet the following requirements:

PayPal Complete Payments (PPCP) capability enabled
Integration with the Orders v2 API
Risk as a Service (RaaS) product provisioned
FPA selected as the fraud protection tool under RaaS and set up for their PayPal business account

For more information on activating FPA for a merchant's PayPal business account, see Activating FPA through partner merchants.

For more information on setting up FPA, see the following guides:

Endpoints used

Method, Endpoint, Description
Method	Endpoint	Description
POST	/v2/checkout/orders	Create an order
GET	/v2/checkout/orders/{orderId}	Show order details
POST	/v2/checkout/orders/{orderId}/capture	Capture payment for order
POST	/v2/checkout/orders/{orderId}/authorize	Authorize payment for order

Recommended fields for optimal FPA performance

Device ID

If your merchant is integrated through the PayPal JS SDK, the device ID is passed by default.
If your merchant is integrated through APIs, pass the device ID using one of the following methods:
- Integrate Fraudnet for browser-based integrations. The device ID is sent as PAYPAL-CLIENT-METADATA-ID in the request header.
- Integrate Magnes for app-based integrations.
- Pass the device ID directly through the PAYPAL-CLIENT-METADATA-ID header field. See the PayPal-Client-Metadata-Id parameter definition for more information.

Create order fields

Header

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. Required if processing via PayPal Guest Processing, which is offered to select partners and merchants. For all other use cases, partners and merchants are not expected to send `email_address`. See the parameter definition for more information.	string	Minimum characters: 3. Maximum characters: 254.
`payment_source.card.attributes.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 `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code`. 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 `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code`. 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 assigned to the customer's device. Supports IPv4 and IPv6 addresses. If integrated through the PayPal JS SDK, the customer IP is passed by default. If integrated through APIs, pass it as shown below. See the Orders v2 API for more information.	string	Minimum characters: 7. Maximum characters: 39.

Pass ip_address in the request object as follows:

"supplementary_data": {
  "risk": {
    "customer": {
      "ip_address": "192.158.1.38"
    }
  }
}

Capture payment for order fields

Field name, Description, Type, Notes
Field name	Description	Type	Notes
`payment_source.card.name`	The cardholder's name as it appears 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 and debit card transactions, Apple Pay, and Google Pay.

Step-by-step guide

Take the following steps to integrate Fraud Protection Advanced with the Orders v2 API.

1. Create an order

Send a POST request to v2/checkout/orders. Include the recommended fields for FPA as described in the Recommended fields for optimal FPA performance section.

Before sending, make the following substitutions:

Replace ACCESS-TOKEN with your access token.
Replace the value of PayPal-Client-Metadata-Id with your device ID.
Replace email_address with the customer's email address.
Replace phone_number with the customer's phone number.
Replace address in the shipping object with the customer's shipping address.
Replace the billing_address fields with the customer's billing address.
Replace number and name in payment_source.card with the card number and cardholder name.
Replace ip_address in supplementary_data.risk.customer with the customer's IP address.

{
  "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": "2028-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"
              }
            }
          }
        }
      }
    }
  }
}

{
  "status": "201 Created",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "6XN26427MP990700L",
    "status": "COMPLETED",
    "payment_source": {
      "card": {
        "name": "John Doe",
        "last_digits": "1111",
        "expiry": "2028-02",
        "brand": "MASTERCARD",
        "available_networks": ["MASTERCARD", "INTERLINK"],
        "type": "DEBIT",
        "bin_details": {
          "bin": "xxxxxx",
          "issuing_bank": "CAPITAL ONE, NATIONAL ASSOCIATION",
          "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" }
    ]
  }
}

Note: If your merchant has not enabled any risk filters, the response is the same as a standard Capture Order response.

2. Get filter failure details for pre-authorization filter failures

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

The response contains the following fields:

status is set to 422 Unprocessable Entity.
details[].issue is set to PAYEE_BLOCKED_TRANSACTION.
details[].description is set to The fraud settings for this seller are such that this payment cannot be executed.
details[].links[].href contains the GET order URL. Use this URL to retrieve order details including the reason for failure and the associated risk filters.

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

{
  "status": "200 OK",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "5O190127TN364715T",
    "status": "CREATED",
    "intent": "CAPTURE",
    "payment_source": {
      "card": {
        "last_digits": "1111",
        "expiry": "2028-02",
        "brand": "VISA"
      }
    },
    "purchase_units": [
      {
        "reference_id": "reference_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" }
    ]
  }
}

The fraud_filter_details object contains the following fields:

status indicates the risk assessment outcome. Possible values:

Status value, Description
Status value	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 lists the filters that executed during risk checks. These are enabled by merchants through Fraud Protection or Fraud Protection Advanced. For more information, see Create and set up filters.

{
  "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": "2028-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"
  }
}

3. Get filter failure details for post-authorization filter failures

If a post-authorization filter fails, the API returns a 201 Created response with a DENY status in fraud_filter_details.

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

{
  "status": "201 Created",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "id": "3W074927CF383080E",
    "status": "COMPLETED",
    "payment_source": {
      "card": {
        "last_digits": "1111",
        "expiry": "2028-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": "2028-02-18T17:42:03Z",
              "update_time": "2028-02-18T17:42:03Z"
            }
          ]
        }
      }
    ],
    "links": [
      { "href": "https://api-m.paypal.com/v2/checkout/orders/3W074927CF383080E", "rel": "self", "method": "GET" }
    ]
  }
}

The fraud_filter_details object contains the following fields:

status is always DENY for post-authorization filter failures.
filters_applied lists the filters that failed. For post-authorization filters, the only possible values are AVS_ZIP_MISMATCH and CVV_MISMATCH.

For orders created with the AUTHORIZE intent, the authorizations array under the payments object contains the following fields:

status is set to DENIED.
status_details.reason is set to DECLINED_BY_RISK_FRAUD_FILTERS.

For orders created with the CAPTURE intent, the captures array under the payments object contains the following fields:

status is set to DECLINED.
status_details.reason is set to DECLINED_BY_RISK_FRAUD_FILTERS.

The processor_response object contains avs_code and cvv_code fields. For code definitions, see processor_response in the Orders v2 API reference.

Note: A GET order request is not required for post-authorization filter failures. The response above contains all failure details.

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

4. Retrieve approved transaction details

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

{
  "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" },
                { "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" }
    ]
  }
}

The risk_assessment.fraud_filter_details object contains the following fields:

status is set to ALLOW for approved transactions.
filters_applied lists the filters that executed during risk checks.

Errors

Feature-specific errors for this task:

Error code, HTTP status, Cause, Resolution
Error code	HTTP status	Cause	Resolution
`PAYEE_BLOCKED_TRANSACTION`	422	A pre-authorization risk filter failed.	Check `details[].links[].href` in the response for the GET order URL. Use it to retrieve the order details and identify the failed filters. Review your merchant's fraud filter configuration. See Create and set up filters.

Test your integration

You must onboard to the RaaS product and integrate with Advanced card processing before testing.

For more information on activating FPA for your merchants, see Activating FPA through partner merchants.

For more information on upgrading merchants from Fraud Protection Standard to FPA, see Upgrade to FPA.

For more information on setting up filters, see Create and set up filters.

Test pre-authorization filter failures

Set up FPA with the appropriate filters and conditions. For example:

Configure a TRANSACTION_AMOUNT_FILTER that fails if the transaction amount exceeds 1000.
Create an order exceeding that amount.
Send an Authorize Order or Capture Order request.

Results: The API returns HTTP 422 UNPROCESSABLE ENTITY. The risk_assessment.status is set to DENY.

Test post-authorization filter failures

Note: The following simulation rules also apply if you have integrated with PayPal's SDK and pass values through SDK hosted fields.

To trigger an AVS filter failure, set address_line_1 in your Orders API request as follows:

"payment_source": {
  "card": {
    "number": "4111111111111111",
    "expiry": "2028-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 trigger a CVV filter failure, set security_code in your Orders API request as follows:

"payment_source": {
  "card": {
    "number": "4111111111111111",
    "expiry": "2028-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.

Integrate Fraud Protection Advanced

Before you begin

Endpoints used

Recommended fields for optimal FPA performance

Device ID

Create order fields

Capture payment for order fields

Supported payment methods

Step-by-step guide

1. Create an order

2. Get filter failure details for pre-authorization filter failures

3. Get filter failure details for post-authorization filter failures

4. Retrieve approved transaction details

Errors

Test your integration

Go live

On this page

On this page

On this page

Integrate Fraud Protection Advanced

Before you begin

Endpoints used

Recommended fields for optimal FPA performance

Device ID

Create order fields

Capture payment for order fields

Supported payment methods

Step-by-step guide

1. Create an order

2. Get filter failure details for pre-authorization filter failures

3. Get filter failure details for post-authorization filter failures

4. Retrieve approved transaction details

Errors

Test your integration

Go live

On this page

On this page

Integrate Fraud Protection Advanced

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

Integrate Fraud Protection Advanced

On this page

On this page