Returns webhook

wbhk

returns

Payology sends POST to the HTTPS receiver configured for your organization. Authentication/custom headers depend on that configuration; there is no universal signature header in the reviewed sender. Acknowledge durable receipt with any 2xx; the body is receiver-defined and may be empty. Delivery may be repeated: deduplicate by webhook_token and business identifiers. Network failures, 408, 429 and 5xx are retryable; other HTTP errors are terminal except for one configured OAuth token refresh on 401/403. Retry count, delay and HTTP timeout are configurable and were not checked in a live environment.

Receiver acknowledgement

After durably accepting the event, the receiver may return:

HTTP/1.1 204 No Content

An empty HTTP 200 is also accepted. A response JSON body is optional and defined by the receiver.

Returns delivery headers include event-type: Returns, payment-method-type: ACH/PAD/X9, payment-token, mobile-payment and reference-id when available. ACH notices of change (C##) do not produce Returns webhook events in the current return producer.

Payload

JSON payload sent by Payology to the configured receiver.

Return Notice. Field definitions, required properties and payload examples describe its use in the operations below.

payment_return

object

required

Return information associated with the payment, or the return event payload in a webhook.

Headers

webhook-notification

string

enum

required

Fixed marker identifying a Payology webhook delivery.

Allowed:

webhook_token

uuid

required

Delivery-log token reused for retries of that delivery. Store it to deduplicate repeated deliveries.

event-type

string

enum

required

Event name. Files payload shape depends on this header.

Allowed:

payment-method-type

string

enum

required

Payment method of the returned payment: ACH, PAD or X9.

Allowed:

payment-token

uuid

required

UUID of the returned payment; also present in payment_return.payment_token.

reference-id

string

Partner reference of the returned payment, when available.

mobile-payment

string

enum

required

Whether the returned payment originated as a mobile payment; serialized as a header string.

Allowed:

Responses

200

Receiver accepted the event. Response body is optional and defined by the receiver.

204

Receiver accepted the event with no response body.

408

Receiver timeout; delivery is retryable.

429

Receiver rate limit; delivery is retryable.

2XX

Any successful 2xx response acknowledges delivery.

4XX

Other receiver errors generally end this delivery. Configured OAuth may refresh once after 401 or 403.

5XX

Receiver server error; delivery is retryable.