AsiaPay Payment Gateway Integration

Comprehensive guide to integrate AsiaPay's secure online payment services into your application

Introduction

AsiaPay is a secure online payment gateway that enables merchants to process payments in Iraqi Dinar (IQD). This documentation provides developers with a comprehensive guide to integrate AsiaPay's payment services seamlessly into their applications.

Secure Payments

Process payments securely using industry-standard encryption and authentication mechanisms.

Easy Integration

Simple API allows for quick and hassle-free integration with your existing systems.

IQD Support

Full support for Iraqi Dinar (IQD) transactions with competitive processing fees.

Integration Flow

The diagram below illustrates the standard flow of integrating and processing payments with AsiaPay:

Payment Processing Flow
flowchart TD A[Start Integration] --> B[Initialize Client] B --> C[Get Authentication Token] C --> D[Create Payment Order] D --> E[Redirect User to Payment Page] E --> F[User Completes Payment] F --> G[Payment Notification to Merchant] G --> H[Redirect to Success/Failure Page] style A fill:#18BC9C,stroke:#128F76,color:white style E fill:#3498DB,stroke:#2980B9,color:white style F fill:#3498DB,stroke:#2980B9,color:white style H fill:#18BC9C,stroke:#128F76,color:white
Initialize Client

Create an instance of the AsiaPay client with your API credentials.

Authenticate

Obtain an authentication token using your App Key and App Secret.

Create Order

Generate a payment order with the required transaction details.

Redirect to Payment

Redirect the customer to the AsiaPay payment page using the URL from the order response.

Handle Callback

Process the payment notification and redirect the customer back to your application.

Prerequisites

Before you begin integration with AsiaPay, ensure you have the following:

Merchant Account

You must have a registered merchant account with AsiaPay. Contact AsiaPay support to create an account if you don't have one already.

API Credentials

The following credentials will be provided by AsiaPay after your merchant account is approved:

  • Domain URL (Production and Sandbox)
  • App Key
  • App Secret
  • Private Key
  • Merchant Code
  • App ID
  • Integration credentials – Used for JWT encoding/decoding.

Technical Requirements

Note: The integration examples in this documentation are based on PHP. However, the API can be integrated with any programming language that supports HTTP requests.

For PHP integration, you'll need:

  • PHP 7.0 or higher
  • Firebase JWT library (composer require firebase/php-jwt)
  • cURL extension enabled

Authentication

AsiaPay uses a token-based authentication system. You must first obtain a token before making any API calls.

Authentication Flow

  1. Make a POST request to the token endpoint using your App Key and App Secret
  2. Store the received token for subsequent API calls
  3. Include the token in the Authorization header for all API requests

Important: Authentication tokens are valid for a limited time. If a token expires, you'll need to generate a new one.

API Reference

This section details the endpoints available in the AsiaPay API.

Get Token

Authenticates and retrieves an access token.

Endpoint /payment/gateway/payment/v1/token
Method POST
Content Type application/json

Headers:

Header Value Description
X-APP-Key Your App Key API key provided by AsiaPay
Content-Type application/json Request body format

Request Body:

JSON
{
  "appSecret": "YOUR_APP_SECRET"
}

Response:

JSON
{"token":"Bearer 76e0ac549fce799159aaf558694815c6","effectiveDate":"20250506233829","expirationDate":"20250507003829"}

Create Order

Creates a payment order and returns a redirect URL for the payment page.

Endpoint /payment/gateway/payment/v1/merchant/preOrder
Method POST
Content Type application/json

Headers:

Header Value Description
X-APP-Key Your App Key API key provided by AsiaPay
Content-Type application/json Request body format
Authorization eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ.. Authorization Token

Request Parameters

Create Order Parameters

Parameter Type Required Description
appid String Yes Application ID provided by AsiaPay
business_type String Yes Type of transaction (e.g., "BuyGoods")
merch_code String Yes Merchant code provided by AsiaPay
merch_order_id String Yes Unique order ID generated by merchant
redirect_url String Yes URL to redirect after payment completion
notify_url String Yes Webhook URL for payment notifications
timeout_express String Yes Order expiration time (e.g., "30m" for 30 minutes)
title String Yes Order title/description
total_amount String Yes Transaction amount (e.g., "12.00")
trade_type String Yes Payment method type (e.g., "Checkout")
trans_currency String Yes Transaction currency (fixed to "IQD")

Request Body:

JSON
{
                    "biz_content": {
                        "appid": "YOUR_APP_ID",
                        "business_type": "BuyGoods",
                        "merch_code": "YOUR_MERCHANT_CODE",
                        "merch_order_id": "UNIQUE_ORDER_ID",
                        "redirect_url": "YOUR_REDIRECT_URL",
                        "notify_url": "YOUR_NOTIFICATION_URL",
                        "timeout_express": "30m",
                        "title": "Order Title",
                        "total_amount": "12.00",
                        "trade_type": "Checkout",
                        "trans_currency": "IQD"
                    },
                    "method": "payment.preorder",
                    "nonce_str": "RANDOM_UNIQUE_STRING",
                    "sign_type": "JWTSecret",
                    "timestamp": "CURRENT_TIMESTAMP",
                    "version": "1.0",
                    "sign": "JWT_SIGNATURE"
                }

Response:

JSON
{
                    "result": "SUCCESS",
                    "code": "0",
                    "msg": "success",
                    "nonce_str": "8941e36049bf4c2a9534a5ea11f81e51",
                    "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                    "sign_type": "JWTSecret",
                    "biz_content": {
                        "merch_order_id": "212291746601184",
                        "prepay_id": "120bfb1ccc3a532b197cdb6fafad7493643002",
                        "redirect_url": "https://apitest.asiapay.iq:5443/payment/web/paygate?appid=1170344370329602&merch_code=260224&nonce_str=8941e36049bf4c2a9534a5ea11f81e51&prepay_id=120bfb1ccc3a532b197cdb6fafad7493643002×tamp=1746601183&sign=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...&sign_type=JWTSecret&version=1.0&trade_type=Checkout&language=en"
                    }
                }

Query Order

Checks the payment status of a previously created order using the merchant order ID.

Endpoint /payment/gateway/payment/v1/merchant/queryOrder
Method POST
Content Type application/json

Headers:

Header Value Description
X-APP-Key Your App Key API key provided by AsiaPay
Content-Type application/json Request body format
Authorization Bearer {your_token} Authorization Token (JWT)

Request Parameters

Query Order Parameters

Parameter Type Required Description
appid String Yes Application ID provided by AsiaPay
merch_code String Yes Merchant code provided by AsiaPay
merch_order_id String Yes Unique order ID to query

Request Body:

JSON
{ "biz_content": { "appid": "1170344370329602", "merch_code": "260224", "merch_order_id": "20251746539388" }, "method": "payment.queryorder", "nonce_str": "d3ef4d049ec44150b212efa76b7e2aa7", "sign_type": "JWTSecret", "timestamp": "CURRENT_TIMESTAMP", "version": "1.0", "sign": "JWT_SIGNATURE" }

Response:

JSON
{ "result": "SUCCESS", "code": "0", "msg": "success", "nonce_str": "24755162ba4d42bcab7f411b55d6ead3", "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "sign_type": "JWTSecret", "biz_content": { "merch_order_id": "20251746539388", "order_status": "PAY_SUCCESS", "trans_currency": "IQD", "total_amount": "1250.000", "trans_id": "0377830000000660613", "trans_time": "2025-05-06 16:50:06", "payment_order_id": "120011075616500500001001" } }

Refund Order

Initiates a refund for an existing payment order.

Endpoint /payment/gateway/payment/v1/merchant/refund
Method POST
Content Type application/json

Headers:

Header Value Description
X-APP-Key Your App Key API key provided by AsiaPay
Content-Type application/json Request body format
Authorization Bearer YOUR_TOKEN JWT Bearer token for authentication

Request Parameters

Refund Parameters

Parameter Type Required Description
appid String Yes Application ID provided by AsiaPay
merch_code String Yes Merchant code provided by AsiaPay
merch_order_id String Yes Original order ID to be refunded
refund_request_no String Yes Unique ID for this refund request
refund_reason String Yes Reason for the refund

Request Body:

JSON
{ "biz_content": { "appid": "1170344370329602", "merch_code": "260224", "merch_order_id": "20251746603699", "refund_request_no": "20250507", "refund_reason": "Wala Etr" }, "method": "payment.refund", "nonce_str": "1c6c09a41156478b892626cc5d383fa0", "sign_type": "JWTSecret", "timestamp": "1746603834", "version": "1.0", "sign": "JWT_SIGNATURE" }

Response:

JSON
{ "result": "SUCCESS", "code": "0", "msg": "success", "nonce_str": "0f710dce49a94f12a1bd3476121c45f6", "sign": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "sign_type": "JWTSecret", "biz_content": { "merch_order_id": "20251746603699", "trans_order_id": "120011075710424400001001", "refund_order_id": "120010075710435500001001", "refund_amount": "1250.000", "refund_currency": "IQD", "refund_status": "REFUND_SUCCESS", "refund_time": "2025-05-07 10:43:55", "business_type": "BuyGoods" } }

Code Examples

Complete Integration Example

Copy
Download
<?php
                        // 1. Include the AsiaPay Integration Class
                        require_once 'AsiaPayIntegration.php';

                        // 2. Configure your API credentials
                        $domain = "https://apitest.asiapay.iq:5443/apiaccess";
                        $appKey = "your-app-key";
                        $appSecret = "your-app-secret";
                        $privateKey = "your-private-key";

                        // 3. Set up order parameters
                        $appid = "your-app-id";
                        $businessType = "BuyGoods";
                        $merchCode = "your-merchant-code";
                        $merchOrderId = "ORDER" . time(); // Generate unique order ID
                        $redirectUrl = "callbackUrl=your.app.scheme";
                        $notifyUrl = "https://your-server.com/webhook";
                        $timeoutExpress = "30m";
                        $title = "Product Purchase";
                        $totalAmount = "50.00";
                        $tradeType = "Checkout";

                        try {
                            // 4. Initialize the AsiaPay client
                            $client = new AsiaPayIntegration($domain, $appKey, $appSecret, $privateKey);

                            // 5. Create a payment order
                            $response = $client->createOrder(
                                $appid,
                                $businessType,
                                $merchCode,
                                $merchOrderId,
                                $redirectUrl,
                                $notifyUrl,
                                $timeoutExpress,
                                $title,
                                $totalAmount,
                                $tradeType
                            );

                            // 6. Handle the response
                            if (isset($response['biz_content']['redirect_url'])) {
                                // For web applications:
                                header("Location: " . $response['biz_content']['redirect_url']);
                                exit;

                                // For mobile applications, return the URL to the app
                                // echo json_encode(['payment_url' => $response['biz_content']['redirect_url']]);
                            } else {
                                // Handle error
                                echo "Error: " . $response['message'];
                            }

                        } catch (Exception $e) {
                            echo "Error: " . $e->getMessage();
                        }
                        ?>
Copy
Download
public static String createOrder(String appSecret, String appId, String appKey, String merchCode, String redirectUrl, String notifyUrl, String timeout, String title, String totalAmount, String privateKey) {
                            String nonceStr = UUID.randomUUID().toString().replace("-", "");
                            long timestamp = Instant.now().getEpochSecond();

                            Map<String,Object>bizContent = new HashMap<>();
                            bizContent.put("appid", appId);
                            bizContent.put("merch_code", merchCode);
                            bizContent.put("merch_order_id", "2025" + timestamp);
                            bizContent.put("redirect_url", redirectUrl);
                            bizContent.put("notify_url", notifyUrl);
                            bizContent.put("timeout_express", timeout);
                            bizContent.put("title", title);
                            bizContent.put("total_amount", totalAmount);
                            bizContent.put("trade_type", "Checkout");
                            bizContent.put("trans_currency", "IQD");

                            Map<String, Object> data = new HashMap<>();
                            data.put("biz_content", bizContent);
                            data.put("method", "payment.preorder");
                            data.put("nonce_str", nonceStr);
                            data.put("sign_type", "JWTSecret");
                            data.put("timestamp", String.valueOf(timestamp));
                            data.put("version", "1.0");

                            String jwt = AsiapayIntegration.createJwt(data, privateKey);
                            data.put("sign", jwt);

                            HttpEntity<Map<String, Object>> request = new HttpEntity<>(data, AsiapayIntegration.getHttpHeaders(appKey, appSecret, TOKEN_URL));
                            ResponseEntity<JsonNode> response = restTemplate.exchange(PRE_ORDER_URL, HttpMethod.POST, request, JsonNode.class);
                            return String.valueOf(response.getBody().get("biz_content").get("redirect_url").asText());
                        }
Copy
Download
// 1. Import the AsiaPay Integration Module
                        const AsiaPayClient = require('asiapay-sdk');

                        // 2. Configure your API credentials
                        const domain = 'https://apitest.asiapay.iq:5443/apiaccess';
                        const appKey = 'your-app-key';
                        const appSecret = 'your-app-secret';
                        const privateKey = 'your-private-key';

                        // 3. Set up order parameters
                        const orderParams = {
                          appid: 'your-app-id',
                          businessType: 'BuyGoods',
                          merchCode: 'your-merchant-code',
                          merchOrderId: `ORDER${Date.now()}`, // Generate unique order ID
                          redirectUrl: 'callbackUrl=your.app.scheme',
                          notifyUrl: 'https://your-server.com/webhook',
                          timeoutExpress: '30m',
                          title: 'Product Purchase',
                          totalAmount: '50.00',
                          tradeType: 'Checkout'
                        };

                        async function createPaymentOrder() {
                          try {
                            // 4. Initialize the AsiaPay client
                            const client = new AsiaPayClient({
                              domain,
                              appKey,
                              appSecret,
                              privateKey
                            });

                            // 5. Create a payment order
                            const response = await client.createOrder(orderParams);

                            // 6. Handle the response
                            if (response.biz_content && response.biz_content.redirect_url) {
                              // For web applications:
                              console.log(`Payment URL: ${response.biz_content.redirect_url}`);

                              // For Express.js web applications:
                              // res.redirect(response.biz_content.redirect_url);

                              // For mobile/React Native applications, return the URL:
                              // res.json({ payment_url: response.biz_content.redirect_url });
                            } else {
                              console.error('Error:', response.message);
                            }

                          } catch (error) {
                            console.error('Error:', error.message);
                          }
                        }

                        // Execute the payment order creation
                        createPaymentOrder();
Copy
Download
import time
                        import requests
                        from asiapay_sdk import AsiaPayClient, OrderRequest

                        # 1. Configure your API credentials
                        domain = "https://apitest.asiapay.iq:5443/apiaccess"
                        app_key = "your-app-key"
                        app_secret = "your-app-secret"
                        private_key = "your-private-key"

                        # 2. Set up order parameters
                        appid = "your-app-id"
                        business_type = "BuyGoods"
                        merch_code = "your-merchant-code"
                        merch_order_id = f"ORDER{int(time.time())}"  # Generate unique order ID
                        redirect_url = "callbackUrl=your.app.scheme"
                        notify_url = "https://your-server.com/webhook"
                        timeout_express = "30m"
                        title = "Product Purchase"
                        total_amount = "50.00"
                        trade_type = "Checkout"

                        def create_payment_order():
                            try:
                                # 3. Initialize the AsiaPay client
                                client = AsiaPayClient(
                                    domain=domain,
                                    app_key=app_key,
                                    app_secret=app_secret,
                                    private_key=private_key
                                )

                                # 4. Create order request object
                                order = OrderRequest(
                                    appid=appid,
                                    business_type=business_type,
                                    merch_code=merch_code,
                                    merch_order_id=merch_order_id,
                                    redirect_url=redirect_url,
                                    notify_url=notify_url,
                                    timeout_express=timeout_express,
                                    title=title,
                                    total_amount=total_amount,
                                    trade_type=trade_type
                                )

                                # 5. Create a payment order
                                response = client.create_order(order)

                                # 6. Handle the response
                                if 'biz_content' in response and 'redirect_url' in response['biz_content']:
                                    payment_url = response['biz_content']['redirect_url']
                                    print(f"Payment URL: {payment_url}")

                                    # For Flask applications:
                                    # return redirect(payment_url)

                                    # For API endpoints:
                                    # return jsonify({"payment_url": payment_url})
                                else:
                                    print(f"Error: {response.get('message', 'Unknown error')}")

                            except Exception as e:
                                print(f"Error: {str(e)}")

                        # Execute the payment order creation
                        if __name__ == "__main__":
                            create_payment_order()

Support & FAQ

How do I get credentials?

You can contact the B2B team for registering your wallet: b2bchannel@asiapay.iq

Who do I contact for help?

Email our technical support team at devops@asiapay.iq.