Version: v1.4.x Legacy

Create Payment

Creates a Payment and returns the Payment object including formUrl (a payment link).

API Endpoint:

POST https://uat-sandbox-3ds-api.qi.iq/api/v1/payment

Headers

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

CURL Example

curl --location '<API_HOST>/api/v1/payment' \
--header 'X-Terminal-Id: {terminalId}' \
--header 'Authorization: Basic <Base64<username:password>>' \
--data '{
    "requestId": <GUID>,
    "amount": 1000.00,
    "locale": "en_US",
    "currency": "IQD",
    "finishPaymentUrl": "https://www.merchant.com/finish",
    "notificationUrl": "https://www.merchant.com/webhook-notification"
}'

Request Body

Media type: application/json

Example of a request body:

{
  "requestId": "37b85e60-e7a6-4abb-9466-703472fb83b9",
  "amount": 256.505,
  "currency": "IQD",
  "locale": "en_US",
  "finishPaymentUrl": "https://merchant.net/finish",
  "notificationUrl": "https://merchhant.net/notification",
  "customerInfo": {
    "firstName": "John",
    "middleName": "Mark",
    "lastName": "Doe",
    "phone": "009647xxxxxxxxx",
    "email": "j.doe@gmail.com",
    "accountId": "j.doe",
    "accountNumber": "40817123456787852369",
    "address": "57th street 26",
    "city": "Baghdad"
  },
  "additionalInfo": {
    "key1": "value1",
    "key2": "value2"
  },
  "appChannel": false // false for web payments, true when performing mobile payments!
}

Request body fields

Field	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.
currency	string `required`	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
locale	string `optional`	The locale for the payment form. If not specified, the default locale for the Merchant Terminal will be used..
fees	number `optional`	Merchant Fees, must have two decimels after point `.`
finishPaymentUrl	string `required`	This field specifies the URL where the payer will be redirected after the payment process is completed. The redirection occurs on the client side, and the URL is provided by the merchant. Once the payment is processed, the user is automatically sent to this URL, reflecting the outcome of the transaction, A merchant can use this field to redirect his user back to the merchant side, Maximum characters: 1024
notificationUrl	string `required`	This field is used to provide a webhook URL where the payment gateway will send a POST request to notify the merchant's side of the payment status after the payer completes the transaction. The notification will include in its body the updated data object of the payment (containing the new status: success, pending, or failure), allowing the merchant to track the result of the payment in real time
customerInfo	object `optional`	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.
browserInfo	object `optional`	This field contains details about the browser where the payment is being made, provided by the merchant's side. While this field is optional, if included, certain fields within the browserInfo object are mandatory. When including this object in body request, if any of required fields are missing, the payment gateway will return a “bad request” response.
additionalInfo	object `optional`	Additional information about the payment.
appChannel	boolean `optional`	A boolean value indicate if the payment is being made in app channel or not, the default value is false, When set to true the mobile payment channel will be enabled.

Response Details

200 OK Response

when create payment succeed, you will receive the following payment object:

{
  "requestId": "4256ab83-de74-450f-b442-8fb995458243",
  "paymentId": "f2bb43a8-488a-4281-977b-5b3418fc3c67",
  "status": "CREATED",
  "canceled": false,
  "amount": 256.89,
  "currency": "IQD",
  "creationDate": "2024-08-04T15:34:33Z",
  "formUrl": "https://uat-sandbox-3ds-api.qi.iq/api/v1/payment/f2bb43a8-488a-4281-977b-5b3418fc3c67",
  "additionalInfo": {
    "key1": "value1",
    "key2": "value2"
  }
}

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'.
formUrl	string	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.
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"
  }
}

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

API Endpoint:​

Headers​

CURL Example​

Request Body​

Media type: application/json​

Request body fields​

Response Details​

200 OK Response​

200 OK Response fields​

400 Bad Request​

500 Server Error​