PayPal Seller Protection

PayPal Seller Protection ensures your eligible sales are protected against unauthorised payments and transactions reversed due to suspicion of fraud. If a buyer claims they didn’t receive an item, your eligible sale is protected when you provide proof of shipment or fulfilment. [1]

High Level Flow


How it works

  1. Merchant's website to get the clientToken from the merchant’s profile.
  2. Merchant's website to send TransactionRiskContext request to a new API endpoint to get ClientMetadataId. In the backend, Wpay will forward the request to PayPal.
  3. Merchant's website then generates device data using ClientMerchantID via the device data collector in BT Client SDK.
  4. The other process to generate a Checkout instance, PayPal tokenization to get Nonce from PayPal and Tokenization process with Wpay remain the same.
  5. When making a payment, the device data string will be added to the existing Making a Payment request payload to connect the payment transaction with TransactionRiskContext required for PayPal seller's protection.

Required Data Attributes

Below are the data attributes that you are required to provide Wpay so they can be passed to PayPal so Seller Protection can be applied to the transaction.


Fields to be passed

PayPal advises to pass as many fields as possible to increase the effectiveness of their risk algorithms for PayPal Seller Protection.

Sender Profile - The fields in this section don't need to be included in the data transmission if either of these conditions exists:

  • The merchant does not require the user to create a merchant account; that is, the user can perform the transaction through a "Guest Checkout" OR
  • The merchant offers PayPal at the cart as a "Shortcut" or as "Checkout with PayPal", so that PayPal provides all the consumer information.

Delivery Information - This field is required for intangible goods only; otherwise, optional

Data Field NameDescriptionData TypeFormatSample
sender_account_idUnique identifier of the buyer account on the partner / merchant platformstringAlphanumericA12345N343
sender_first_nameFirst name registered with the buyer's partner/merchant accountstringAlphanumericJohn
sender_last_nameLast name registered with the buyer's partner/merchant accountstringAlphanumericSmith
sender_emailEmail address registered with the buyer's partner/merchant accountstringE.123 - Email Address[email protected]
sender_phonePhone number (national notation) registered with the buyer's partner/merchant accountstringE.123 - Telephone Number (National Notation)(042) 1123 4567
sender_country_codeCountry code registered with the buyer's partner/merchant accountstringISO Alpha-2 Country CodeUS
sender_create_dateDate of creation of the buyer's account on the partner/merchant platformdateISO 8601 date format2012-12-09T19:14:55.277-0:00
dg_delivery_methodDelivery method for an intangible item if there is an associated email/phone. It acts as the shipping address for an intangible.string{email, phone}email
highrisk_txn_flagFlag for high-risk items such as gift cards / anything cash equivalentBooleanBoolean (0 or 1)0
verticalTransaction level vertical flag for partner/merchant's transactions that are in several verticalsstringAlphanumericRetail

Retrieving the ClientMetadataID

To retrieve the ClientMetadataId use the createtransactionriskcontext endpoint to generate the TransactionRiskContext and send this information to Wpay who will retrieve this value on your behalf from PayPal.

curl --location --request POST 'https://{{environment}}' \
--header 'x-api-key: {{yourApiKey}}' \
--header 'authorization: Bearer {{yourBearerToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
     "senderEmail":"[email protected]",
var myHeaders = new Headers();
var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY";
var accessToken = "ACCESS-TOKEN";
myHeaders.append("Content-Type", "application/json");
myHeaders.append("X-Api-Key", yourAPIkey);
myHeaders.append("Authorization", `Bearer ${accessToken}`);

var raw = JSON.stringify({
  "senderEmail":"[email protected]",

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'

fetch(`https://${environment}`, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking

var semaphore = DispatchSemaphore (value: 0)

let yourAPIkey = "YOUR-API-KEY";
let environment = "substitute environment-value here"
let accessToken = "ACCESS-TOKEN";
let parameters = """
    \"senderEmail\":\"[email protected]\",\
let postData = .utf8)

var request = URLRequest(
  url: URL(string: "https://\(environment)")!,
  timeoutInterval: Double.infinity
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue(yourAPIkey, forHTTPHeaderField: "X-Api-Key")
request.addValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
  print(String(data: data, encoding: .utf8)!)

var myHeaders = new Headers()
var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY"
var accessToken = "ACCESS-TOKEN"
val response =
  url = "https://$environment" + 
  headers = mapOf("Content-Type" to "application/json",
                  "X-Api-Key" to yourAPIkey,
                  "Authorization", "Bearer $accessToken"),
  json = mapOf("senderAccountId" to "A123N23424",
               "senderFirstName" to "John",
               "senderLastName" to "Smith",
               "senderEmail" to "[email protected]",
               "senderPhone" to "0444444444",
               "senderCountryCode"to "AU",
               "senderCreateDate" to "2022-06-09T02:01:41.041Z",
               "dgDeliveryMethod" to "email",
               "highriskTxnFlag" to true,
               "vertical" to "Retail"

if(response.statusCode == 200) {
  val obj : JSONObject = response.jsonObject
  println("Successful response payload: ${obj}")
} else {

TransactionRiskContext Response

  "clientMetadataId": "082029267ff97ffed8c089*********"

Making a Payment

To make a payment using PayPal Seller Protection using the Wpay Platform please follow Making a Payment


  1. PayPal Seller Protection