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

When a request fails, the response's error object contains the numeric code and its description. Use the code for programmatic handling and the name for logging.

Code	Error name	Description
1	ORDER_ALREADY_EXISTS	An order with the same identifier already exists.
2	ORDER_NOT_FOUND	No order was found for the supplied identifier.
3	ORDER_ALREADY_CANCELLED	The order has already been cancelled.
4	NO_COMPATIBLE_SERVICES_FOUND	No service compatible with the request could be found.
5	CAN_NOT_PROCESS_REQUEST	The request could not be processed.
6	REQUISITES_NOT_FOUND	The requested requisites do not exist.
7	REQUISITES_ALREADY_EXISTS	Requisites with the same details already exist.
8	CAN_NOT_CREATE_NEW_REQUISITES	New requisites could not be created.
9	TERMINAL_NOT_FOUND_EXCEPTION	The specified terminal (X-Terminal-Id) was not found.
10	PAYMENT_ALREADY_EXISTS	A payment with the same identifier already exists.
11	MAX_NUMBER_OF_PAYMENTS_FOR_ORDER_EXCEEDED	The order has reached its maximum number of payments.
12	PAYMENT_NOT_FOUND	No payment was found for the supplied identifier.
13	UNKNOWN_STRATEGY	The requested processing strategy is not recognized.
14	PROCESSING_IMPOSSIBLE	The payment cannot be processed in its current state.
15	CAN_NOT_CANCEL_PAYMENT	The payment cannot be cancelled.
16	CAN_NOT_CONFIRM_PAYMENT	The payment cannot be confirmed.
17	CAN_NOT_FINISH_AUTHENTICATION	Authentication (3DS) could not be completed.
18	REFUNDS_NOT_ALLOWED	Refunds are not allowed for this payment.
19	PAYMENT_PARAMS_NOT_FOUND	The required payment parameters were not found.
20	REFUND_ERROR	An error occurred while processing the refund.
21	VALIDATION_ERROR	One or more request fields failed validation.
22	INCORRECT_PAYMENT_STATE	The payment is not in a valid state for this operation.
23	INTERNAL_SYSTEM_ERROR	An unexpected internal error occurred.
24	EXTERNAL_SYSTEM_ERROR	An error was returned by an external system.
26	INVALID_PAYMENT_FORM_DOMAIN	The payment form domain is invalid.
27	BAD_CREDENTIALS	The supplied authentication credentials are invalid.
28	LIMIT_VIOLATION	The operation exceeds a configured limit.
29	TRANSFER_NOT_FOUND	No transfer was found for the supplied identifier.
30	INCORRECT_TRANSFER_STATE	The transfer is not in a valid state for this operation.
31	TOKEN_NOT_FOUND	The specified payment token does not exist.
32	TOKEN_PROCESS_NOT_ALLOWED	The requested operation is not allowed for this token.
33	CAN_NOT_CANCEL_TRANSFER	The transfer cannot be cancelled.
34	TRANSFER_ALREADY_EXISTS	A transfer with the same identifier already exists.
35	INVALID_TOKEN_TYPE	The supplied token type is invalid.

note

The full, canonical list of gateway error codes is maintained on the API Error Codes page. Code 25 is not currently in use.