Integration Guides

CallbackURL Retries

Where payments and withdrawals have a callbackUrl field populated, Eclipse will retry these callbacks indefinitely using an exponential back-off algorithm until an HTTP response code less than 300 is received. The algorithm is as follows:

  • Retry twice with a 1 second gap
  • Retry twice with a 10 second gap
  • Retry twice with a 2 minute gap
  • Retry 3 times with a 2 hour gap
  • Retry 19 times with a 24 hour gap
  • Retry 4 times with a 1 week gap
  • Retry once every 30 days from then on

Specifying a Callback URL

The callbackUrl is supplied by the tenant at the time of initiating a payment or withdrawal. Eclipse will POST the completed transaction object to this URL when the transaction reaches a terminal state (e.g. SUCCESSFUL or FAILED).

Example — initiating a payment with a callback URL:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/payments
{
  "paymentType": "EFT",
  "amount": 500.00,
  "currency": "ZAR",
  "walletId": 51234,
  "callbackUrl": "https://myapp.example.com/webhooks/payment-complete",
  "externalUniqueId": "pay-20240315-001"
}

Eclipse will POST a payload like the following to the callbackUrl once the payment completes:

{
  "paymentId": 74881,
  "externalUniqueId": "pay-20240315-001",
  "status": "SUCCESSFUL",
  "amount": 500.00,
  "currency": "ZAR",
  "walletId": 51234,
  "fee": 2.50,
  "paymentReference": "EFT-REF-20240315",
  "created": "2024-03-15T10:26:59.000+02:00"
}

Callback Security

All Eclipse callback requests include an Eclipse-Signature header, which tenants must verify before processing the payload. See the Encryption and Integrity section for verification details.

Disabling Retries

If tenants have large failure rates on callbacks or have excessive system downtime, callback retries may be disabled for the tenant. This is controlled via the global property arch.callback.config using the sub-keys dont.retry.paths.matching and ignore.paths.matching, which accept regex patterns matching the callback URL paths that should not be retried.