1. Webhook
BananaTech
  • API Security Implementation Guide
  • Guides
    • 01-README
    • 02-Getting-Started
    • 03-Virtual-Cards
    • 04-Physical-Cards
    • 05-Card-Operations
  • Webhook
    • Integration Guide
    • Event Types
  • Merchant related APIs
    • Get Account Balance
      POST
    • Get Card Templates
      POST
    • Set Webhook URL
      POST
    • Get Webhook Records
      POST
  • User related APIs
    • Register
      POST
    • Get Users
      POST
  • Card related APIs
    • Apply
      POST
    • Recharge
      POST
    • Withdraw
      POST
    • Update Status
      POST
    • Get Balance
      POST
    • Get Information
      POST
    • Get Transactions
      POST
    • Assign (for Physical cards only)
      POST
    • Set PIN (for Physical cards only)
      POST
    • 3DS Confirm
      POST
  • Schemas
    • Sample Schemas
      • Pet
      • Category
      • Tag
  1. Webhook

Event Types

Overview#

1.
USER_CREATE_RESULT
2.
CARD_APPLY_RESULT
3.
CARD_ACTIVATE_RESULT
4.
CARD_ASSIGN_RESULT
5.
CARD_STATUS_CHANGE
6.
CARD_BALANCE_CHANGE
7.
CARD_RECHARGE_RESULT
8.
CARD_WITHDRAW_RESULT
9.
CARD_CLOSE_RESULT
10.
TRANSACTION_CREATED
11.
CARD_CORRECTION
12.
CARD_3DS
13.
CARD_VERIFICATION
14.
MERCHANT_BALANCE_RECHARGED

1. USER_CREATE_RESULT#

Decrypted JSON String
Result Fields
FieldDescription
user_idUser unique ID
statusUser status
messageReason of rejection (Optional)

2. CARD_APPLY_RESULT#

Decrypted JSON String
Result Fields
FieldDescription
template_idCard template ID
user_idUser unique ID
card_idCard unique ID
statusApplication status
occur_timeTrigger time (milliseconds)

3. CARD_ACTIVATE_RESULT#

Decrypted JSON String
Result Fields
FieldDescription
card_idCard unique ID
card_numberCard number
statusActivation status
occur_timeTrigger time (milliseconds)

4. CARD_ASSIGN_RESULT#

Decrypted JSON String (Success)
Decrypted JSON String (Failed)
Result Fields
FieldDescription
card_idCard unique ID (only present for successful assigns)
user_idUser unique ID
statusAssignment status (SUCCESS/FAILED)
error_reasonError description (only present for failed assigns)
occur_timeTrigger time (milliseconds)
Purpose
This webhook is triggered after assigning a physical (plastic) card to a user. The assignment process is asynchronous - after calling the /card/assign endpoint, you must wait for this webhook to confirm whether the assignment succeeded or failed before proceeding with card activation.

5. CARD_STATUS_CHANGE#

Decrypted JSON String
Result Fields
FieldDescription
card_idCard unique ID
statusOperation status
card_statusNew card status (LOCKED/ACTIVE)
occur_timeTrigger time (milliseconds)

6. CARD_BALANCE_CHANGE#

Decrypted JSON String
Result Fields
FieldDescription
card_idCard unique ID
amountCurrent total balance amount
availableCurrent available balance
before_availableAvailable balance before the change
currencyBalance currency
occur_timeTrigger time (milliseconds)
Purpose
This webhook is triggered when a card's balance changes. This can happen due to various operations such as transactions, refunds, settlements, or other balance adjustments processed by the card network.
Notes
The available field represents the current spendable balance
The before_available field shows what the balance was before this change
The difference between before_available and available indicates the amount of change

7. CARD_RECHARGE_RESULT#

Decrypted JSON String
Result Fields
FieldDescription
template_idCard template ID
user_idUser unique ID
card_idCard unique ID
transaction_idTransaction unique ID
receive_amountRecharge amount
statusTransaction status
currencyCurrency code
descriptionTransaction description
occur_timeTrigger time (milliseconds)

8. CARD_WITHDRAW_RESULT#

Decrypted JSON String
Result Fields
FieldDescription
template_idCard template ID
user_idUser unique ID
card_idCard unique ID
transaction_idTransaction unique ID
withdraw_amountWithdraw amount
statusTransaction status
currencyCurrency code
descriptionTransaction description
occur_timeTrigger time (milliseconds)

9. CARD_CLOSE_RESULT#

Decrypted JSON String
Result Fields
FieldDescription
template_idCard template ID
user_idUser unique ID
card_idCard unique ID
transaction_idTransaction unique ID
refund_amountRefunded amount (card balance)
statusClose operation status
currencyCurrency code
descriptionTransaction description
occur_timeTrigger time (milliseconds)
Purpose
This webhook is triggered after a card close operation completes. When closing a card:
1.
The remaining card balance is withdrawn
2.
The funds are returned to the merchant balance
3.
The card status is changed to CLOSED
Notes
This webhook is only sent for HiPay cards
The refund_amount contains the balance that was on the card at the time of closing
If the card had zero balance, refund_amount will be 0 or null
The card becomes permanently unusable after this operation

10. TRANSACTION_CREATED#

Decrypted JSON String (Success)
Decrypted JSON String (Failed)
Result Fields
FieldDescription
card_idCard unique ID
transaction_idTransaction unique ID
typeTransaction type (AUTHORIZATION, PURCHASE, etc.)
statusTransaction status (SUCCESS, FAILED, etc.)
billing_currencyBilling currency
billing_amountBilling amount
billing_transaction_feeTransaction fee
transaction_currencyTransaction currency
transaction_amountTransaction amount
merchantMerchant information object
merchant.nameMerchant name
merchant.countryMerchant country code (e.g., "US", "JP", "ES") - Optional
merchant.mccMerchant Category Code (e.g., "5814", "5999") - Optional
merchant.descriptionMerchant business description - Optional
descriptionTransaction description
occur_timeTrigger time (milliseconds)
failure_reasonFailure reason (Only present for failed transactions)

11. CARD_CORRECTION#

Decrypted JSON String
Result Fields
FieldDescription
card_idCard unique ID
correction_idCorrection transaction ID
typeCorrection type
statusCorrection status
currencyCurrency code
amountCorrection amount
response_codeResponse code
response_messageResponse message
occur_timeTrigger time (milliseconds)
original_transaction_idOriginal transaction ID (optional)

12. CARD_3DS#

Decrypted JSON String
Result Fields
FieldDescription
card_idCard unique ID
securement_id3DS securement ID for confirmation
amountTransaction amount requiring 3DS authentication
currencyTransaction currency
confirm3DS confirmation status (PENDING/ACCEPTED/DECLINED)
method3DS authentication method (OTP/OOB/URL)
status3DS process status (PENDING/SUCCESS/FAILED)
merchantMerchant information object
merchant.nameMerchant name
merchant.countryMerchant country code (e.g., "US", "JP") - Optional
merchant.mccMerchant Category Code (e.g., "5411") - Optional
merchant.descriptionMerchant business description - Optional
value6-digit OTP code (present when method is "OTP")
occur_timeTrigger time (milliseconds)
Action Required
When receiving a CARD_3DS webhook, the required action depends on the authentication method:

For OTP Method#

When method is "OTP", the value field contains a 6-digit one-time code that should be displayed to the user. The user needs to enter this code on the merchant's website to complete the authentication.

For OOB Method#

When method is "OOB", clients should use the /cards/confirm_3ds endpoint to either accept or decline the 3DS authentication:

13. CARD_VERIFICATION#

Decrypted JSON String
Result Fields
FieldDescription
card_idCard unique ID
verification_idVerification unique ID
methodVerification method (currently only "OTP" supported)
otp_value6-digit OTP code for verification
statusVerification process status (PENDING/SUCCESS/FAILED)
confirmVerification confirmation status (PENDING/ACCEPTED/DECLINED)
occur_timeTrigger time (milliseconds)
Purpose
This webhook is triggered when a Google Pay binding requires verification via OTP. Currently only applicable to specific card templates: 9, 10
Action Required
When receiving a CARD_VERIFICATION webhook:
1.
Display the otp_value to the user
2.
Instruct the user to enter this OTP code on the Google Pay verification page
3.
The verification process will complete automatically once the user enters the correct OTP
The webhook provides all necessary information for the merchant to guide their users through the Google Pay binding verification process.

14. MERCHANT_BALANCE_RECHARGED#

Decrypted JSON String (Success)
Decrypted JSON String (Failed)
Result Fields
FieldDescription
merchant_idMerchant unique ID (UUID)
order_idPayment operation order ID
amountRequested recharge amount
old_balanceMerchant balance before the operation
new_balanceMerchant balance after the operation
statusOperation status (SUCCESS/FAILED)
errorError message (only present for failed operations)
timestampOperation timestamp (ISO 8601 format)
Purpose
This webhook is triggered when a merchant balance recharge operation completes via crypto deposit to the reserve. It notifies API merchants about the result of their balance top-up request.
Modified at 2026-02-06 12:34:05
Previous
Integration Guide
Next
Get Account Balance
Built with