Multiparty

FPA API Integration guide

DocsCurrent

Last updated: Feb 5th, 9:51pm

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:

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.

Header

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


Capture payment for order

Field name Description Type Notes
payment_source.card.name The cardholder's name as it shows up on the card. See the parameter definition 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

  1. Request
  2. Response
1{
2    "request": {
3        "method": "POST",
4        "path": "v2/checkout/orders",
5        "headers": {
6            "Content-Type": "application/json",
7            "PayPal-Request-Id": "7b92603e-77ed-4896-8e78-5dea2050476a",
8            "PayPal-Client-Metadata-Id": "pay_ses_1pa68ngmzk5"
9            "Authorization": "Bearer ACCESS-TOKEN"
10        },
11        "body": {
12           "intent": "CAPTURE",
13            "purchase_units": [
14                {
15                    "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
16                    "amount": {
17                        "currency_code": "USD",
18                        "value": "100.00"
19                    },
20                    "shipping": {
21                        "address": {
22                            "address_line_1": "2211 N First Street",
23                            "address_line_2": "Building 17",
24                            "admin_area_2": "San Jose",
25                            "admin_area_1": "",
26                            "state": "",
27                            "postal_code": "95131",
28                            "country_code": "US"
29                        }
30                    },
31                    "supplementary_data": {
32                        "risk": {
33                            "customer": {
34                                "ip_address": "192.158.1.38"
35                            }
36                        }
37                    }
38                }
39            ],
40            "payment_source": {
41                "card": {
42                    "number": "4111111111111111",
43                    "expiry": "2025-02",
44                    "name": "John Doe",
45                    "billing_address": {
46                        "address_line_1": "2211 N First Street",
47                        "address_line_2": "17.3.160",
48                        "admin_area_1": "CA",
49                        "admin_area_2": "San Jose",
50                        "postal_code": "95131",
51                        "country_code": "US"
52                    },
53                    "attributes": {
54                        "customer": {
55                            "id": "n9a9sd",
56                            "email_address": "test123@gmail.com",
57                            "phone": {
58                                "phone_type": "MOBILE",
59                                "phone_number": {
60                                    "country_code": "1",
61                                    "national_number": "4083855946"
62                                }
63                            }
64                        }
65                    }
66                }
67            }
68        }
69    }
70}

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.

  1. Sample request
  2. Sample response
1{
2  "request": {
3    "method": "GET",
4    "path": "v2/checkout/orders/{orderId}",
5    "headers": {
6      "Content-Type": "application/json",
7      "Authorization: "Bearer ACCESS-TOKEN"
8    }
9  }
10}

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:

    1{
    2    "response": {
    3        "status": "201 Created",
    4        "headers": {
    5            "Content-Type": "application/json"
    6        },
    7        "body": {
    8            "id": "1B3121425K9657222",
    9            "intent": "CAPTURE",
    10            "status": "COMPLETED",
    11            "payment_source": {
    12                "card": {
    13                    "name": "txn1",
    14                    "last_digits": "6237",
    15                    "expiry": "2026-01",
    16                    "brand": "VISA",
    17                    "available_networks": [
    18                        "VISA"
    19                    ],
    20                    "type": "CREDIT",
    21                    "bin_details": {
    22                        "bin": "430591983",
    23                        "issuing_bank": "SIERRA CENTRAL CREDIT UNION",
    24                        "bin_country_code": "US"
    25                    }
    26                }
    27            },
    28            "purchase_units": [
    29                {
    30                    "reference_id": "REF123",
    31                    "amount": {
    32                        "currency_code": "USD",
    33                        "value": "13.00"
    34                    },
    35                    "payee": {
    36                        "email_address": "RaaS-DirectMerchant-FT01@abc.com",
    37                        "merchant_id": "YQVPMPGKSQUMW"
    38                    },
    39                    "soft_descriptor": "NATURESKEEP",
    40                    "payments": {
    41                        "captures": [
    42                            {
    43                                "id": "6M8275308Y428715L",
    44                                "status": "COMPLETED",
    45                                "amount": {
    46                                    "currency_code": "USD",
    47                                    "value": "13.00"
    48                                },
    49                                "final_capture": true,
    50                                "seller_protection": {
    51                                    "status": "NOT_ELIGIBLE"
    52                                },
    53                                "seller_receivable_breakdown": {
    54                                    "gross_amount": {
    55                                        "currency_code": "USD",
    56                                        "value": "13.00"
    57                                    },
    58                                    "paypal_fee": {
    59                                        "currency_code": "USD",
    60                                        "value": "0.83"
    61                                    },
    62                                    "net_amount": {
    63                                        "currency_code": "USD",
    64                                        "value": "12.17"
    65                                    }
    66                                },
    67                                "links": [
    68                                    {
    69                                        "href": "https://api.paypal.com/v2/payments/captures/6M8275308Y428715L",
    70                                        "rel": "self",
    71                                        "method": "GET"
    72                                    },
    73                                    {
    74                                        "href": "https://api.paypal.com/v2/payments/captures/6M8275308Y428715L/refund",
    75                                        "rel": "refund",
    76                                        "method": "POST"
    77                                    },
    78                                    {
    79                                        "href": "https://api.paypal.com/v2/checkout/orders/1B3121425K9657222",
    80                                        "rel": "up",
    81                                        "method": "GET"
    82                                    }
    83                                ],
    84                                "create_time": "2024-09-13T14:02:23Z",
    85                                "update_time": "2024-09-13T14:02:23Z",
    86                                "network_transaction_reference": {
    87                                    "id": "497635885629824",
    88                                    "network": "VISA"
    89                                },
    90                                "processor_response": {
    91                                    "avs_code": "Y",
    92                                    "cvv_code": "M",
    93                                    "response_code": "0000"
    94                                }
    95                            }
    96                        ]
    97                    },
    98                    "risk_assessment": {
    99                        "fraud_filter_details": {
    100                            "status": "ALLOW",
    101                            "filters_applied": [
    102                                "Test Approve"
    103                            ]
    104                        }
    105                    }
    106                }
    107            ],
    108            "create_time": "2024-09-13T14:02:23Z",
    109            "update_time": "2024-09-13T14:02:23Z",
    110            "links": [
    111                {
    112                    "href": "https://api.paypal.com/v2/checkout/orders/1B3121425K9657222",
    113                    "rel": "self",
    114                    "method": "GET"
    115                }
    116            ]
    117        }
    118    }
    119}

    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.

    1. Sample request
    2. Sample response
    1{
    2    "request": {
    3        "method": "GET",
    4        "path": "v2/checkout/orders/{orderId}",
    5        "headers": {
    6            "Content-Type": "application/json",
    7            "Authorization": "Bearer ACCESS-TOKEN"
    8        }
    9    }
    10}

    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.

      1"response": {
      2        "status": "422 Unprocessable Entity",
      3        "headers": {
      4            "Content-Type": "application/json"
      5        },
      6        "body": {
      7            "name": "UNPROCESSABLE_ENTITY",
      8            "details": [
      9                {
      10                    "issue": "PAYEE_BLOCKED_TRANSACTION",
      11                    "description": "Declined by fraud tool ( Fraud Protection / Chargeback Protection ) due to potential fraud risk. Please review your fraud settings.",
      12                    "links": [
      13                        {
      14                            "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      15                            "rel": "self",
      16                            "method": "GET"
      17                        }
      18                    ]
      19                }
      20            ],
      21            "message": "The requested action could not be performed, semantically incorrect, or failed business validation",
      22            "debug_id": "9e57901073cf8",
      23            "links": [
      24                {
      25                    "href": "https://developer.paypal.com/docs/api/orders/v2/#error-PAYEE_BLOCKED_TRANSACTION",
      26                    "rel": "information_link",
      27                    "method": "GET"
      28                }
      29            ]
      30        }
      31    }

      Step result

      Request Result
      Single step payment – Risk filter failures HTTP 422 UNPROCESSABLE ENTITY
      Multi step payment – Risk filter failures HTTP 422 UNPROCESSABLE ENTITY
      Confirm payment - Risk filter failures HTTP 422 UNPROCESSABLE ENTITY

      Response parameters with failed pre-authorization filters

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

      1. Sample request
      2. Sample response
      1{
      2  "request": {
      3    "method": "GET",
      4    "path": "v2/checkout/orders/{orderId}",
      5    "headers": {
      6      "Content-Type": "application/json",
      7      "Authorization: "Bearer ACCESS-TOKEN"
      8    }
      9  }
      10}

      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
      ALLOW Fraud Protection allowed this payment.
      DENY/DECLINED Fraud Protection denied this payment.
      PENDING Payment is in the Fraud Protection Review queue
      • filters_applied which describes filters applied during risk checks. These are typically enabled by the merchants through Fraud Protection or Fraud Protection Advanced suites. For example, in the response above, the failed filters were CONFIGURED_FILTER_1 and CONFIGURED_FILTER_2.

      Subscribe to CHECKOUT.ORDER.DECLINED Webhook event

      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.

        1{
        2  "response": {
        3    "status": "200 OK",
        4    "headers": {
        5      "Content-Type": "application/json"
        6    },
        7    "body": {
        8      "id": "WH-COC11055RA711503B-3W074927CF383080E",
        9      "create_time": "2024-01-16T21:21:49.000Z",
        10      "event_type": "CHECKOUT.ORDER.DECLINED",
        11      "resource_type": "checkout-order",
        12      "resource_version": "2.0",
        13      "summary": "Checkout Order Declined due to Risk Fraud Filter failures",
        14      "resource": {
        15        "id": "3W074927CF383080E",
        16        "status": "CREATED",
        17        "payment_source": {
        18          "card": {
        19            "last_digits": "1111",
        20            "expiry": "2025-10",
        21            "brand": "VISA",
        22            "type": "CREDIT"
        23          }
        24        },
        25        "purchase_units": [
        26          {
        27            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
        28            "shipping": {
        29              "address": {
        30                "address_line_1": "2211 N First Street",
        31                "address_line_2": "Building 17",
        32                "admin_area_2": "San Jose",
        33                "admin_area_1": "CA",
        34                "postal_code": "95131",
        35                "country_code": "US"
        36              }
        37            },
        38            "risk_assessment": {
        39              "fraud_filter_details": {
        40                "status": "DENY",
        41                "filters_applied": [
        42                  "TRANSACTION_AMOUNT_FILTER"
        43                ]
        44              }
        45            }
        46          }
        47        ],
        48        "links": [
        49          {
        50            "href": "https://api-m.paypal.com/v2/checkout/orders/3W074927CF383080E",
        51            "rel": "self",
        52            "method": "GET"
        53          }
        54        ]
        55      },
        56      "links": [
        57        {
        58          "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-COC11055RA711503B-3W074927CF383080E",
        59          "rel": "self",
        60          "method": "GET"
        61        },
        62        {
        63          "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-COC11055RA711503B-3W074927CF383080E/resend",
        64          "rel": "resend",
        65          "method": "POST"
        66        }
        67      ],
        68      "zts": 1494957670,
        69      "event_version": "1.0"
        70    }
        71  }
        72}

        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:

          1{
          2  "response": {
          3    "status": "201 Created",
          4    "headers": {
          5      "Content-Type": "application/json"
          6    },
          7    "body": {
          8      "id": "3W074927CF383080E",
          9      "status": "COMPLETED",
          10      "payment_source": {
          11        "card": {
          12          "last_digits": "1111",
          13          "expiry": "2025-10",
          14          "brand": "VISA",
          15          "type": "CREDIT"
          16        }
          17      },
          18      "purchase_units": [
          19        {
          20          "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
          21          "shipping": {
          22            "address": {
          23              "address_line_1": "2211 N First Street",
          24              "address_line_2": "Building 17",
          25              "admin_area_2": "San Jose",
          26              "admin_area_1": "CA",
          27              "postal_code": "95131",
          28              "country_code": "US"
          29            }
          30          },
          31          "risk_assessment": {
          32            "fraud_filter_details": {
          33              "status": "DENY",
          34              "filters_applied": [
          35                "AVS_ZIP_MISMATCH"
          36              ]
          37            }
          38          },
          39          "payments": {
          40            "authorizations": [
          41              {
          42                "id": "1FG40628C3275111G",
          43                "status": "DENIED",
          44                "status_details": {
          45                  "reason": "DECLINED_BY_RISK_FRAUD_FILTERS"
          46                },
          47                "amount": {
          48                  "currency_code": "USD",
          49                  "value": "100.00"
          50                },
          51                "invoice_id": "DEMO-472",
          52                "custom_id": "Custom-ID",
          53                "seller_protection": {
          54                  "status": "NOT_ELIGIBLE"
          55                },
          56                "links": [
          57                  {
          58                    "href": "https://api-m.paypal.com/v2/payments/authorizations/1FG40628C3275111G",
          59                    "rel": "self",
          60                    "method": "GET"
          61                  },
          62                  {
          63                    "href": "https://api-m.paypal.com/v2/checkout/orders/3W074927CF383080E",
          64                    "rel": "up",
          65                    "method": "GET"
          66                  }
          67                ],
          68                "processor_response": {
          69                  "avs_code": "I",
          70                  "cvv_code": "M",
          71                  "response_code": "0000"
          72                },
          73                "create_time": "2025-02-18T17:42:03Z",
          74                "update_time": "2025-02-18T17:42:03Z"
          75              }
          76            ]
          77          }
          78        }
          79      ],
          80      "links": [
          81        {
          82          "href": "https://api-m.paypal.com/v2/checkout/orders/3W074927CF383080E",
          83          "rel": "self",
          84          "method": "GET"
          85        }
          86      ]
          87    }
          88  }
          89}

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

          Subscribe to CHECKOUT.ORDER.COMPLETED Webhook event

          To receive information about transactions declined due to post-authorization risk filters, subscribe to the CHECKOUT.ORDER.COMPLETED Webhook event. A sample response for this event is shown below. In this example, the transaction was declined because the filters AVS_ZIP_MISMATCH and CVV_MISMATCH, configured for the merchant, failed.

            1{
            2    "id": "WH-34M010001R114212F-8LR00246M4043391E",
            3    "event_version": "1.0",
            4    "create_time": "2024-09-11T09:11:03.200Z",
            5    "resource_type": "checkout-order",
            6    "resource_version": "2.0",
            7    "event_type": "CHECKOUT.ORDER.COMPLETED",
            8    "summary": "Checkout Order Completed",
            9    "resource": {
            10        "create_time": "2024-09-11T09:10:18Z",
            11        "purchase_units": [
            12            {
            13                "reference_id": "REF123",
            14                "amount": {
            15                    "currency_code": "USD",
            16                    "value": "6.00",
            17                    "breakdown": {
            18                        "item_total": {
            19                            "currency_code": "USD",
            20                            "value": "6.00"
            21                        },
            22                        "shipping": {
            23                            "currency_code": "USD",
            24                            "value": "0.00"
            25                        },
            26                        "handling": {
            27                            "currency_code": "USD",
            28                            "value": "0.00"
            29                        },
            30                        "insurance": {
            31                            "currency_code": "USD",
            32                            "value": "0.00"
            33                        },
            34                        "shipping_discount": {
            35                            "currency_code": "USD",
            36                            "value": "0.00"
            37                        }
            38                    }
            39                },
            40                "payee": {
            41                    "email_address": "p4pmp_99c58fac-be6b-48f7-ad20-63e7f9f0268a@paypal.com",
            42                    "display_data": {
            43                        "brand_name": "INC"
            44                    }
            45                },
            46                "soft_descriptor": "DEMO",
            47                "payments": {
            48                    "captures": [
            49                        {
            50                            "id": "7SW18441P6357352M",
            51                            "status": "DECLINED",
            52                            "status_details": {
            53                                "reason": "DECLINED_BY_RISK_FRAUD_FILTERS"
            54                            },
            55                            "amount": {
            56                                "currency_code": "USD",
            57                                "value": "6.00"
            58                            },
            59                            "final_capture": true,
            60                            "disbursement_mode": "INSTANT",
            61                            "seller_protection": {
            62                                "status": "NOT_ELIGIBLE"
            63                            },
            64                            "seller_receivable_breakdown": {
            65                                "gross_amount": {
            66                                    "currency_code": "USD",
            67                                    "value": "6.00"
            68                                },
            69                                "net_amount": {
            70                                    "currency_code": "USD",
            71                                    "value": "6.00"
            72                                }
            73                            },
            74                            "links": [
            75                                {
            76                                    "href": "https://api.paypal.com/v2/payments/captures/7SW18441P6357352M",
            77                                    "rel": "self",
            78                                    "method": "GET"
            79                                },
            80                                {
            81                                    "href": "https://api.paypal.com/v2/payments/captures/7SW18441P6357352M/refund",
            82                                    "rel": "refund",
            83                                    "method": "POST"
            84                                },
            85                                {
            86                                    "href": "https://api.paypal.com/v2/checkout/orders/8EY32815388724808",
            87                                    "rel": "up",
            88                                    "method": "GET"
            89                                }
            90                            ],
            91                            "create_time": "2024-09-11T09:10:27Z",
            92                            "update_time": "2024-09-11T09:10:27Z",
            93                            "network_transaction_reference": {
            94                                "id": "895546237854296",
            95                                "network": "VISA"
            96                            },
            97                            "processor_response": {
            98                                "avs_code": "A",
            99                                "cvv_code": "D",
            100                                "response_code": "0000"
            101                            }
            102                        }
            103                    ]
            104                },
            105                "risk_assessment": {
            106                    "fraud_filter_details": {
            107                        "status": "DENY",
            108                        "filters_applied": [
            109                            "AVS_ZIP_MISMATCH",
            110                            "CVV_MISMATCH"
            111                        ]
            112                    }
            113                }
            114            }
            115        ],
            116        "links": [
            117            {
            118                "href": "https://api.paypal.com/v2/checkout/orders/8EY32815388724808",
            119                "rel": "self",
            120                "method": "GET"
            121            },
            122            {
            123                "href": "https://api.paypal.com/checkoutnow?token=8EY32815388724808",
            124                "rel": "approve",
            125                "method": "GET"
            126            },
            127            {
            128                "href": "https://api.paypal.com:18824/v2/checkout/orders/8EY32815388724808",
            129                "rel": "update",
            130                "method": "PATCH"
            131            },
            132            {
            133                "href": "https://api.paypal.com:18824/v2/checkout/orders/8EY32815388724808/capture",
            134                "rel": "capture",
            135                "method": "POST"
            136            },
            137            {
            138                "href": "https://api.paypal.com:18824/v2/checkout/orders/8EY32815388724808/confirm-payment-source",
            139                "rel": "confirm",
            140                "method": "POST"
            141            }
            142        ],
            143        "id": "8EY32815388724808",
            144        "payment_source": {
            145            "card": {
            146                "name": "txnREFUND_AND_REVERSAL",
            147                "last_digits": "9084",
            148                "expiry": "2026-01",
            149                "brand": "VISA",
            150                "available_networks": [
            151                    "VISA"
            152                ],
            153                "type": "CREDIT",
            154                "bin_details": {
            155                    "bin": "407055807",
            156                    "issuing_bank": "SIERRA CENTRAL CREDIT UNION",
            157                    "bin_country_code": "US"
            158                }
            159            }
            160        },
            161        "intent": "CAPTURE",
            162        "status": "CREATED"
            163    },
            164    "links": [
            165        {
            166            "href": "https://api.paypal.com/v1/notifications/webhooks-events/WH-34M010001R114212F-8LR00246M4043391E",
            167            "rel": "self",
            168            "method": "GET"
            169        },
            170        {
            171            "href": "https://api.paypal.com:14084/v1/notifications/webhooks-events/WH-34M010001R114212F-8LR00246M4043391E/resend",
            172            "rel": "resend",
            173            "method": "POST"
            174        }
            175    ]
            176}

            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:

              1"payment_source": {
              2        "card": {
              3          "number": "4111111111111111",
              4          "expiry": "2025-02",
              5          "name": "John Doe",
              6          "billing_address": {
              7            "address_line_1": "AVS_A_971",
              8            "admin_area_1": "CA",
              9            "admin_area_2": "San Jose",
              10            "postal_code": "95131",
              11            "country_code": "US"
              12          }
              13        }
              14      }

              To ensure the CVV filter fails, set the security_code in your Orders API as shown in the following sample:

                1"payment_source": {
                2        "card": {
                3          "number": "4111111111111111",
                4          "expiry": "2025-02",
                5          "name": "John Doe",
                6          "security_code" : 116,
                7          "billing_address": {
                8           "address_line_1": "2211 N First Street",
                9            "address_line_2": "17.3.160",
                10            "admin_area_1": "CA",
                11            "admin_area_2": "San Jose",
                12            "postal_code": "95131",
                13            "country_code": "US"
                14          }
                15        }
                16      }
                ReferencePayPal.comPrivacyCookiesSupportLegalContact

                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