Skip to content

[New Connector] asiapay — Authorize, PSync, Capture, Void, Refund, IncomingWebhook #175

Open
Open
[New Connector] asiapay — Authorize, PSync, Capture, Void, Refund, IncomingWebhook#175
Labels
connector-integration

Description

@shuklatushar226
shuklatushar226
opened on May 27, 2026

asiapay — New Connector Integration

Workflow: new-connector
Flows: Authorize, PSync, Capture, Void, Refund, IncomingWebhook
Auth scheme: Signature
Currency unit: StringMajor
Base URL: https://www.paydollar.com/b2c2/eng
Sandbox URL: https://test.paydollar.com/b2cDemo/eng
Generated by: Grace pipeline run run-2026-05-27T08-12-02-861Z-3c225d

Discovered Docs

Acceptance Criteria

  • Authorize flow compiles and runs
  • gRPC Authorize call succeeds against sandbox

Tech Spec

AsiaPay UCS Connector Integration Technical Specification

Connector Profile

Field Value
Connector Name AsiaPay (PayDollar)
Owning Company AsiaPay Limited (Hong Kong)
Primary Brand PayDollar
Regional Brands PesoPay (Philippines), SiamPay (Thailand), BimoPay (Indonesia)
Production Base URL https://www.paydollar.com/b2c2/eng
Sandbox Base URL https://test.paydollar.com/b2cDemo/eng
Developer Portal https://developer.asiapay.com/ (requires merchant login)
Admin Portal https://admin.paydollar.com/b2c2/eng/merchant/index.jsp

Supported Countries: Hong Kong, China, Macau, Taiwan, Singapore, Malaysia, India, Vietnam, Australia, New Zealand, Philippines, Thailand, Indonesia

Supported Currencies (ISO 4217 numeric codes used in API):

Currency ISO Alpha ISO Numeric (currCode) Brand
Hong Kong Dollar HKD 344 PayDollar
US Dollar USD 840 PayDollar
Singapore Dollar SGD 702 PayDollar
Chinese Yuan CNY 156 PayDollar
Japanese Yen JPY 392 PayDollar
Taiwan Dollar TWD 901 PayDollar
Australian Dollar AUD 036 PayDollar
Euro EUR 978 PayDollar
British Pound GBP 826 PayDollar
Canadian Dollar CAD 124 PayDollar
Thai Baht THB 764 SiamPay
Philippine Peso PHP 608 PesoPay

Note on regional brands: PesoPay, SiamPay, and BimoPay share the same API structure as PayDollar but use different base URLs (e.g., https://www.pesopay.com/b2c2/eng, https://www.siampay.com/b2c2/eng, https://www.bimopay.com/b2c2/eng).

Authentication

AsiaPay uses a Secure Hash (SHA1 or SHA256 signature) scheme. The hash is computed by the merchant server, covering key transaction fields, and included as a form POST body parameter named secureHash. No HTTP Authorization header is used.

Scheme

  • Primary auth (payment requests): Signature — SHA1 (default) or SHA256 (request from AsiaPay)
  • Merchant API auth (capture/void/refund/query): Form body credentials — loginId + password
  • Auth Location: Body (form-encoded POST parameter)

Credential Fields

Field Type Purpose
merchantId Number Unique merchant identifier assigned by AsiaPay
secureHashSecret String Secret key for hash computation; must be enabled by contacting AsiaPay
loginId String (max 30 chars) Separate API login ID for Merchant API operations
password String (max 15 chars) API password for Merchant API operations

Secure Hash Calculation (Request)

Concatenate the following fields with | as delimiter, then apply SHA1 (or SHA256 if configured):

secureHash = SHA1(merchantId + "|" + orderRef + "|" + currCode + "|" + amount + "|" + payType + "|" + secureHashSecret)

Example:

SHA1("88888|ORDER-001|344|100.00|H|MY_SECRET") => "a1b2c3d4e5f6..."

Secure Hash Verification (Datafeed Response)

The datafeed POST from AsiaPay includes a secureHash field. Verify it as:

expectedHash = SHA1(merchantId + "|" + Ref + "|" + PayRef + "|" + Cur + "|" + Amt + "|" + successcode + "|" + secureHashSecret)

Compare with the received secureHash. Discard the datafeed if they do not match.

Supported Flows

Flow HTTP Method Endpoint Path Idempotency Key Notes
Authorize POST /directPay/payComp.jsp orderRef Server-to-server card submission; payType=H for auth-only
Capture POST /merchant/api/orderApi.jsp payRef actionType=Capture; uses separate Merchant API credentials
Void POST /merchant/api/orderApi.jsp payRef actionType=Void; cancels authorized or accepted payment
Refund POST /merchant/api/orderApi.jsp payRef actionType=Refund; must be within 14 days of original transaction
PSync POST /merchant/api/orderApi.jsp payRef actionType=Query; returns current orderStatus
IncomingWebhook POST {merchantConfiguredUrl} PayRef Datafeed POSTed asynchronously to merchant Return Value Link

Normal Sale vs. Authorize-only: Set payType=N for an immediate auth+capture (no separate Capture call needed). Set payType=H (Hold) for authorize-only; then call Capture via Merchant API.

Request Schema

Authorize Request

Endpoint: POST https://www.paydollar.com/b2c2/eng/directPay/payComp.jsp

Content-Type: application/x-www-form-urlencoded

{
  "merchantId": "88888",
  "orderRef": "ORDER-2024-001",
  "amount": "100.00",
  "currCode": "344",
  "payType": "H",
  "payMethod": "CC",
  "cardNo": "4111111111111111",
  "cardHolder": "Test User",
  "epMonth": "12",
  "epYear": "2026",
  "securityCode": "123",
  "lang": "E",
  "successUrl": "https://merchant.example.com/success",
  "failUrl": "https://merchant.example.com/fail",
  "cancelUrl": "https://merchant.example.com/cancel",
  "secureHash": "a1b2c3d4e5f6789abc"
}
Field Type Required Description
merchantId Number Yes Merchant identifier assigned by AsiaPay
orderRef String (max 35) Yes Merchant's unique order reference
amount Decimal String Yes Amount in major units (e.g., "100.00" for 100 HKD)
currCode String (3 digits) Yes ISO 4217 numeric currency code (e.g., "344" = HKD, "840" = USD)
payType String Yes "N" = Normal/Sale (auth+capture); "H" = Hold (authorize only)
payMethod String No "ALL", "CC", "ALIPAY", "WECHATPAY", "UNIONPAY", "PAYPAL", "CHINAPAY", "TENPAY", "99BILL", "PPS"
cardNo String (16) Cond Card PAN (required for server-side direct payment)
cardHolder String (max 20) Cond Cardholder name
epMonth String (MM) Cond Card expiry month
epYear String (YYYY) Cond Card expiry year
securityCode String (3–4) No CVV2/CVC2
lang String No E=English, C=Traditional Chinese, X=Simplified Chinese, K=Korean, J=Japanese, T=Thai, F=French, G=German, R=Russian, S=Spanish
successUrl String No Redirect URL on payment success
failUrl String No Redirect URL on payment failure
cancelUrl String No Redirect URL on cancellation
secureHash String Yes SHA1 or SHA256 signature
redirect Number No Auto-redirect delay (seconds)
mpsMode String No Multi-currency mode: "NIL", "SCP", "DCC", "MCP"
remark String No Merchant remark (passed through to datafeed)

Capture Request

Endpoint: POST https://www.paydollar.com/b2c2/eng/merchant/api/orderApi.jsp

Content-Type: application/x-www-form-urlencoded

{
  "merchantId": "88888",
  "loginId": "api_login",
  "password": "api_pass",
  "actionType": "Capture",
  "payRef": "4780",
  "amount": "100.00"
}
Field Type Required Description
merchantId Number Yes Merchant identifier
loginId String (max 30) Yes Merchant API login ID
password String (max 15) Yes Merchant API password
actionType String Yes Must be "Capture"
payRef String (max 35) Yes PayDollar payment reference from original authorization
amount Decimal String Yes Capture amount; must be ≤ original authorized amount

Void Request

Endpoint: POST https://www.paydollar.com/b2c2/eng/merchant/api/orderApi.jsp

Content-Type: application/x-www-form-urlencoded

{
  "merchantId": "88888",
  "loginId": "api_login",
  "password": "api_pass",
  "actionType": "Void",
  "payRef": "4780"
}
Field Type Required Description
merchantId Number Yes Merchant identifier
loginId String (max 30) Yes Merchant API login ID
password String (max 15) Yes Merchant API password
actionType String Yes Must be "Void"
payRef String (max 35) Yes PayDollar payment reference to void

Refund Request

Endpoint: POST https://www.paydollar.com/b2c2/eng/merchant/api/orderApi.jsp

Content-Type: application/x-www-form-urlencoded

{
  "merchantId": "88888",
  "loginId": "api_login",
  "password": "api_pass",
  "actionType": "Refund",
  "payRef": "4780",
  "amount": "50.00"
}
Field Type Required Description
merchantId Number Yes Merchant identifier
loginId String (max 30) Yes Merchant API login ID
password String (max 15) Yes Merchant API password
actionType String Yes Must be "Refund"
payRef String (max 35) Yes PayDollar payment reference
amount Decimal String No Refund amount; omit for full refund; provide for partial refund (must be ≤ original)

PSync Request

Endpoint: POST https://www.paydollar.com/b2c2/eng/merchant/api/orderApi.jsp

Content-Type: application/x-www-form-urlencoded

{
  "merchantId": "88888",
  "loginId": "api_login",
  "password": "api_pass",
  "actionType": "Query",
  "payRef": "4780"
}
Field Type Required Description
merchantId Number Yes Merchant identifier
loginId String (max 30) Yes Merchant API login ID
password String (max 15) Yes Merchant API password
actionType String Yes Must be "Query"
payRef String (max 35) Yes PayDollar payment reference to query

IncomingWebhook

AsiaPay POSTs the datafeed as application/x-www-form-urlencoded to the merchant-configured URL.

Field Type Description
successcode String "0" = success, "1" = failure, "-1" = system error
Ref String Merchant's original order reference
PayRef String AsiaPay internal payment reference
Amt Decimal String Transaction amount in major units
Cur String ISO numeric currency code
prc String Primary response code (bank response)
src String Secondary response code
AuthId String Bank authorization code
errMsg String Human-readable result message
Holder String Cardholder name
TxTime DateTime Transaction timestamp (YYYY-MM-DD HH:mm:ss.S)
ip String Cardholder IP address
eci String ECI code (3D Secure result)
payerAuth String Payer authentication result
mpsMode String Multi-currency processing mode used
remark String Merchant remark (passed through)
secureHash String SHA1/SHA256 response signature for verification
payType String "N" or "H"
Ord String Order ID

Response Schema

Authorize Response

For server-to-server direct post (/directPay/payComp.jsp), the result is returned synchronously in the HTTP response body as URL-encoded parameters.

Success Response:

{
  "successcode": "0",
  "Ref": "ORDER-2024-001",
  "PayRef": "4780",
  "Amt": "100.00",
  "Cur": "344",
  "prc": "0",
  "src": "0",
  "AuthId": "123456",
  "errMsg": "Transaction completed",
  "Holder": "Test User",
  "TxTime": "2024-01-15 10:30:00.0",
  "Ord": "6697090",
  "eci": "05",
  "secureHash": "b2c3d4e5f6..."
}

Error Response:

{
  "successcode": "1",
  "Ref": "ORDER-2024-001",
  "PayRef": "4780",
  "Amt": "100.00",
  "Cur": "344",
  "prc": "5",
  "src": "1",
  "errMsg": "Transaction declined by bank"
}
Field Type Description
successcode String "0" = success, "1" = failure, "-1" = system error
Ref String Merchant's order reference
PayRef String AsiaPay payment reference (store for subsequent Capture/Void/Refund)
Amt Decimal String Transaction amount
Cur String ISO numeric currency code
prc String Primary response code from bank
src String Secondary response code
AuthId String Bank authorization approval code
errMsg String Result message
eci String ECI code (3DS status)
secureHash String Response signature for verification

Capture / Void / Refund / PSync Response

All Merchant API operations return URL-encoded query string in the response body.

Capture Success:

resultCode=0&orderStatus=Accepted&ref=ORDER-2024-001&payRef=4780&amt=100.00&cur=344&errMsg=Capture+Successfully

Void Success:

resultCode=0&orderStatus=Voided&ref=ORDER-2024-001&payRef=4780&amt=100.00&cur=344&errMsg=Void+Successfully

Refund Success:

resultCode=0&orderStatus=Refunded&ref=ORDER-2024-001&payRef=4780&amt=100.00&cur=344&errMsg=Refund+Successfully

Failure:

resultCode=-1&orderStatus=Authorized&ref=ORDER-2024-001&payRef=4780&amt=100.00&cur=344&errMsg=Operation+failed
Field Type Description
resultCode String "0" = success, "-1" = failure
orderStatus String Current/updated order status (see Status Mapping)
ref String Merchant's order reference
payRef String PayDollar payment reference
amt Decimal String Transaction amount
cur String ISO numeric currency code
errMsg String Error or success message

Error Handling

HTTP Status Connector Field Value UCS Error Mapping Cause
200 successcode "0" + prc=0 AttemptStatus::Charged Transaction successful
200 successcode "1" + prc=5 AttemptStatus::Failure Card declined
200 successcode "1" + prc=9 AttemptStatus::Failure Transaction rejected
200 successcode "1" + any prc AttemptStatus::Failure Generic bank decline
200 successcode "-1" AttemptStatus::SystemError AsiaPay/bank system error
200 resultCode "-1" AttemptStatus::Failure Merchant API operation failed
200 orderStatus "Rejected" AttemptStatus::Failure Bank rejected transaction
200 orderStatus "Cancelled" AttemptStatus::Voided Cancelled by cardholder

PRC (Primary Response Code) meanings:

  • 0 = Approved / Success
  • 1 = Referral (contact bank)
  • 5 = Declined
  • 9 = Hold / Pickup card
  • Other values = Bank-specific decline or error codes

Retry Semantics:

  • successcode=-1 (system error): safe to retry with the same orderRef
  • successcode=1 (declined): do NOT retry without cardholder action (new card details or 3DS)
  • Merchant API resultCode=-1: investigate via Query before retrying to avoid double operations
  • Refund has a 14-day window from the original transaction; after expiry the call will fail with resultCode=-1

Status Mapping

Connector Status (verbatim) UCS AttemptStatus Notes
Pending AuthenticationPending Authorization in progress at issuing bank
Pending_3D AuthenticationPending 3D Secure verification in progress
Authorized Authorized Auth-only hold placed; awaiting merchant Capture
Capturing CaptureInitiated Capture in progress
Accepted Charged Authorized + captured / settled
Accepted_Adj Charged Accepted with partial chargeback or partial refund applied
Rejected Failure Transaction rejected by bank or AsiaPay
Cancelled Voided Cancelled by cardholder before completion
Voided Voided Voided by merchant via Merchant API
Reverse Auth Voided Authorization reversed by merchant
Reversal Void Charged Prior void was reversed; payment restored
Request Refund AutoRefunding Full refund request submitted, processing
RequestPartialRefund AutoRefunding Partial refund submitted, processing
Refunded AutoRefunded Full refund completed
Partial Refunded PartialCharged Partial refund completed
ChargeBack AutoRefunded Full chargeback from cardholder/bank
Partial ChargeBack PartialCharged Partial chargeback
Reversal-CB Charged Successful chargeback reversal by merchant

Webhooks

Subscription Mechanism

Merchants manually configure the datafeed URL in the AsiaPay Merchant Administration Portal:

  1. Log in to https://admin.paydollar.com/b2c2/eng/merchant/index.jsp
  2. Navigate to Profile → Payment Account Settings → Return Value Link (Datafeed)
  3. Enable the option by selecting the Enable radio button
  4. Enter the merchant-side webhook URL in the Return Value Link text field
  5. Click Update and confirm

Payload Structure

AsiaPay POSTs the datafeed as application/x-www-form-urlencoded:

successcode=0&Ref=ORDER-001&PayRef=4780&Amt=100.00&Cur=344&prc=0&src=0&AuthId=123456&errMsg=Transaction+completed&Holder=John+Doe&TxTime=2024-01-15+10%3A30%3A00.0&eci=05&secureHash=a1b2c3d4e5f6

Signature Verification

Header: none (signature embedded as secureHash field in POST body).

Algorithm:

expectedHash = SHA1(merchantId + "|" + Ref + "|" + PayRef + "|" + Cur + "|" + Amt + "|" + successcode + "|" + secureHashSecret)

If expectedHash != received secureHash, reject the datafeed.

Event Types

Event successcode Trigger
Payment Success "0" Transaction authorized and/or captured
Payment Failure "1" Transaction declined or failed
System Error "-1" Processing error at AsiaPay or bank

Retry / Delivery Policy

  • AsiaPay retries datafeed delivery if the merchant endpoint does not return HTTP 2xx
  • Implement idempotent webhook handling keyed on PayRef
  • If datafeed delivery fails persistently, use the PSync (Query) API to reconcile transaction status

3D Secure ECI Codes

Network ECI Meaning
Visa 05 Full 3DS authentication successful
Visa 06 3DS attempted; one party not enrolled
Visa 07 3DS not attempted or not supported
MasterCard 02 Full 3DS authentication successful
MasterCard 01 3DS attempted; one party not enrolled
MasterCard 00 3DS not attempted or not supported
JCB 05 Full 3DS authentication successful
JCB 06 3DS attempted; one party not enrolled
JCB 07 3DS not attempted or not supported

References

Official AsiaPay

Public Mirrors / Integration Guides

Reference Implementations

Third-Party Platform Docs

Metadata

Metadata

Assignees

No one assigned

    Labels

    connector-integration

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions