BananaTech
  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
    • 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_RECHARGE_RESULT
7.
CARD_CLOSE_RESULT
8.
TRANSACTION_CREATED
9.
CARD_CORRECTION
10.
CARD_3DS
11.
CARD_VERIFICATION

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_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)

7. CARD_CLOSE_RESULT#

Decrypted JSON String
Result Fields
FieldDescription
card_idCard unique ID
transaction_idTransaction unique ID
refund_amountRefunded amount
statusTransaction status
descriptionTransaction description
occur_timeTrigger time (milliseconds)

8. 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)

9. 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)

10. 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)
merchant_nameMerchant name
merchant_countryMerchant country code
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:

11. 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.
Modified at 2025-12-05 12:37:24
Previous
Integration Guide
Next
Get Account Balance
Built with