Card

1.Push events

Event	Repeat	Describe
CC_CONSUME	yes	card consume
CC_REFUND	yes	card refund
CC_WITHDRAW_CASH	yes	Card withdrawal
CC_REDEEM	yes	Card redemption
CC_RECHARGE	yes	Card recharge/collateral(Notification after successful recharge/collateral using API recharge card)
3DS_OTP	yes	3D Secure Verification Code
3DS_CONFIRM	yes	3DS Confirmation Code
CR_RECHARGE	yes	Notification of successful submission of card recharge application(Used only in IFrame scenarios)
CA_APPLY	yes	Card application submission successful notification
NE_VERIFY	yes	Verification notification
KS_KYC	yes	KYC Verification(Notification of approval or rejection after submitting KYC certification)
CSC_STATUS_CHANGE	yes	Card status change(Notifications when card status changes, such as notifications when activating, locking, or unlocking a card using the API)
MF_MATERIAL_FLOW	yes	Card delivery logistics notice(Notification after successful card delivery)
CS_APPROVED	yes	Card Issuance Success Notification (each card will trigger the notification only once) Physical Card: The notification is triggered when the card status changes to “Pending Activation.” Virtual Card: The notification is triggered when the card status becomes “Normal.”
CE_EVENT		Card event notification (triggered when card is frozen or unfrozen)
CC_AUTHORIZATION	Yes	Card transaction authorization notice(Applicable only to specific shared-mode card ranges)

2.Global push format

Parameter	Type	Required	Describe
event	String	true	Event name
trace	String	true	Link ID, the same link ID for the same transaction
orderNo	String	true	Order number, globally unique
timestamp	Long	true	Push timestamp (milliseconds)
detail	Object		The format of push content varies depending on the event

2.1.Card transaction push format

Including card consumption, card refund, card withdrawal, card redemption, card recharge/mortgage

Parameter	Type	Required	Describe
cardId	String	true	Card unique ID
cardNumber	String	true	Card number
orderNo	String	true	Order Number
customerNo	String	true	Customer number
type	int	true	Transaction type (1=Recharge/Collateral, 2=consumption, 3=refund, 4=Cash Withdrawal, 5=redemption, 6=management fee)
status	int	true	Transaction status (1=Success, 2=Failed, 3=Processing, 4=Posted, 5=Unposted, 7=Canceled)
amount	BigDecimal	true	Transaction amount
direction	int	true	Income and expenditure direction(1=Income, 2=Expenditure)
merchantName	String	false	Merchant name
currency	String	true	Transaction currency
transactionAt	Long	true	Transaction time
transactionId	String	true	Transaction ID,The TransactionID of the same transaction is consistent
originalAmount	BigDecimal	false	Original transaction amount
originalCurrency	String	false	Original transaction currency
reason	String	false	Cause of failure
fee	BigDecimal	false	Transaction fees
thirdOrderNo	String	false	Third party order number (valid for card recharge/mortgage)
merchantMcc	String	false	MCC
merchantCategory	String	false	Merchant category
merchantCountry	String	false	Merchant country

2.2. 3DS OTP Data Webhook Format

Parameter	Type	Required	Describe
cardId	String	true	Card unique ID
cardNumber	String	true	Card number
customerNo	String	true	Customer number
3dsCode	String	true	3DS Code
orderNo	String	true	Order Number
merchants	String	true	Merchant Name
amount	BigDecimal	true	Transaction amount
transactionCurrency	String	true	Trading currency
transactionTime	Long	true	Trading hours

2.3. 3DS Confirm Data Webhook Format

Parameter	Type	Required	Describe
cardId	String	true	Card unique ID
cardNumber	String	true	Card number
customerNo	String	true	Customer number
type	String	true	3DS confirmation type (code / link)
validateCode	String	false	3DS verification code, valid when type=code
url	String	false	3DS confirms link, valid when type=link
merchants	String	true	Merchant Name
transactionTime	Long	true	Trading hours
amount	BigDecimal	true	Transaction amount
transactionCurrency	String	true	Trading currency

2.4. Card application submission successful notification push format

Parameter	Type	Required	Describe
cardId	String	true	Card ID
orderNo	String	true	Order Number
customerNo	String	true	Customer number
amount	BigDecimal	true	Actual payment amount
status	Integer	true	Payment Status (1: Paid 2: Pending Payment)
subscribeAt	Long	true	Subscribe time

2.5. Push notification format for successful recharge application submission(Used only in IFrame scenarios)

Parameter	Type	Required	Describe
cardId	String	true	Card unique ID
orderNo	String	true	Order Number
customerNo	String	true	Customer number
cardNumber	String	true	Card Number
amount	BigDecimal	true	Actual payment amount
status	Integer	true	Payment Status (8: Pending Payment)
subscribeAt	Long	true	Subscribe time

2.6. Verification notification push format

Parameter	Type	Required	Describe
cardId	String	true	Card unique ID
orderNo	String	true	Order Number
code	String	true	Verification Code
cardNumber	String	true	Card Number
type	String	true	Type (see 2.7 Verification Notification Type)
customerNo	String	true	Customer Number

2.7. Verification notification type

Parameter	Describe
CARD_ACTIVATION	Card Activation
LOCK_UNLOCK_CARD	Card lock/unlock
TX_WDR_PWD_MODIFY	Modify transaction (cash withdrawal) password
TX_WDR_PWD_SET	Set transaction (cash withdrawal) password
CAT_CARD	View Card

2.8. Kyc notification push format

Parameter	Type	Required	Describe
customerNo	String	yes	Customer
documentType	String	yes	numberDocument type (1:Id Card 2.Passport 3.Selfie,4=Driver's license, 5=Residence permit)
status	String	yes	Status(1=Approved,2=Rejected,3=Pending,4=Unverified) Only push 1, 2 final status
reason	String	no	Reason for verification rejection (only valid when status is Rejected)

2.9. Card status change notification push format

Parameter	Type	Required	Describe
cardId	String	yes	Card unique ID
cardNumber	String	yes	Card number
status	String	yes	Status (1=Normal, 2=Pending Activation, 3=Frozen, 4=Locked, 5=Deactivated, 6=Applying, 7=Activating, 8=Locking, 9=Unlocking, 10=Deactivating,13=Rejected,14=Cancelled,15=Replacing,16=Replaced).Only push change data with statuses 1, 2, 3, 4, 5, 13
orderNo	String	yes	Order no
customerNo	String	yes	Customer no
reason	String		Reason

2.10. Card delivery logistics notification push format

Parameter	Type	Required	Describe
dispatchTime	String	yes	Delivery time
logisticsOrderNo	String	yes	Logistics tracking number
logisticsCompanyName	String	yes	Logistics Company Name
recipientAddress	String	yes	Shipping address
logisticsImage	String	yes	Logistics photos
cardId	String	yes	Card unique ID

2.11. Format of push notification for successful card activation

Parameter	Type	Required	Describe
orderNo	String	yes	Order number
cardId	String	yes	Card unique ID
cardNumber	String	yes	Card number
customerNo	String	yes	Customer number
cardStatus	Integer	yes	Card Status: （1=Normal, 2=Pending Activation) Virtual Card: Status = 1 (Normal) Physical Card: Status = 2 (Pending Activation)

2.12. Card event notification push format

Parameter	Type	Required	Describe
cardId	String	yes	Card unique ID
event	String	yes	Event type (Frozen/Unfrozen)
reason	String	no	Reason

2.13. Card transaction authorization notice(Applicable only to specific shared-mode card ranges)

Parameter	Type	Required	Describe
cardId	String	yes	Card unique ID
cardNumber	String	yes	Card number
amount	String	yes	Transaction amount
currency	String	yes	Transaction currency
merchantMcc	String	no	MCC
transactionId	String	yes	Transaction ID
authorizationId	String	yes	Transaction authorization ID
transactionChannel	String	no	Transaction channel

Note: When a card transaction occurs, UPay will send an authorization request to the merchant system via Webhook after completing preliminary risk control and limit checks. The merchant must return either approve or decline. If no response is received within 2.5 seconds, the transaction will be declined due to timeout.

For authorization, the HTTP response status code should be 200, and the returned value should be a string type: approve / decline

Code Example

Java

public ResponseEntity<String> simulation(@RequestBody String body) {
	//return ResponseEntity.status(status).body("decline");
   return ResponseEntity.status(status).body("approve");
}

Go

package main

import (
    "net/http"
    "github.com/gin-gonic/gin"
)

func simulation(c *gin.Context) {
    
    body, err := c.GetRawData()
    if err != nil {
        c.String(http.StatusBadRequest, "failed to read body")
        return
    }
    _ = string(body) 
    c.String(http.StatusOK, "approve")
}

Python

from flask import Flask, request, make_response

app = Flask(__name__)

@app.route('/simulation', methods=['POST'])
def simulation():
    
    body = request.get_data(as_text=True)
   
    return make_response("approve", 200)