OnlinePay API
  1. Notify
OnlinePay API
  • Introduction
    • Introduction
    • How to Start
    • Country Code
    • Country Info
    • Currency Code
    • Error Code
    • Transfer Order Info Type
    • Transfer Order File Type
    • Per Bank
    • Spei Bank
    • Vietnam Bank
  • Payin
    • OnRamps API
      GET
    • Alipay API
      POST
    • Apple Pay API
      POST
    • Cash App API
      POST
    • Credit Card API
      POST
    • Crypto Pay API
      POST
    • GCash API
      POST
    • Google Pay API
      POST
    • PerTransfer API
      POST
    • PIX API
      POST
    • SEPA API
      POST
    • SPEI API
      POST
    • Union Pay API
      POST
    • WeChat API
      POST
    • CheckOut
      POST
    • CheckOut Payment
      POST
    • Momo API
      POST
    • Vietnam Bank API
      POST
  • Payout
    • Bank Account
    • Card
    • Per Transfer
    • Pix
    • CheckOut
    • Spei Payout
  • Notify
    • Pay Notify WebHook API
    • Refund Notify WebHook API
    • Chargeback Notify WebHook API
    • Card Notify WebHook API
  • Refund
    • Refund API
  • Review
    • Upload SEPA File API
  • Query
    • Query API
    • QueryBalance API
    • QueryOrderList API
    • QueryOrderAmount API
  • Card
    • CreateCardholder API
    • CreateCard API
    • QueryCardInfo API
    • ActiveCard API
    • TopUpCard API
    • CardWithdraw API
    • QueryCardTransaction API
    • QueryCardBalance API
    • FreezeCard API
    • UnFreezeCard API
    • CancelCard API
    • AddVpaScene API
    • UploadFile API
  1. Notify

Card Notify WebHook API

NOTE
If the notifyUrl parameter is provided during card application, the system will send asynchronous notifications to that address when card status changes occur.

Notification Types#

The system supports the following three types of card notifications:
1.
Card Application Notification - Card application status change notification
2.
Card Status Change Notification - Card status change notification
3.
Card Transaction Notification - Card transaction result notification

Common Parameters#

All notifications include the following common parameters:
ParameterTypeRequiredDescription
notifyIdStringYesNotification Unique ID
merApplyNostringYesMerchant application flow number
applyOrderNostringYesApplication order flow number
cardNostringYesCard number
notifyTypestringYesNotification type: card_apply, card_status_change, card_transaction
timestampstringYesNotification timestamp (milliseconds)
signstringYesSignature, MD5(parameters sorted alphabetically&key=merchant secret key)

1. Card Application Notification#

When the card application status changes, the system sends a card application notification.

Request Parameters#

ParameterTypeRequiredDescription
notifyIdStringYesNotification Unique ID
merApplyNostringYesMerchant application flow number
applyOrderNostringYesApplication order flow number
cardNostringNoCard number (returned when card opening is successful)
statusstringYesApplication status code
statusDescstringYesStatus description
notifyTypestringYesNotification type: card_apply
timestampstringYesNotification timestamp (milliseconds)
signstringYesSignature

Status Codes#

Status CodeDescription
0Under Review
1Review Failed
2Processing
3Processing Failed
4Processing Successful
5Closed

Example Request#

{
  "notifyId": "NF123456",
  "merApplyNo": "MER202312010001",
  "applyOrderNo": "APP202312010001",
  "cardNo": "411111****1111",
  "status": "4",
  "statusDesc": "Processing Successful",
  "notifyType": "card_apply",
  "timestamp": "1701234567890",
  "sign": "A1B2C3D4E5F6G7H8I9J0"
}

2. Card Status Change Notification#

When the card status changes, the system sends a card status change notification.

Request Parameters#

ParameterTypeRequiredDescription
notifyIdStringYesNotification Unique ID
merApplyNostringYesMerchant application flow number
applyOrderNostringYesApplication order flow number
cardNostringYesCard number
oldStatusstringYesPrevious status code
newStatusstringYesNew status code
statusDescstringYesNew status description
notifyTypestringYesNotification type: card_status_change
timestampstringYesNotification timestamp (milliseconds)
signstringYesSignature

Card Status Codes#

Status CodeDescription
0Pending Activation
1Activated
2Frozen
3Freezing in Progress
4Cancelling in Progress
5Cancelled
6Unfreezing in Progress
7Uncancelling in Progress

Example Request#

{
  "notifyId": "NF123456",
  "merApplyNo": "MER202312010001",
  "applyOrderNo": "APP202312010001",
  "cardNo": "411111****1111",
  "oldStatus": "1",
  "newStatus": "2",
  "statusDesc": "Frozen",
  "notifyType": "card_status_change",
  "timestamp": "1701234567890",
  "sign": "A1B2C3D4E5F6G7H8I9J0"
}

3. Card Transaction Notification#

When a card transaction is completed, the system sends a card transaction notification.

Request Parameters#

ParameterTypeRequiredDescription
notifyIdStringYesNotification Unique ID
merOrderNostringYesMerchant application order number
tradeNostringYesApplication order number
cardNostringYesCard number
trxTypestringYesTransaction type
settleAmountstringYesSettlement amount
settleCurrencystringYesSettlement currency
amountstringYestransfer amount
currencystringYestransfer currency
notifyTypestringYesNotification type: card_transaction
statusstringyestransfer status 0:Success 1:Failed 2:Preprocessing
transactionDirectionstringyestransfer direction 0:IN 1:OUT
timestampstringYesNotification timestamp (milliseconds)
signstringYesSignature

Transaction Types#

Transaction TypeDescription
0Deposit
1Payment
2Withdrawal
3Refund
4PaymentCancel
5PerAuth

Example Request#

{
  "notifyId": "NF123456",
  "merOrderNo": "MER123456789",
  "tradeNo": "TRADE987654321",
  "cardNo": "411111******1111",
  "trxType": "1",
  "settleAmount": "100.00",
  "settleCurrency": "USD",
  "amount": "100.00",
  "currency": "USD",
  "notifyType": "card_transaction",
  "status": "0",
  "transactionDirection": "0",
  "timestamp": "1625097600000",
  "sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Signature Generation#

Signature Algorithm#

The signature is generated using MD5 algorithm with the following steps:
1.
Sort all parameters alphabetically (excluding the sign parameter)
2.
Concatenate parameters in the format: key1=value1&key2=value2&...
3.
Append the merchant secret key: &key=merchant_secret_key
4.
Calculate MD5 hash of the concatenated string
5.
Convert to uppercase

Signature Example#

Response Requirements#

Success Response#

The merchant should return SUCCESS or 200 to acknowledge receipt of the notification.

Failure Response#

If the merchant returns any other response, the system will retry the notification.

Retry Mechanism#

Retry Policy#

The system implements an automatic retry mechanism for failed notifications:
Maximum retries: 5 times
Retry intervals: 0 minutes, 1 minute, 5 minutes, 15 minutes, 30 minutes
Retry conditions: Network errors, timeout, or non-success responses

Retry Log#

Failed notifications are logged for monitoring and manual intervention if needed.

Security Considerations#

HTTPS Requirement#

All notifications are sent via HTTPS to ensure data security.

Signature Verification#

Merchants should verify the signature of each notification to ensure authenticity:
1.
Extract all parameters except sign
2.
Generate signature using the same algorithm
3.
Compare with the received signature
4.
Reject notifications with invalid signatures
Modified at 2025-08-04 03:08:39
Previous
Chargeback Notify WebHook API
Next
Refund API
Built with