less than a minute read • Updated 20 hours ago
Respond to the pre-payment webhook
The JSON response format for approving or rejecting a transaction, with an example PHP endpoint.
In response, a JSON payload in the following format should be output on the page.
Approve
{
"ok": true,
"details": ""
}
If you’re using the Square Platform payment splitting integration, an additional payment_logic parameter can be passed through as well.
Reject
{
"ok": false,
"details": "Sorry, we're all out of Example Products. Please remove that item from your cart and try again."
}
Only a valid JSON object should be output from your endpoint. If you output anything else on the page that isn’t part of a valid JSON object, the hook fails to process and default handling occurs.
Example endpoint
The following is an example PHP endpoint for handling the pre-payment hook. It’s for illustrative purposes — it will work as-is, but blocking based on IP or email isn’t necessarily a recommended approach.
<?php
$rawPost = file_get_contents('php://input');
$cart_details = json_decode($rawPost, true);
$response = array(
'ok' => true,
'details' => "Sorry, we couldn't process your transaction. Please contact us to proceed."
);
$log_file = './log.txt';
$date = new DateTime();
$date_string = $date->format('Y-m-d H:i:s');
$log_line = $date_string . ': ' . $cart_details['customer_ip'] . ' - '. $cart_details['_embedded']['fx:customer']['email'] . ' -- ';
// Example: Loop through cart items and reject on specific product names
foreach($cart_details['_embedded']['fx:items'] as $item) {
if ($item['name'] == 'Example Product') {
$response['ok'] = false;
$response['details'] = "Sorry, we're all out of Example Products. Please remove that item from your cart and try again.";
}
}
// Example: Reject on specific IP addresses
// The IPs to block should be in a separate file named `ips_to_reject.txt`
// Note that this looks for exact matches.
// If you wanted to check CIDR ranges, try adding something like https://github.com/tholu/php-cidr-match
$ips_to_reject = file('./ips_to_reject.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
if ($ips_to_reject) {
foreach ($ips_to_reject as $ip) {
if ($ip == $cart_details['customer_ip']) {
$log_line .= "IP MATCH: $ip";
$response['ok'] = false;
break;
}
}
}
// Example: Reject on specific email addresses (exact matches)
// The emails to block should be in a separate file named `emails_to_reject.txt`
$emails_to_reject = file('./emails_to_reject.txt', FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
if ($emails_to_reject) {
foreach ($emails_to_reject as $email) {
if (trim($email) == trim($cart_details['_embedded']['fx:customer']['email'])) {
$log_line .= "EMAIL MATCH. REJECTING.";
$response['ok'] = false;
break;
}
}
}
$log_line .= (string) $response['ok'] . "\n";
$fp = fopen($log_file, 'a');
fwrite($fp, $log_line);
header('Content-Type: application/json');
print json_encode($response);
Debugging errors
If your pre-payment hook endpoint fails to return a response, or returns a non-JSON response, an error is added to your store’s error log in the administration.