Skip to main content

Webhook Notifications

Notification payloads for each webhook event type.

Events​

WEBHOOK_CREATED

    type WEBHOOK_CREATEDrequired

    data

    object

    required

    webhookId stringrequired
    traceId stringrequired

WEBHOOK_UPDATED

    type WEBHOOK_UPDATEDrequired

    data

    object

    required

    webhookId stringrequired
    traceId stringrequired

WEBHOOK_DELETED

Sent when a webhook subscription is deleted (soft-deleted).

    type WEBHOOK_DELETEDrequired

    data

    object

    required

    webhookId stringrequired
    traceId stringrequired

CUSTOMER_CREATED

    type CUSTOMER_CREATEDrequired

    data

    object

    required

    customerId stringrequired
    traceId stringrequired

Bank Transaction Events​

Events for ACH and wire transfers. Use GET /v1/baas/transactions/:bankTransactionId for full details.

BANK_DEPOSIT_TRANSACTION_PENDING

Deposit received, pending clearing.

    type BANK_DEPOSIT_TRANSACTION_PENDINGrequired

    data

    object

    required

    walletId stringrequired
    bankTransactionId stringrequired
    traceId stringrequired

BANK_DEPOSIT_TRANSACTION_COMPLETED

Deposit cleared successfully.

    type BANK_DEPOSIT_TRANSACTION_COMPLETEDrequired

    data

    object

    required

    walletId stringrequired
    bankTransactionId stringrequired
    traceId stringrequired

BANK_DEPOSIT_TRANSACTION_FAILED

Deposit failed (returned, rejected).

    type BANK_DEPOSIT_TRANSACTION_FAILEDrequired

    data

    object

    required

    walletId stringrequired
    bankTransactionId stringrequired
    traceId stringrequired

BANK_WITHDRAWAL_TRANSACTION_PENDING

Withdrawal initiated, funds reserved.

    type BANK_WITHDRAWAL_TRANSACTION_PENDINGrequired

    data

    object

    required

    walletId stringrequired
    bankTransactionId stringrequired
    traceId stringrequired

BANK_WITHDRAWAL_TRANSACTION_COMPLETED

Withdrawal completed successfully.

    type BANK_WITHDRAWAL_TRANSACTION_COMPLETEDrequired

    data

    object

    required

    walletId stringrequired
    bankTransactionId stringrequired
    traceId stringrequired

BANK_WITHDRAWAL_TRANSACTION_FAILED

Withdrawal failed.

    type BANK_WITHDRAWAL_TRANSACTION_FAILEDrequired

    data

    object

    required

    walletId stringrequired
    bankTransactionId stringrequired
    traceId stringrequired

Internal Transfer Events​

Events for wallet-to-wallet transfers. Note: Internal transfers send 2 webhooks - one for each wallet.

INTERNAL_TRANSACTION_COMPLETED

Internal transfer completed. Source wallet owner receives a debit webhook; destination wallet owner receives a credit webhook.

    type INTERNAL_TRANSACTION_COMPLETEDrequired

    data

    object

    required

    walletId stringrequired

    The wallet receiving this webhook

    transactionId stringrequired

    Parent ledger transaction ID

    traceId stringrequired

VIRTUAL_ACCOUNT_CREATED

    type VIRTUAL_ACCOUNT_CREATEDrequired

    data

    object

    required

    customerId stringrequired
    walletId stringrequired
    traceId stringrequired

CUSTOMER_KYC_STARTED

    type CUSTOMER_KYC_STARTEDrequired

    data

    object

    required

    customerId stringrequired
    status stringrequired
    onboardingId stringrequired
    traceId stringrequired

CUSTOMER_KYC_SDK_FLOW_REQUIRED

SDK links generated. User needs to complete identity verification.

    type CUSTOMER_KYC_SDK_FLOW_REQUIREDrequired

    data

    object

    required

    customerId stringrequired
    status stringrequired
    onboardingId stringrequired
    traceId stringrequired

CUSTOMER_KYC_SDK_FLOW_COMPLETED

User finished SDK flow. Identity verification submitted.

    type CUSTOMER_KYC_SDK_FLOW_COMPLETEDrequired

    data

    object

    required

    customerId stringrequired
    status stringrequired
    onboardingId stringrequired
    traceId stringrequired

CUSTOMER_KYC_FINISHED

Final KYC outcome reached. Check the status field (APPROVED, DENIED_COMPLIANCE, etc.).

    type CUSTOMER_KYC_FINISHEDrequired

    data

    object

    required

    customerId stringrequired
    status stringrequired
    onboardingId stringrequired
    traceId stringrequired

CUSTOMER_KYC_RESTARTED

KYC re-run via POST /v1/compliance/kyc/:id/rerun. New onboarding created.

    type CUSTOMER_KYC_RESTARTEDrequired

    data

    object

    required

    customerId stringrequired
    status stringrequired
    onboardingId stringrequired

    New onboarding ID

    previousOnboardingId stringrequired

    Previous (archived) onboarding ID

    traceId stringrequired

CUSTOMER_KYC_SDK_EXPIRED

SDK links expired before user completed verification.

    type CUSTOMER_KYC_SDK_EXPIREDrequired

    data

    object

    required

    customerId stringrequired
    status stringrequired
    onboardingId stringrequired
    traceId stringrequired

CUSTOMER_KYC_ERROR

System error during verification. Contact support may be required.

    type CUSTOMER_KYC_ERRORrequired

    data

    object

    required

    customerId stringrequired
    status stringrequired
    onboardingId stringrequired
    errorType string

    Type of error

    errorMessage string

    Error description

    traceId stringrequired

COOP_AUTH_0100

Authorization request for cooperative authorization cards. Sent when a card transaction requires approval.

    type COOP_AUTH_0100required

    data

    object

    required

    mti stringrequired

    ISO8583 message type indicator

    stan stringrequired

    System trace audit number

    rrn stringrequired

    Retrieval reference number

    amountMinor numberrequired

    Transaction amount in minor units (cents)

    billingAmountMinor numberrequired

    Cardholder billing amount in minor units

    currency stringrequired

    ISO 4217 currency code (e.g., USD)

    processingCode stringrequired

    Processing code indicating transaction type

    mcc stringrequired

    Merchant category code

    posEntryMode stringrequired

    Point of service entry mode

    posConditionCode stringrequired

    Point of service condition code

    terminalId stringrequired

    Card acceptor terminal identification

    merchantId stringrequired

    Card acceptor identification code

    merchantNameLocation stringrequired

    Merchant name and location

    acquirerId stringrequired

    Acquiring institution identification code

    cardReferenceId stringrequired

    Internal card reference identifier

    posData stringrequired

    Point of service data

    networkData stringrequired

    Network-specific data

    networkDataRef string

    Stable transaction lifecycle identifier extracted from network data. Use this field to correlate authorization and completion messages when the RRN changes due to settlement batching.

    tpi string

    Transaction processing indicator

    surchargeAmountMinor number

    Surcharge amount in minor units

    additionalAmounts string

    Additional amounts data

    posPinCaptureCode string

    PIN capture code

    timestamp stringrequired

    ISO 8601 timestamp

    raw

    object

    isoMti stringrequired

    Original ISO8583 MTI

    fields objectrequired

    Raw ISO8583 fields (sensitive data stripped)

    traceId stringrequired

COOP_AUTH_0120

Authorization advice for cooperative authorization cards. Sent for advice messages.

    type COOP_AUTH_0120required

    data

    object

    required

    Same payload structure as COOP_AUTH_0100. See above for field descriptions.

    traceId stringrequired

COOP_AUTH_0200

Financial transaction for cooperative authorization cards. Sent for financial presentments.

    type COOP_AUTH_0200required

    data

    object

    required

    Same payload structure as COOP_AUTH_0100. See above for field descriptions.

    traceId stringrequired

COOP_AUTH_0220

Authorization completion for cooperative authorization cards. Note: The RRN may differ from the original authorization due to settlement batching - use networkDataRef for reliable correlation.

    type COOP_AUTH_0220required

    data

    object

    required

    Same payload structure as COOP_AUTH_0100. See above for field descriptions.

    traceId stringrequired

COOP_AUTH_0420

Reversal transaction for cooperative authorization cards. Sent when a previously authorized transaction is reversed.

    type COOP_AUTH_0420required

    data

    object

    required

    Same payload structure as COOP_AUTH_0100, with additional original field containing the original transaction's mti, stan, and rrn.

    original

    object

    mti stringrequired

    Original transaction MTI

    stan stringrequired

    Original transaction STAN

    rrn stringrequired

    Original transaction RRN

    traceId stringrequired

Card Transaction Events (Debit Cards)​

Events for debit card transactions. Use GET /v1/cards/transactions/:cardTransactionId for full details.

CARD_TRANSACTION_PENDING

Authorization approved - a hold is placed on the card.

    type CARD_TRANSACTION_PENDINGrequired

    data

    object

    required

    cardId stringrequired
    cardTransactionId stringrequired
    traceId stringrequired

CARD_TRANSACTION_COMPLETED

Transaction settled - funds have been captured.

    type CARD_TRANSACTION_COMPLETEDrequired

    data

    object

    required

    cardId stringrequired
    cardTransactionId stringrequired
    traceId stringrequired

CARD_TRANSACTION_FAILED

Authorization denied - no hold placed.

    type CARD_TRANSACTION_FAILEDrequired

    data

    object

    required

    cardId stringrequired
    cardTransactionId stringrequired
    traceId stringrequired

CARD_TRANSACTION_CANCELLED

Transaction reversed or voided.

    type CARD_TRANSACTION_CANCELLEDrequired

    data

    object

    required

    cardId stringrequired
    cardTransactionId stringrequired
    traceId stringrequired

Crypto Transaction Events​

Events for cryptocurrency deposits and withdrawals. Use GET /v1/baas/transactions?cryptoTransactionId=:id for full details.

CRYPTO_DEPOSIT_TRANSACTION_PENDING

Crypto deposit detected on-chain, awaiting confirmations.

    type CRYPTO_DEPOSIT_TRANSACTION_PENDINGrequired

    data

    object

    required

    walletId stringrequired
    cryptoTransactionId stringrequired
    traceId stringrequired

CRYPTO_DEPOSIT_TRANSACTION_COMPLETED

Crypto deposit confirmed.

    type CRYPTO_DEPOSIT_TRANSACTION_COMPLETEDrequired

    data

    object

    required

    walletId stringrequired
    cryptoTransactionId stringrequired
    traceId stringrequired

CRYPTO_DEPOSIT_TRANSACTION_FAILED

Crypto deposit failed.

    type CRYPTO_DEPOSIT_TRANSACTION_FAILEDrequired

    data

    object

    required

    walletId stringrequired
    cryptoTransactionId stringrequired
    traceId stringrequired

CRYPTO_WITHDRAWAL_TRANSACTION_PENDING

Crypto withdrawal initiated.

    type CRYPTO_WITHDRAWAL_TRANSACTION_PENDINGrequired

    data

    object

    required

    walletId stringrequired
    cryptoTransactionId stringrequired
    traceId stringrequired

CRYPTO_WITHDRAWAL_TRANSACTION_COMPLETED

Crypto withdrawal confirmed on-chain.

    type CRYPTO_WITHDRAWAL_TRANSACTION_COMPLETEDrequired

    data

    object

    required

    walletId stringrequired
    cryptoTransactionId stringrequired
    traceId stringrequired

CRYPTO_WITHDRAWAL_TRANSACTION_FAILED

Crypto withdrawal failed.

    type CRYPTO_WITHDRAWAL_TRANSACTION_FAILEDrequired

    data

    object

    required

    walletId stringrequired
    cryptoTransactionId stringrequired
    traceId stringrequired