Transaction Webhook

Business clients receive real-time notifications when transaction status changes occur. This webhook provides comprehensive information about all transaction types including deposits, withdrawals, exchanges, direct exchanges, and transfers.

When is this webhook sent?

The transaction webhook is sent when:

  • A transaction status changes (e.g., from PENDING to COMPLETED, PROCESSING to FAILED)
  • The transaction belongs to a user associated with your business
  • Your business API key has a webhook URL configured
  • CAD Interac payout (non-autodeposit): a pending payout receives security credentials from the provider — you get an additional webhook while status is still PROCESSING, with interac_payout_instruction populated (before the final COMPLETED or FAILED webhook)

Payload Schema

The transaction webhook uses a unified payload structure that works for all transaction types and currencies:

json
{  "event_type": "transaction",  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",  "transaction_type": "DEPOSIT",  "status": "COMPLETED",  "reference": "TXN-123456789",  "user_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",  "created_at": "2024-01-15T10:30:00Z",  "timestamp": "2024-01-15T10:35:00Z",  "origin_reference": "550e8400-e29b-41d4-a716-446655440001",  "source_currency": "CAD",  "source_amount": "100.00",  "source_amount_with_fees": "105.00",  "target_currency": "USD",  "target_amount": "75.00",  "amount_with_fees": "105.00",  "fee": "5.00",  "fee_currency": "CAD",  "exchange_rate": "0.75",  "sender": {    "email": "sender@example.com",    "account_number": "1234567890",    "account_name": "John Doe",    "bank_name": "Example Bank",    "beneficiary_id": "550e8400-e29b-41d4-a716-446655440002"  },  "recipient": {    "email": "recipient@example.com",    "account_number": "9876543210",    "account_name": "Jane Smith",    "bank_name": "Another Bank",    "beneficiary_id": "550e8400-e29b-41d4-a716-446655440003"  }}

Payload Fields

Core Fields

FieldTypeRequiredDescription
event_typestringYesAlways "transaction" for this webhook type
transaction_idstringYesUnique identifier for the transaction (UUID format)
transaction_typestringYesType of transaction: DEPOSIT, WITHDRAWAL, EXCHANGE, DIRECT_EXCHANGE, TRANSFER
statusstringYesCurrent transaction status: PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED
referencestringYesTransaction reference you can use to reconcile
user_idstringYesUnique identifier for the user who owns the transaction (UUID format)
created_atstringYesRFC3339 timestamp indicating when the transaction was created (UTC)
timestampstringYesRFC3339 timestamp indicating when the webhook was generated (UTC)
origin_referencestringYesOrigin reference UUID associated with the transaction

Currency and Amount Fields

FieldTypeRequiredDescription
source_currencystringYesCurrency code of the source currency (e.g., CAD, USD, EUR, GBP)
source_amountstringYesAmount in source currency (decimal string)
source_amount_with_feesstringYesTotal source amount including fees; this is the amount tendered/payable in the source currency (decimal string)
target_currencystringYesCurrency code of the target currency (e.g., CAD, USD, EUR, GBP)
target_amountstringYesAmount in target currency (decimal string)
amount_with_feesstringYesTotal amount including fees (decimal string)
feestringNoTotal fee amount (decimal string, omitted if zero)
fee_currencystringNoCurrency of the fee (omitted if no fee)
exchange_ratestringNoExchange rate used for cross-currency transactions (omitted for same-currency transactions)

Party Information

FieldTypeRequiredDescription
senderobjectNoSender information (structure varies by transaction type)
recipientobjectNoRecipient information (structure varies by transaction type)

Sender and Recipient Fields

The sender and recipient objects contain party details. Fields are included based on availability and transaction type:

FieldTypeDescription
emailstringEmail address of the party
account_numberstringBank account number or payment address
account_namestringName associated with the account
bank_namestringName of the bank or financial institution
beneficiary_idstringUnique identifier for the beneficiary (UUID format, if applicable)

CAD Interac payout instruction

For CAD Interac payouts to non-autodeposit beneficiaries, the provider returns a security question and answer asynchronously. When available, the outbound transaction webhook includes:

FieldTypeRequiredDescription
interac_payout_instructionobjectNoOmitted unless target_currency is CAD and the provider has returned payout security credentials
interac_payout_instruction.questionstringYes*Interac security question (*when parent object is present)
interac_payout_instruction.answerstringYes*Interac security answer as a numeric string (*when parent object is present)

This object is omitted for:

  • Non-CAD transactions (NGN, USD, EUR, GBP, etc.)
  • CAD autodeposit Interac recipients
  • CAD Interac payouts before the provider returns question/answer (e.g. immediately after accept)

Treat answer as confidential — share only with the intended beneficiary.

You may receive an additional transaction webhook while the payout is still PROCESSING (before the final COMPLETED or FAILED webhook) when these credentials become available.

Transaction Types

DEPOSIT

A deposit transaction represents funds being sent from an external party to your user.

  • Sender: External party (may include payment sender name, email, or account number)
  • Recipient: Your user (may include beneficiary account details if deposit is to a beneficiary account)

Example:

json
{  "event_type": "transaction",  "transaction_type": "DEPOSIT",  "status": "COMPLETED",  "sender": {    "email": "external@example.com",    "account_name": "External Sender"  },  "recipient": {    "email": "user@example.com",    "account_name": "John Doe",    "account_number": "1234567890",    "bank_name": "User Bank",    "beneficiary_id": "550e8400-e29b-41d4-a716-446655440002"  }}

WITHDRAWAL

A withdrawal transaction represents funds being sent from your user to an external beneficiary.

  • Sender: Your user
  • Recipient: External beneficiary

Example:

json
{  "event_type": "transaction",  "transaction_type": "WITHDRAWAL",  "status": "COMPLETED",  "sender": {    "email": "user@example.com",    "account_name": "John Doe"  },  "recipient": {    "email": "beneficiary@example.com",    "account_number": "9876543210",    "account_name": "Jane Smith",    "bank_name": "Beneficiary Bank",    "beneficiary_id": "550e8400-e29b-41d4-a716-446655440003"  }}

EXCHANGE

An exchange transaction represents currency conversion within your user's account.

  • Sender: Your user
  • Recipient: Your user (same user, different currency)

Example:

json
{  "event_type": "transaction",  "transaction_type": "EXCHANGE",  "status": "COMPLETED",  "source_currency": "CAD",  "source_amount": "100.00",  "target_currency": "USD",  "target_amount": "75.00",  "exchange_rate": "0.75",  "sender": {    "email": "user@example.com",    "account_name": "John Doe"  },  "recipient": {    "email": "user@example.com",    "account_name": "John Doe"  }}

DIRECT_EXCHANGE

A direct exchange transaction represents a deposit that is immediately converted to a different currency.

  • Sender: External party (deposit sender)
  • Recipient: Your user (in target currency)

Example:

json
{  "event_type": "transaction",  "transaction_type": "DIRECT_EXCHANGE",  "status": "COMPLETED",  "source_currency": "CAD",  "source_amount": "100.00",  "target_currency": "USD",  "target_amount": "75.00",  "exchange_rate": "0.75",  "sender": {    "email": "external@example.com",    "account_name": "External Sender"  },  "recipient": {    "email": "user@example.com",    "account_name": "John Doe"  }}

TRANSFER

A transfer transaction represents funds being sent from your user to another user or beneficiary.

  • Sender: Your user
  • Recipient: Another user or beneficiary

Example:

json
{  "event_type": "transaction",  "transaction_type": "TRANSFER",  "status": "COMPLETED",  "sender": {    "email": "user@example.com",    "account_name": "John Doe"  },  "recipient": {    "email": "recipient@example.com",    "account_number": "9876543210",    "account_name": "Jane Smith",    "bank_name": "Recipient Bank",    "beneficiary_id": "550e8400-e29b-41d4-a716-446655440003"  }}

Transaction Status Values

StatusDescription
PENDINGTransaction has been created but not yet processed
PROCESSINGTransaction is currently being processed
COMPLETEDTransaction has been successfully completed
FAILEDTransaction failed to complete
CANCELLEDTransaction was cancelled

Example Payloads

Example 1: Completed Deposit

json
{  "event_type": "transaction",  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",  "transaction_type": "DEPOSIT",  "status": "COMPLETED",  "reference": "TXN-123456789",  "user_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",  "created_at": "2024-01-15T10:30:00Z",  "timestamp": "2024-01-15T10:35:00Z",  "origin_reference": "550e8400-e29b-41d4-a716-446655440001",  "source_currency": "CAD",  "source_amount": "100.00",  "target_currency": "CAD",  "target_amount": "100.00",  "amount_with_fees": "100.00",  "sender": {    "email": "sender@example.com",    "account_name": "External Sender"  },  "recipient": {    "email": "user@example.com",    "account_name": "John Doe"  }}

Example 2: Failed Withdrawal

json
{  "event_type": "transaction",  "transaction_id": "660e8400-e29b-41d4-a716-446655440001",  "transaction_type": "WITHDRAWAL",  "status": "FAILED",  "reference": "TXN-987654321",  "user_id": "7ba7b810-9dad-11d1-80b4-00c04fd430c9",  "created_at": "2024-01-15T11:00:00Z",  "timestamp": "2024-01-15T11:05:00Z",  "origin_reference": "660e8400-e29b-41d4-a716-446655440002",  "source_currency": "USD",  "source_amount": "50.00",  "target_currency": "NGN",  "target_amount": "40000.00",  "amount_with_fees": "52.50",  "fee": "2.50",  "fee_currency": "USD",  "exchange_rate": "800.00",  "sender": {    "email": "user@example.com",    "account_name": "Jane Smith"  },  "recipient": {    "account_number": "1234567890",    "account_name": "Beneficiary Name",    "bank_name": "Beneficiary Bank",    "beneficiary_id": "770e8400-e29b-41d4-a716-446655440003"  }}

Example 3: CAD Interac payout — security credentials (PROCESSING)

Sent when a CAD Interac payout targets a non-autodeposit beneficiary and the provider returns security question/answer. Status is still PROCESSING; a later webhook will carry COMPLETED or FAILED.

json
{  "event_type": "transaction",  "transaction_id": "880e8400-e29b-41d4-a716-446655440005",  "transaction_type": "WITHDRAWAL",  "status": "PROCESSING",  "status_name": "PROCESSING",  "reference": "TXN-CAD-INTERAC-001",  "user_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",  "created_at": "2024-01-15T14:00:00Z",  "timestamp": "2024-01-15T14:02:15Z",  "origin_reference": "PAYOUT-2026-CAD-001",  "source_currency": "CAD",  "source_amount": "100.00",  "source_amount_with_fees": "102.00",  "target_currency": "CAD",  "target_amount": "100.00",  "amount_with_fees": "102.00",  "amount_tendered_with_fees": "102.00",  "amount_tendered_without_fees": "100.00",  "amount_received": "100.00",  "payment_completed": false,  "fee": "2.00",  "fee_currency": "CAD",  "tracking_message": "Processing Payout",  "recipient": {    "email": "alex.tremblay@example.com",    "account_name": "Alex Tremblay",    "beneficiary_id": "550e8400-e29b-41d4-a716-446655440000"  },  "interac_payout_instruction": {    "question": "What is your reference number?",    "answer": "48291"  }}

Example 4: Processing Exchange

json
{  "event_type": "transaction",  "transaction_id": "770e8400-e29b-41d4-a716-446655440002",  "transaction_type": "EXCHANGE",  "status": "PROCESSING",  "reference": "TXN-456789123",  "user_id": "8ba7b810-9dad-11d1-80b4-00c04fd430c0",  "created_at": "2024-01-15T12:00:00Z",  "timestamp": "2024-01-15T12:01:00Z",  "origin_reference": "770e8400-e29b-41d4-a716-446655440004",  "source_currency": "EUR",  "source_amount": "200.00",  "target_currency": "GBP",  "target_amount": "170.00",  "amount_with_fees": "202.00",  "fee": "2.00",  "fee_currency": "EUR",  "exchange_rate": "0.85",  "sender": {    "email": "user@example.com",    "account_name": "Bob Johnson"  },  "recipient": {    "email": "user@example.com",    "account_name": "Bob Johnson"  }}

Important Notes

  1. Status Changes: This webhook is sent whenever a transaction status changes. You may receive multiple webhooks for the same transaction as it progresses through different statuses.

  2. Idempotency: Implement idempotency handling in your webhook receiver. Use transaction_id plus status (and whether interac_payout_instruction is present) to deduplicate events. CAD Interac payouts may deliver one PROCESSING webhook with credentials and a later COMPLETED or FAILED webhook for the same transaction.

  3. Party Information: The sender and recipient fields are populated based on the transaction type. Some fields may be omitted if the information is not available.

  4. Exchange Rate: The exchange_rate field is only included for cross-currency transactions. For same-currency transactions (e.g., CAD to CAD), this field is omitted.

  5. Fees: The fee and fee_currency fields are omitted if there are no fees associated with the transaction.

  6. CAD Interac payout instruction: interac_payout_instruction is omitted from the JSON payload unless target_currency is CAD and payout security credentials are available. It is not included on accept-quote responses — only on the outbound transaction webhook.

  7. Webhook Security: This webhook uses the same security mechanism as other business webhooks:

    • Signed with HMAC-SHA256 using your API key's secret
    • Includes X-Transfaar-Signature header for verification
    • Same retry logic applies (up to 10 attempts with exponential backoff, only retries if response is not 200 OK)