Refund Payment

Full or partial refund to the payer. In the case of a two-stage payment, a refund can be made after confirmation. The amount of all refunds must not exceed the amount of the payment.

API Endpoint:

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

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}/refund' \
--header 'X-Terminal-Id: {terminalId}' \
--header 'Authorization: Basic <Base64<username:password>>' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "20250301-231819-115",
    "amount": 10000.00,
    "message": "I want my money back :)"
}'

Request Body Example

Media type: application/json

Example of a request body:

{
  "requestId": "4256ab83-de74-450f-b442-8fb995458243",
  "amount": 52000.15,
  "message": "customer wants his money back :)",
  // optional object below
  "extParams": {
    "phone": "79997776655",
    "recipientBankId": "100000000001",
    "processRefundAsOct": true
  }
}

Request body fields

Options	Type	Description
requestId	string required	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.
amount	number required	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.
message	string optional	A string feild string can be used for example to document a reason why the user wants his money back.
extParams	object optional	optional additional data object

Response Details

200 OK Response

Refund Returned data:

{
  "refundId": "37b85e60-e7a6-4abb-9466-703472fb83b9",
  "requestId": "37b85e60-e7a6-4abb-9466-703472fb83b9",
  "paymentId": "37b85e60-e7a6-4abb-9466-703472fb83b9",
  "amount": 256.89,
  "status": "SUCCESS",
  "canceled": false,
  "currency": "IQD",
  "creationDate": "2020-05-14T12:06:39Z",
  "message": "Marriage",
  "details": {
    "resultCode": "00",
    "resultDescription": "Successfully",
    "rrn": "433726493310",
    "externalRrn": "123456789012",
    "authId": "39827334",
    "authDate": "2020-05-14T12:06:39Z",
    "maskedPan": "4234********3456",
    "paymentSystem": "VISA",
    "customDetails": {
      "octLimitBalance": "12345678.99"
    }
  }
}

200 OK Response fields

Options	Type	Description
refundId	string	A refund ID is used identify a refund object as a refrence for the refund operation, it can be used to fetch a refund details
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
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.
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.
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'.
message	string	A string feild string can be used for example to document a reason why the user wants his money back.
details	object	additional info about the refund operation.

400 Bad Request

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

500 Server Error

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

Possible Error Codes

• 1 - ORDER_ALREADY_EXISTS
• 2 - ORDER_NOT_FOUND
• 3 - ORDER_ALREADY_CANCELLED
• 4 - NO_COMPATIBLE_SERVICES_FOUND
• 5 - CAN_NOT_PROCESS_REQUEST
• 6 - REQUISITES_NOT_FOUND
• 7 - REQUISITES_ALREADY_EXISTS
• 8 - CAN_NOT_CREATE_NEW_REQUISITES
• 9 - TERMINAL_NOT_FOUND_EXCEPTION
• 10 - PAYMENT_ALREADY_EXISTS
• 11 - MAX_NUMBER_OF_PAYMENTS_FOR_ORDER_EXCEEDED
• 12 - PAYMENT_NOT_FOUND
• 13 - UNKNOWN_STRATEGY
• 14 - PROCESSING_IMPOSSIBLE
• 15 - CAN_NOT_CANCEL_PAYMENT
• 16 - CAN_NOT_CONFIRM_PAYMENT
• 17 - CAN_NOT_FINISH_AUTHENTICATION
• 18 - REFUNDS_NOT_ALLOWED
• 19 - PAYMENT_PARAMS_NOT_FOUND
• 20 - REFUND_ERROR
• 21 - VALIDATION_ERROR
• 22 - INCORRECT_PAYMENT_STATE
• 23 - INTERNAL_SYSTEM_ERROR
• 24 - EXTERNAL_SYSTEM_ERROR
• 26 - INVALID_PAYMENT_FORM_DOMAIN
• 27 - BAD_CREDENTIALS
• 28 - LIMIT_VIOLATION
• 29 - TRANSFER_NOT_FOUND
• 30 - INCORRECT_TRANSFER_STATE
• 31 - TOKEN_NOT_FOUND
• 32 - TOKEN_PROCESS_NOT_ALLOWED
• 33 - CAN_NOT_CANCEL_TRANSFER
• 34 - TRANSFER_ALREADY_EXISTS
• 35 - INVALID_TOKEN_TYPE