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

Merchant's website to get the clientToken from the merchant’s profile.
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.
Merchant's website then generates device data using ClientMerchantID via the device data collector in BT Client SDK.
The other process to generate a Checkout instance, PayPal tokenization to get Nonce from PayPal and Tokenization process with Wpay remain the same.
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 Name	Description	Data Type	Format	Sample
sender_account_id	Unique identifier of the buyer account on the partner / merchant platform	string	Alphanumeric	A12345N343
sender_first_name	First name registered with the buyer's partner/merchant account	string	Alphanumeric	John
sender_last_name	Last name registered with the buyer's partner/merchant account	string	Alphanumeric	Smith
sender_email	Email address registered with the buyer's partner/merchant account	string	E.123 - Email Address	[email protected]
sender_phone	Phone number (national notation) registered with the buyer's partner/merchant account	string	E.123 - Telephone Number (National Notation)	(042) 1123 4567
sender_country_code	Country code registered with the buyer's partner/merchant account	string	ISO Alpha-2 Country Code	US
sender_create_date	Date of creation of the buyer's account on the partner/merchant platform	date	ISO 8601 date format	2012-12-09T19:14:55.277-0:00
dg_delivery_method	Delivery 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_flag	Flag for high-risk items such as gift cards / anything cash equivalent	Boolean	Boolean (0 or 1)	0
vertical	Transaction level vertical flag for partner/merchant's transactions that are in several verticals	string	Alphanumeric	Retail

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}}.wpay.com.au/wow/v1/pay/paypal/createtransactionriskcontext' \
--header 'x-api-key: {{yourApiKey}}' \
--header 'authorization: Bearer {{yourBearerToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
     "senderAccountId":"A123N23424",
     "senderFirstName":"John",
     "senderLastName":"Smith",
     "senderEmail":"[email protected]",
     "senderPhone":"0444444444",
     "senderCountryCode":"AU",
     "senderCreateDate":"2022-06-09T02:01:41.041Z",
     "dgDeliveryMethod":"email",
     "highriskTxnFlag":true,
     "vertical":"Retail"
}'

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({
  "senderAccountId":"A123N23424",
  "senderFirstName":"John",
  "senderLastName":"Smith",
  "senderEmail":"[email protected]",
  "senderPhone":"0444444444",
  "senderCountryCode":"AU",
  "senderCreateDate":"2022-06-09T02:01:41.041Z",
  "dgDeliveryMethod":"email",
  "highriskTxnFlag":true,
  "vertical":"Retail"
});

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

fetch(`https://${environment}.wpay.com.au/wow/v1/pay/paypal/createtransactionriskcontext`, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif

var semaphore = DispatchSemaphore (value: 0)

let yourAPIkey = "YOUR-API-KEY";
let environment = "substitute environment-value here"
let accessToken = "ACCESS-TOKEN";
let parameters = """
{\
    \"senderAccountId\":\"A123N23424\",\
    \"senderFirstName\":\"John\",\
    \"senderLastName\":\"Smith\",\
    \"senderEmail\":\"[email protected]\",\
    \"senderPhone\":\"0444444444\",\
    \"senderCountryCode\":\"AU\",\
    \"senderCreateDate\":\"2022-06-09T02:01:41.041Z\",\
    \"dgDeliveryMethod\":\"email\",\
    \"highriskTxnFlag\":true,\
    \"vertical\":\"Retail\"\
}\
"""
let postData = parameters.data(using: .utf8)

var request = URLRequest(
  url: URL(string: "https://\(environment).wpay.com.au/wow/v1/pay/paypal/createtransactionriskcontext")!,
  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))
    semaphore.signal()
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

var myHeaders = new Headers()
var environment = "substitute environment-value here"
var yourAPIkey = "YOUR-API-KEY"
var accessToken = "ACCESS-TOKEN"
      
val response = khttp.post(
  url = "https://$environment" + 
        ".wpay.com.au/wow/v1/pay/paypal/createtransactionriskcontext",
  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 {
  handleError(response)
}

TransactionRiskContext Response

{
  "clientMetadataId": "082029267ff97ffed8c089*********"
}

Making a Payment

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

References