Risk and fraud management

PayPal requires risk-related data to properly mitigate transaction risks while setting up payment methods and processing payments. 

Pass risk management data

1. Call the CreateTransactionRiskContext mutation to send risk-related data to PayPal. The mutation sends a clientMetadataId.
Important
Contact the PayPal sales team to determine the list of key-value pairs to include in the API call. It depends on your industry and the data you have available.
Mutation

Copy

mutation CreateTransactionRiskContext(
  $input: CreateTransactionRiskContextInput!
) {
  createTransactionRiskContext(input: $input) {
    clientMetadataId
    paypalRiskCorrelationId
  }
}

Variables

Copy

{
  "input": {
    "riskContext": {
      "fields": [
        {
          "name": "sender_account_id",
          "value": "xyz123"
        },
        {
          "name": "txn_count_total",
          "value": "15987"
        }
      ]
    }
  }
}

Response

Copy

{
  "data": {
    "createTransactionRiskContext": {
      "clientMetadataId": "01e59aa07d2187e13b1bf9cf42a45596",
      "paypalRiskCorrelationId": "01e59aa07d2187e13b1bf9cf42a45596"
    }
  }
}

2. Pass the clientMetadataId either when saving or charging the payment method. It is when the risk evaluation happens.

Pass device data

1. Gather device data from your customers. 
2. Pass the collected information through the deviceData parameter inside riskData. Including device data increases the accuracy in determining fraudulent transactions.
Mutation

Copy

mutation ChargePayPalAccount($input: ChargePayPalAccountInput!) {
  chargePayPalAccount(input: $input) {
    transaction {
      id
      amount {
        value
        currencyCode
      }
      paymentMethodSnapshot {
        ... on PayPalTransactionDetails {
          captureId
          payerStatus
        }
      }
    }
  }
}

Variables

Copy

{
  "input": {
    "paymentMethodId": "id_of_payment_method",
    "transaction": {
      "amount": "10.00",
      "orderId": "id_of_order",
      "riskData": {
        "customerBrowser": "web_browser_type",
        "customerIp": "ip_address",
        "deviceData": "device_type"
      },
      "vaultPaymentMethodAfterTransacting": {
        "when": "ON_SUCCESSFUL_TRANSACTION"
      }
    },
    "options": {
      "customField": "PayPal custom field",
      "description": "Description for PayPal email reciept"
    }
  }
}

Response

Copy

{
  "data": {
    "chargePayPalAccount": {
      "transaction": {
        "id": "id_of_transaction",
        "amount": {
          "value": "10.00",
          "currencyCode": "USD"
        },
        "paymentMethodSnapshot": {
          "captureId": "id_of_capture",
          "payerStatus": "VERIFIED"
        }
      }
    }
  },
  "extensions": {
    "requestId": "a-uuid-for-the-request"
  }
}

Note
You can pass the device data if it is not a recurring transaction initiated from Vault records. It helps reduce decline rates.