Cancel Payment

Cancellation Of The Payment. The payment can be canceled if it has not yet entered the processing stage or has been completed successfully and is awaiting confirmation.

API Endpoint:

POST https://uat-sandbox-3ds-api.qi.iq/api/v1/payment/{paymentId}/cancel

Headers

Name	Type	Description	Required
X-Terminal-Id	String	The ID of the Merchant Terminal. Provided by the Acquirer.	Yes

Parameters

Name	Type	Description	Required
paymentId	String	the ID of the payment transaction that want to be refunded.	Yes

CURL Example

curl --location '<API_HOST>/api/v1/payment/{paymentId}/cancel' \
--header 'X-Terminal-Id: {terminalId}' \
--header 'Authorization: Basic <Base64<username:password>>' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "f2bb43a8-488a-4281-977b-5b3418fc3c67"
}'

Request Body

Media type: application/json

Example of a request body:

{
  "requestId": "37b85e60-e7a6-4abb-9466-703472fb83b9"
}

Response Details

200 OK Response

You will receive the following payment object with the following response:

{
  "requestId": "20250302-002826-967",
  "paymentId": "15450bc8-6bd2-4be7-9254-7b9b3634eaf0",
  "status": "CREATED",
  "canceled": true,
  "amount": 1000.0,
  "currency": "IQD",
  "creationDate": "2025-03-02T00:28:27",
  "cancels": [
    {
      "requestId": "20250302-002847-182",
      "created": "2025-03-02T00:28:47",
      "successfully": true,
      "amount": 1000.0
    }
  ],
  "withoutAuthenticate": false,
  "additionalInfo": {}
}

200 OK Response fields

Options	Type	Description
requestId	string	A unique identifier generated by the Merchant's side. It must be ensured that the RequestId remains unique within the context of each Merchant Terminal to prevent duplication or conflicts.
paymentId	string	Payment ID (Transaction ID): the payment transaction reference ID in the Payment Gateway system
status	string	the payment transaction status value, possible values are: SUCCESS, FAILED, CREATED & AUTHENTICATION_FAILED
canceled	boolean	A boolean value indicate if the payment got canceled or not.
amount	number	Specifies the total payment amount, including any applicable fees or commissions from the merchant. This field is required for all payment transactions but should be absent for non-payment transactions. Note non-payment transactions are used to collect card information without processing any payment. This type of transaction is useful when card details are needed for future use, but no immediate charge is required.
currency	string	The ISO 4217 code represents the currency for the payment, for example: IQD - Iraqi Dinar, The value must be exactly 3 characters long, Max value = 3, Min value = 3
creationDate	string	Payment object creation date, follows the ISO 8601 standard, example: '2024-08-04T15:34:33Z'.
cancels	Array[object]	This object contains details about the customer making the payment and is optional for the merchant's side to include when using the create payment request. It helps the merchant track which customer is paying, offering visibility into their payments.
withoutAuthenticate	boolean	If value is false, then the 3DS challage is enabled.
additionalInfo	object	Additional information about the payment.

400 Bad Request

{
  "error": {
    "code": 27,
    "description": "Authentication required: Incorrect credentials"
  }
}

500 Server Error

{
  "error": {
    "code": 23,
    "description": "INTERNAL_SYSTEM_ERROR"
  }
}