Disbursement Callback

Introduction

This part of documentation describes the callback mechanism used to send transaction status updates to the merchant's callback URL. When a disbursement transaction is initiated and its state changes, a callback containing relevant data is sent to the specified callback URL. This allows the merchant to receive real-time updates on the state of disbursement transactions.

The callback request includes both headers and a payload with payment details. It also contains an HMAC signature (X-Signature) for ensuring data integrity and security.

Callback Headers

The callback request contains the following headers:

Header	Description
Content-Type	"application/json"
X-Signature	The HMAC signature used for verification.

Example Headers

POST /your/callback/url HTTP/1.1
Content-Type: application/json
X-Signature: <hash_str>

Callback Parameters

Property	Type	Description
creedo_disbursement_id	String	Creedo generated disbursement ID for this disbursement creation request. This disbursement ID can be used later to track down the disbursement and in other disbursement related APIs.
merchant_disbursement_id	String	The merchant invoice number is a unique identifier assigned to a disbursement by the merchant.
disbursement_amount	Integer	This parameter specifies the total disbursement amount specified in the create disbursement API call.
disbursement_currency	String	Currency of the mentioned amount.
disbursement_method	String	disbursement method of the mentioned order.
creation_time	String	The time when the disbursement was created. Format is "dd-mm-YYYY H:M:S p".
paid_at	String or Null	The time when the disbursement was made. The "paid_at" parameter will be provided only if the payment has been completed; otherwise, it will not be included. The format is "dd-mm-YYYY H:M:S p".
disbursement_status	String	Current status of this disbursement.

Example Callback Request Parameters (JSON)

{
    "creedo_disbursement_id": "6AQ027SVVS",
    "merchant_disbursement_id": "1234",
    "disbursement_method": "JAZZCASH_P2C",
    "disbursement_currency": "PKR",
    "disbursement_amount": 550,
    "creation_time": "2024-09-03 06:53:24 PM",
    "paid_at":  "2024-09-03 06:56:24 PM",
    "disbursement_status": "paid"
}

Signature Verification

The callback request includes an X-Signature header, which is an HMAC signature generated using the secret_key. To ensure the integrity of the request, you must verify the signature before processing the payload.

Signature Generation

The signature (X-Signature) is generated using HMAC with SHA-256. It uses the secret_key and a secret_string as inputs. All inputs should be in string format:

secret_string = creedo_disbursement_id:merchant_disbursement_id:disbursement_method:disbursement_currency:disbursement_amount:disbursement_status

Expected Response

The callback handler should return an HTTP 200 OK status if the callback is successfully processed.

Example Success Response

{
    "status": "success"
}

Error Handling

If the signature verification fails or any other error occurs, respond with an appropriate HTTP status code:

• 400 Bad Request: If required parameters are missing.
• 403 Forbidden: If the signature verification fails.
• 500 Internal Server Error: If an unexpected error occurs.

Security Measures

• Merchants should validate the IP address of incoming requests to ensure they originate from a trusted source.
• Merchants should call the Query Payment API to verify the legitimacy of the callback and confirm the current payment status.