Flows

Escrow Payment

End-to-end guide for buyer-protected escrow payments with merchant acceptance and customer confirmation.

Overview

Escrow payment provides buyer protection by holding funds in escrow until the customer confirms receipt of goods or services. This flow requires multiple API calls throughout the transaction lifecycle: payment initiation, merchant acceptance, and customer confirmation (or void/cancel if issues arise).

The escrow flow ensures that:

Funds are held securely until the merchant fulfills the order
Merchants must explicitly accept orders before fulfillment
Customers can confirm receipt to release funds
Merchants can void/cancel if fulfillment cannot be completed

Escrow payment uses the special product code 51051000101000100008. Standard cashier payments use a different product code and complete immediately without the acceptance/confirmation steps.

Complete Escrow Flow

1. Initial Payment (Cashier Mode)

The flow starts like a standard cashier payment, but uses the escrow product code.

Steps 1-18: Follow the standard cashier payment flow:

Mini Program gets authorization via my.getAuthCode
Merchant backend exchanges authCode for accessToken via applyToken
Mini Program creates order and sends to merchant backend
Merchant backend calls pay API with escrow product code
Customer completes payment in wallet cashier
Funds are held in escrow (not released to merchant yet)

Request to /v1/payments/pay:

{
  "productCode": "51051000101000100008",
  "paymentRequestId": "escrow_order_20240101_123456",
  "paymentAmount": {
    "currency": "IQD",
    "value": "500000"
  },
  "order": {
    "orderDescription": "iPhone 15 Pro - Space Black",
    "buyer": {
      "referenceBuyerId": "216610000000003660xxxx"
    }
  },
  "paymentNotifyUrl": "https://www.merchant.com/notify/payment",
  "paymentRedirectUrl": "https://www.merchant.com/order/return"
}

Response:

{
  "result": {
    "resultCode": "ACCEPT",
    "resultStatus": "A",
    "resultMessage": "accept"
  },
  "paymentId": "2024010111121280010016600900000xxxx",
  "redirectActionForm": {
    "redirectionUrl": "https://www.wallet.com/cashier?orderId=xxxxxxx"
  }
}

2. Merchant Accepts Order

After payment is completed, the merchant reviews the order (checks inventory, validates delivery address, etc.) and must explicitly accept it to proceed with fulfillment.

API: POST /v1/payments/merchantAccept

Request:

{
  "paymentId": "2024010111121280010016600900000xxxx"
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  }
}

Why Accept? The acceptance step commits the merchant to fulfilling the order. If the merchant cannot fulfill (out of stock, delivery issue, etc.), they should not accept and should instead use the cancel API.

3. Fulfillment & Delivery

After acceptance, the merchant:

Prepares and ships the goods
Provides tracking information to customer
Delivers the product/service

During this phase, the funds remain in escrow.

4. Customer Confirms Receipt

Once the customer receives and verifies the goods/services are satisfactory, they confirm receipt through the Mini Program. This releases the escrowed funds to the merchant.

API: POST /v1/payments/confirm

Request:

{
  "paymentId": "2024010111121280010016600900000xxxx",
  "confirmRequestId": "confirm_20240115_789012"
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "confirmId": "202401151112128001016xxxx",
  "confirmTime": "2024-01-15T14:30:22+03:00"
}

Irreversible Action: Once confirmed, funds are immediately released to the merchant and cannot be reversed. Customers should only confirm after verifying goods are satisfactory.

Transaction Complete

The escrow payment is now complete and the merchant receives the funds.

Alternative Flows

Cancel Before Acceptance

If the merchant decides not to accept the order (e.g., out of stock, cannot deliver), they can cancel the payment before calling merchantAccept. This immediately returns the full amount to the customer.

API: POST /v1/payments/cancel

Use when:

Merchant is out of stock
Cannot deliver to customer's location
Pricing error on the order
Payment result delayed and merchant wants to cancel

Request:

{
  "paymentId": "2024010111121280010016600900000xxxx"
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "paymentId": "2024010111121280010016600900000xxxx",
  "cancelTime": "2024-01-01T15:20:10+03:00"
}

Important: After calling merchantAccept, you cannot use cancel. Use void instead.

Void After Acceptance

If issues arise after the merchant has accepted the order but before/during delivery, the merchant can initiate a void to return funds to the customer.

API: POST /v1/payments/void

Use when:

Merchant accepted but cannot fulfill (supplier issue, damaged goods, etc.)
Delivery failed or goods cannot be delivered
Goods were damaged and cannot be replaced
Any other fulfillment issue preventing order completion

Full Void Request:

{
  "voidRequestId": "void_20240105_345678",
  "paymentId": "2024010111121280010016600900000xxxx"
}

Partial Void Request:

{
  "voidRequestId": "void_20240105_345678",
  "paymentId": "2024010111121280010016600900000xxxx",
  "voidAmount": {
    "value": "200000",
    "currency": "IQD"
  }
}

Response:

{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success."
  },
  "voidRequestId": "void_20240105_345678",
  "voidId": "202401051112128017xxxx"
}

Partial vs Full Void:

Full void: Returns entire amount and closes the order
Partial void: Returns part of the amount; order remains open with timeout for remaining funds

Refund After Completion

If the customer already confirmed receipt but later discovers issues (defective product, wrong item, etc.), the merchant can issue a refund.

API: POST /v1/payments/refund

Use when:

Customer confirmed but goods were defective
Wrong item was delivered
Customer changed mind after confirmation (merchant's discretion)
Warranty claim or return processing

Request:

{
  "refundRequestId": "refund_20240120_901234",
  "paymentId": "2024010111121280010016600900000xxxx",
  "refundAmount": {
    "value": "500000",
    "currency": "IQD"
  }
}

Key Differences: Escrow vs Standard Payment

Aspect	Standard Cashier Payment	Escrow Payment
Product Code	`51051000101000000011`	`51051000101000100008`
Fund Release	Immediate	After customer confirmation
Merchant Action	None required	Must call `merchantAccept`
Customer Action	None required	Must call `confirm` to release funds
Buyer Protection	Standard wallet policies	Extended protection with escrow hold
After Acceptance	Use `refund` after completion	Use `void` before completion, `refund` after

Polling Payment Status

Since escrow payments involve multiple steps, use inquiryPayment to check the current transaction status:

API: POST /v1/payments/inquiryPayment

Request:

{
  "paymentId": "2024010111121280010016600900000xxxx"
}

Response includes:

paymentStatus: Current payment status (PROCESSING, SUCCESS, FAIL, etc.)
transactions: Array of all transaction operations (PAY, VOID, REFUND, etc.)

Common Error Codes

merchantAccept Errors

resultCode	Cause	Action
`ORDER_STATUS_INVALID`	Payment not completed or already accepted	Verify payment status via `inquiryPayment`
`ORDER_IS_MERCHANT_ACCEPTED`	Already accepted	No action needed
`ORDER_NOT_EXIST`	Invalid payment ID	Verify `paymentId`

void Errors

resultCode	Cause	Action
`ORDER_STATUS_INVALID`	Order cannot be voided in current status	Check if already voided/cancelled/confirmed
`VOID_AMOUNT_EXCEEDS_AUTH_LIMIT`	Void amount exceeds payment amount	Reduce void amount
`MUTEX_OPERATION_IN_PROCESSING`	Another operation in progress	Wait and retry
`ORDER_UNSUPPORTED_OPERATION`	Non-escrow payment	Only escrow payments support void

confirm Errors

resultCode	Cause	Action
`ORDER_STATUS_INVALID`	Merchant hasn't accepted yet	Wait for merchant acceptance
`MUTEX_OPERATION_IN_PROCESSING`	Void/refund in progress	Wait and retry
`ORDER_NOT_EXIST`	Invalid payment ID	Verify `paymentId`

cancel Errors

resultCode	Cause	Action
`ORDER_HAS_BEEN_CAPTURED`	Already confirmed/completed	Use `refund` instead
`ORDER_HAS_BEEN_VOIDED`	Already voided	No action needed
`CANCEL_WINDOW_EXCEED`	Too late to cancel	Use `void` or `refund`

pay - Initiate escrow payment
merchantAccept - Accept the order
confirm - Confirm receipt and release funds
void - Void payment after acceptance
cancel - Cancel before acceptance
refund - Refund after completion
inquiryPayment - Query payment status

Best Practices

Always check payment status before calling merchantAccept to ensure payment was successful
Set reasonable timeouts for acceptance and confirmation to avoid funds being held indefinitely
Implement notifications for all payment events (payment, acceptance, confirmation, void, etc.)
Validate inventory before accepting orders to avoid accepting orders you cannot fulfill
Provide tracking information to customers after acceptance to reduce disputes
Handle async notifications properly as some operations may complete asynchronously
Use idempotent IDs (voidRequestId, confirmRequestId) to safely retry failed operations
Monitor for UNKNOWN_EXCEPTION status and poll inquiryPayment rather than assuming failure

Agreement Payment

End-to-end guide for setting up recurring payments via QiCard agreement authorization.

Overview

Complete guide to Super Qi's backend-to-backend OpenAPIs for Mini Programs.