Payment Callback

Introduction

This section describes the callback mechanism used to send payment status updates to the merchant's callback URL. When a payment 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 payment 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_payment_id	String	Creedo-generated payment ID for this payment creation request. This payment ID can be used later to track the payment and in other payment-related APIs.
merchant_payment_id	String	Unique invoice number used on the merchant side for this specific payment.
payment_amount	Integer	Specifies the total payment amount set in the create payment API call.
received_amount	Integer or null	Indicates the amount of the payment that has been successfully received by Creedo.
payment_currency	String	Currency of the mentioned amount.
payment_method	String	Payment method of the mentioned order.
creation_time	String	The time when the payment was created.
payment_status	String	Current state of this payment.

Example Callback Payload

{
    "creedo_payment_id": "8QAR88VWQ8",
    "merchant_payment_id": "37862050",
    "payment_method": "NAGAD_P2P",
    "payment_currency": "BDT",
    "payment_amount": 550,
    "received_amount": 550,
    "creation_time": "2025-10-27T12:10:34.425Z",
    "payment_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_payment_id:merchant_payment_id:payment_method:payment_currency:payment_amount:payment_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.