OnlinePay API
V2
V1
V2
V1
  1. Notify
  • 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
    • V2 Signature Specification
  • Payin
    • Credit Card API
      POST
    • Alipay API
      POST
    • GCash API
      POST
    • WeChat API
      POST
    • PIX API
      POST
    • Crypto API
      POST
    • Union Pay API
      POST
    • SPEI API
      POST
    • SEPA API
      POST
    • Per Transfer API
      POST
    • Cash App API
      POST
    • Google Pay API
      POST
    • Apple Pay API
      POST
    • MONO API
      POST
    • Vietnam Bank API
      POST
    • CheckOut API
      POST
    • CheckOut Payment API
      POST
    • OnRamps API
      GET
  • Payout
    • PER Transfer Payout API
    • Checkout Payout API
    • Card Payout API
    • Bank Account Payout API
    • PIX Payout API
    • PER Transfer Payout API
    • SPEI Payout API
    • CashApp Payout API
    • Checkout Payout API
    • Query Payout Order API
    • Upload SEPA File API
  • Refund
    • Refund API
  • Card
    • Create Cardholder API
    • Create Card API
    • Active Card API
    • Freeze Card API
    • UnFreeze Card API
    • Cancel Card API
    • TopUp Card API
    • Card Withdraw API
    • Query Card Balance API
    • Query Card Info API
    • Query Card Transaction API
    • Add VPA Scene API
    • UploadFile API
  • Query
    • Query Payout Order API
    • Query Order API
    • QueryOrderList API
    • QueryBalance API
    • QueryOrderAmount API
  • Notify
    • Pay Notify WebHook API
      POST
    • Card Notify WebHook API
      POST
    • Refund Notify WebHook API
      POST
    • Chargeback Notify WebHook API
      POST
  • Schemas
    • UserArray
    • CheckStandV2Request
    • ApiResponse
    • PayoutCheckStandV2Request
    • QueryPayOutV2Request
    • V2EncryptedEnvelope
    • V2EncryptedNotification
    • PaymentNotificationPayload
    • ProductParams
    • Category
    • PayoutCheckStandV2Response
    • PaymentNotification
    • QueryPayOutV2Response
    • PayoutQueryResult
    • Pet
    • OrderQueryV2Data
    • PayoutCheckStandV2Data
    • CheckStandV2Response
    • RefundNotificationPayload
    • CheckStandV2Data
    • ChargebackNotificationPayload
    • Tag
    • OrderQueryV2Request
    • OrderQueryV2Response
    • Order
    • User
  1. Notify

Card Notify WebHook API

Testing Env
https://testpay.onlinepay.ai
Testing Env
https://testpay.onlinepay.ai
POST
/notify/v2/card
NOTE
If the notifyUrl parameter is provided during card application, the system will send asynchronous notifications to that address when card status changes occur. V2 notification body is RSA+AES encrypted.

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

What You Receive#

POST your notifyUrl
Content-Type: application/json

{
  "encryptedData": "SFOs0qSAGLs6kHLf...",
  "encryptedKey": "Vfn2M+u4uG7nWklk...",
  "signType": "RSA256"
}

Step 1: Decrypt#

// 1. RSA decrypt encryptedKey with OnlinePay Public Key → get AES key
// 2. AES decrypt encryptedData with AES key → get plaintext JSON below

Step 2: Decrypted Fields#

Common Parameters#

All notifications include the following common parameters:
ParameterTypeRequiredDescription
notifyIdstringYesNotification unique ID
merApplyNostringYesMerchant application flow number
applyOrderNostringYesApplication order flow number
cardNostringYesCard number (masked)
notifyTypestringYesNotification type: card_apply, card_status_change, card_transaction
timestampstringYesNotification timestamp (milliseconds)
signTypestringYesMD5 or RSA256
signstringYesSignature value

1. Card Application Notification#

When the card application status changes, the system sends a card application notification.
ParameterTypeRequiredDescription
statusstringYesApplication status code
statusDescstringYesStatus description

Application Status Codes#

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

Example#

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

2. Card Status Change Notification#

When the card status changes, the system sends a card status change notification.
ParameterTypeRequiredDescription
oldStatusstringYesPrevious status code
newStatusstringYesNew status code
statusDescstringYesNew status description

Card Status Codes#

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

Example#

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

3. Card Transaction Notification#

When a card transaction is completed, the system sends a card transaction notification.
ParameterTypeRequiredDescription
merOrderNostringYesMerchant order number
tradeNostringYesOnlinePay trade number
trxTypestringYesTransaction type
settleAmountstringYesSettlement amount
settleCurrencystringYesSettlement currency
amountstringYesTransfer amount
currencystringYesTransfer currency
statusstringYesTransfer status: 0=Success, 1=Failed, 2=Pending
transactionDirectionstringYesTransfer direction: 0=IN, 1=OUT

Transaction Types#

TypeDescription
0Deposit
1Payment
2Withdrawal
3Refund
4Payment Cancel
5Pre-Authorization

Example#

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

Step 3: Verify Signature#

1.
Sort all fields by key (exclude sign, signType, skip null/empty)
2.
Join as key1=value1&key2=value2
3.
Verify by signType:
MD5: MD5(signString + md5Key).toUpperCase() == sign
RSA256: RSA-SHA256-Verify(signString, sign, OnlinePay_PublicKey)

Step 4: Respond#

The merchant should return SUCCESS or 200 to acknowledge receipt of the notification.
HTTP/1.1 200 OK
Content-Type: text/plain

success

Retry Mechanism#

Maximum retries: 5 times
Retry intervals: 0, 1, 5, 15, 30 minutes
Retry conditions: Network errors, timeout, or non-success responses

Request

Body Params application/jsonRequired

Example
{
    "encryptedData": "SFOs0qSAGLs6kHLf...",
    "encryptedKey": "Vfn2M+u4uG7nWklk...",
    "signType": "RSA256"
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://testpay.onlinepay.ai/notify/v2/card' \
--header 'Content-Type: application/json' \
--data '{
    "encryptedData": "SFOs0qSAGLs6kHLf...",
    "encryptedKey": "Vfn2M+u4uG7nWklk...",
    "signType": "RSA256"
}'

Responses

🟢200
Return HTTP 200 to acknowledge receipt
This response does not have a body.
Modified at 2026-05-20 02:30:05
Previous
Pay Notify WebHook API
Next
Refund Notify WebHook API
Built with