Callbacks

Ayoconnect uses callbacks to notify merchants of Account Validation and Disbursement transaction status updates through HTTPS requests.

Both APIs are processed asynchronously, meaning the initial API response may not contain the final result.

Merchants must register their callback URLs with Ayoconnect during onboarding to receive these notifications.

Supported Callback Types

Important: For Disbursement, merchants must use the latestTransactionStatus field from the callback or Status Inquiry API to determine the transaction outcome, rather than relying solely on the initial API response.

Callback Behavior

Retry Behavior

Ayoconnect automatically retries callback delivery when the merchant's endpoint does not successfully acknowledge the request.

• Initial Attempt: Sent when a callback event is ready for delivery.
• Automatic Retries: Up to 3 additional delivery attempts if the previous attempts are unsuccessful.
• Maximum Attempts: 4 delivery attempts, including the initial attempt.

If all delivery attempts fail, merchants can use the Status Inquiry API to retrieve the latest Disbursement transaction status.

Note: Status Inquiry retrieves the transaction status directly and does not trigger another callback.

Duplicate Callbacks

Merchants may receive the same callback more than once due to delivery retries.

Merchant systems must handle duplicate callbacks safely to prevent repeated transaction updates or unintended actions.

Handling Missing Callbacks

Account Validation

Merchants must confirm successful Account Validation before initiating a Disbursement.

If the callback is delayed or not received, follow the retry and verification instructions in the Account Validation API guide.

Disbursement

If a Disbursement callback is not received within 30 minutes, merchants must:

1. Keep the transaction as Processing.
2. Call the Status Inquiry API, using the original X-EXTERNAL-ID as originalExternalId.
3. Update the transaction based on the returned latestTransactionStatus.
4. Continue monitoring if the transaction remains Pending or its outcome is unknown.

Mandatory: Merchants must not retry or initiate another disbursement while the original transaction remains unresolved. This is required to prevent duplicate fund transfers.

Best Practices

To ensure reliable callback processing, merchants should:

• Use HTTPS: Register secure callback endpoints with valid SSL/TLS certificates.
• Allowlist Ayoconnect IPs: Ensure Ayoconnect's designated callback IP addresses are allowed.
• Return HTTP 2xx: Acknowledge successfully received callbacks promptly to prevent unnecessary retries.
• Handle Callbacks Asynchronously: Process callback events through a background queue when possible.
• Prevent Duplicate Processing: Implement idempotent callback handling.
• Verify Transaction Status: Use the Status Inquiry API when a Disbursement callback is delayed or unavailable.

For more information, refer to Disbursement Retry & Duplicate Prevention, Status Inquiry API, and Integration Preparation & Security.