Authorization
prepare
Initialize a QiCard agreement authorization request.
Overview
POST /v1/authorizations/prepare issues an authUrl that merchants use to launch the QiCard signing experience. Supply the agreement scope and descriptive metadata; upon success the API returns a hosted URL for qicardSignContract.
To view the end-to-end diagram, see the Agreement Payment flow.
Endpoint
| Method | Path |
|---|---|
POST | /v1/authorizations/prepare |
API Structure
A message consists of a header and body. The following sections are focused on the body structure. For the header structure, see: OpenAPIs Overview.
Request
| Field | Type | Required | Description |
|---|---|---|---|
scopes | string | Yes | Scope to authorize. Use AGREEMENT_PAY to initiate agreement payments. Max length 16 characters. |
extendInfo | string | Yes | JSON string describing the contract. Max length 4096 characters; disallow @, #, ?. Include keys such as language ("en-US" or "ar-IQ") and contractDesc. |
{
"scopes": "AGREEMENT_PAY",
"extendInfo": "{\"language\":\"en-US\",\"contractDesc\":\"agreement payment description.\"}"
}
Response
| Field | Type | Required | Description |
|---|---|---|---|
result | object | Yes | Outcome metadata with status and codes. |
authUrl | string | No | Hosted authorization URL to pass into qicardSignContract. Returned when result.resultStatus is S. Max length 256 characters. |
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "success"
},
"authUrl": "https://xxxxx.wallet.iq?authId=xxxxx"
}
Result Processing Logic
| Status | Description |
|---|---|
S | Request succeeded. The merchant can redirect users via authUrl. |
U | Result unknown (resultCode: UNKNOWN_EXCEPTION). Retry or inspect Common error codes. |
F | Request failed. Check resultCode and the Error codes table. |
Error Codes
| Error Code | Result Status | Message | Next Step |
|---|---|---|---|
INVALID_SCOPE | F | The provided scope is invalid. | Use a supported scope such as AGREEMENT_PAY. |
PARAM_ILLEGAL | F | Request parameters are invalid (e.g., non-numeric fields, malformed JSON). | Validate payload fields before retrying. |