Follow-up #2364: response OUR Custom Refund URL must send TO SBPay

API General
1

Thank you @dmytro_bondarev for the reply in topic #2364. That topic is closed, so I am clarifying the remaining question here.

We understand your explanation of the Merchant API /api/order/{id}/refund. We need the contract for the opposite HTTP direction, at the endpoint configured under Payment processors → Custom → Refund URL:

Staff clicks Refund in SBPay Payments → SBPay calls OUR configured Refund URL → our server refunds the original Stripe/PayPay payment → our server sends an HTTP response BACK TO SBPay.

We are implementing the server receiving that callback. Could you please confirm:

  1. Our response to SBPay: Which exact HTTP status, Content-Type and body must OUR server return for success, failure and a provider refund still pending? Is an empty 200 or 204 accepted for this callback, or is a specific JSON body required? Please provide a synthetic callback request/response example, including its request method and Content-Type.
  2. Transport: Does SBPay follow the HTTP redirect from a Google Apps Script ContentService endpoint to script.googleusercontent.com and evaluate its final response? What is the callback timeout, and does SBPay automatically retry after a timeout/lost response?
  3. Recording the same refund: Does accepting our callback response automatically update the SBPay order and SimplyBook invoice? If Stripe completes later, what supported call records that same refund without invoking our Refund URL again? Please state if asynchronous completion is unsupported.

The empty response from the Merchant API in your previous answer does not by itself specify what our callback server must return. A callback handler example or a link to that exact contract would be sufficient.

This is a documentation question only. Please do not change any account or perform a refund. No live identifiers or secrets are needed. Thank you.

3

Hi,

Sorry.

They payload that you will receive in your custom payment processor is following:

"order_id": 123,
"transaction_id": "abc",
"amount": 100.00,
"currency": "EUR",
"timestamp": "2026-10-12T15:19:21+00:00",
"algo": "sha256"

Response must be 2xx (200, 201, etc). It can be empty response.

Yes it supports redirect. Timeout is 3 seconds.

Yes it automatically updates SBPay record.

4

Thank you. We understand that a successful Custom Refund URL response is any 2xx, may have an empty body, supports redirects, has a 3-second timeout, and automatically updates the SBPay record.

One completion/recovery case remains: the original Stripe refund may still be pending, or may succeed after SBPay has timed out. We will not return 2xx before the refund succeeds and will not create a second refund.

  1. If our Refund URL returns a non-2xx response or exceeds 3 seconds, what status does SBPay retain, and does SBPay retry the callback automatically? If staff retry, is it the same order/transaction callback? Please confirm how a provider-pending refund should be reported without marking it refunded prematurely.
  2. After that same provider refund succeeds, which supported API/action records its completion in SBPay? In particular, with a Refund URL configured, does POST /api/order/{id}/refund invoke the URL again? Is there a supported record-only completion operation? If there is no asynchronous completion mechanism, please state that explicitly.

Please also identify exactly which records the automatic update affects: SBPay payment/order only, or the SimplyBook invoice and associated booking cancellation too.

A handler example or exact documentation for these cases is sufficient. This is a documentation question only; please do not change settings or perform a refund. Thank you.