Mock Deposit Webhook

Simulate deposit webhooks for Direct Exchange quotes and Virtual Bank Account (VBA) deposits. This allows you to test deposit flows without making actual deposits.

Overview

There are two endpoints for simulating deposits:

Simulate VBA Deposit - For Virtual Bank Account deposits (any rail/currency)
Direct Exchange Deposit Webhook - For Direct Exchange quotes (source funding)

Simulate VBA Deposit

Simulates a deposit to a Virtual Bank Account (VBA) by providing an account number or email (for CAD) and amount. This endpoint works for any payment rail and currency.

Endpoint

POST /api/v1/client/mock/simulate-deposit

Description

Simulates deposits to Virtual Bank Accounts (VBAs) for testing purposes. The endpoint:

Accepts either account_number or email (for CAD Interac deposits)
Automatically detects the currency based on the VBA
Builds webhook payloads matching real provider formats
Sends webhooks to the same processors as real deposits
Supports multiple currencies: NGN, CAD, USD, GBP, EUR
Credits the wallet linked to the VBA (VBAs are created with a primary_wallet_id)

Important: The VBA must be created first and linked to a wallet. Deposits will credit the wallet associated with the VBA's primary_wallet_id.

Request Body

{
  "account_number": "string",
  "email": "string",
  "amount": 100.50
}

Field	Type	Required	Description
`account_number`	string	Conditional	Virtual Bank Account number (required if `email` not provided)
`email`	string	Conditional	Email address for CAD Interac deposits (required if `account_number` not provided)
`amount`	number	Yes	Deposit amount (must be greater than 0)

Note: Provide either account_number or email, but not both.

Success Response (200 OK)

{
  "message": "Deposit simulation sent to webhook processor",
  "currency": "CAD",
  "amount": "100.50",
  "vba_ident": "user@example.com",
  "webhook_sent": true
}

Response Fields

Field	Type	Description
`message`	string	Human-readable message
`currency`	string	Currency code of the VBA (e.g., "NGN", "CAD", "USD")
`amount`	string	The deposit amount as a string
`vba_ident`	string	The identifier used (account_number or email)
`webhook_sent`	boolean	Indicates if the webhook was successfully sent

Error Responses

Status Code	Description
`400`	Invalid request (missing amount, both account_number and email provided, etc.)
`401`	Unauthorized - Invalid or missing API key or signature
`403`	Forbidden - Endpoint blocked in production environment
`404`	VBA not found for the provided account_number or email
`500`	Internal server error

Example: cURL

Using Account Number (NGN, USD, GBP, EUR)

curl -X POST "https://api.sznd.app/api/v1/client/mock/simulate-deposit" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "1234567890",
    "amount": 1000.00
  }'

Using Email (CAD Interac)

curl -X POST "https://api.sznd.app/api/v1/client/mock/simulate-deposit" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "amount": 500.00
  }'

Example: HTTP Request

POST /api/v1/client/mock/simulate-deposit HTTP/1.1
Host: api.sznd.app
x-api-key: your_api_key_here
x-timestamp: 2025-01-30T12:20:15Z
x-signature: generated_signature_here
Content-Type: application/json

{
  "account_number": "1234567890",
  "amount": 1000.00
}

Mock Direct Exchange Deposit Webhook

Simulates the source-leg deposit webhook for an existing Direct Exchange quote. This endpoint is specifically for Direct Exchange transactions where you need to simulate the source funding.

Endpoint

POST /api/v1/client/mock/direct-exchange-deposit-webhook

Description

Simulates source funding webhooks for Direct Exchange quotes only. The endpoint:

Accepts only Direct Exchange quote transactions
Builds deposit webhook payloads matching real provider formats
Sends webhooks to the same processors as real webhooks
Supports both successful and failed deposit scenarios

Note: For Virtual Bank Account (VBA) based deposits (any rail), use /mock/simulate-deposit instead.

Request Body

{
  "transaction_reference": "string",
  "expected_status": "successful" | "failed"
}

Field	Type	Required	Description
`transaction_reference`	string	Yes	The transaction reference of an existing Direct Exchange transaction
`expected_status`	string	Yes	Expected webhook status: `"successful"` or `"failed"`

Success Response (200 OK)

{
  "success": true,
  "message": "Mock deposit webhook sent successfully",
  "data": {
    "transaction_reference": "TXN123456789",
    "expected_status": "successful",
    "webhook_sent": true
  }
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the mock webhook was sent successfully
`message`	string	Human-readable message
`data.transaction_reference`	string	The transaction reference that was processed
`data.expected_status`	string	The expected status that was simulated
`data.webhook_sent`	boolean	Indicates if the webhook was successfully sent

Error Responses

Status Code	Description
`400`	Invalid request or quote is not Direct Exchange type
`401`	Unauthorized - Invalid or missing API key or signature
`403`	Forbidden - Endpoint blocked in production environment
`404`	Transaction not found
`422`	Unprocessable entity
`500`	Internal server error

Example: cURL

curl -X POST "https://api.sznd.app/api/v1/client/mock/direct-exchange-deposit-webhook" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_reference": "TXN123456789",
    "expected_status": "successful"
  }'

Example: HTTP Request

POST /api/v1/client/mock/direct-exchange-deposit-webhook HTTP/1.1
Host: api.sznd.app
x-api-key: your_api_key_here
x-timestamp: 2025-01-30T12:20:15Z
x-signature: generated_signature_here
Content-Type: application/json

{
  "transaction_reference": "TXN123456789",
  "expected_status": "successful"
}

Use Cases

Testing Deposit Flows - Simulate deposits to test your deposit handling logic
Wallet Balance Testing - Verify wallet balances update correctly after deposits
Webhook Testing - Test webhook handling without real deposits
Integration Testing - Test end-to-end deposit flows in staging environments
Currency Testing - Test deposits for different currencies (NGN, CAD, USD, GBP, EUR)
Direct Exchange Testing - Test Direct Exchange source funding flows

Prerequisites

Before simulating deposits, ensure you have:

Created a Wallet - A wallet must exist for the currency you want to deposit to
Created a VBA - The Virtual Bank Account must be created and linked to the wallet
VBA-Wallet Linkage - VBAs are linked to wallets at creation time; deposits to a VBA will credit the linked wallet

Note: See Virtual Wallets API for creating VBAs and Wallets API for wallet management.

Important Notes

CAD Deposits: Use email parameter instead of account_number for CAD Interac deposits
VBA Must Exist: The VBA (identified by account_number or email) must exist in the system and be linked to a wallet
Wallet Required: A wallet must exist for the VBA's currency before deposits can be simulated
VBA-Wallet Relationship: VBAs are created with a primary_wallet_id that links them to a specific wallet; deposits credit this wallet
Production Blocked: These endpoints are automatically blocked in production environments
Webhook Processing: The simulated webhook goes through the same processors as real webhooks
Transaction Creation: Successful deposits will create transactions and update wallet balances
Direct Exchange Only: The /direct-exchange-deposit-webhook endpoint only works with Direct Exchange quotes

Related Endpoints

Mock Payout - Simulate payout webhooks
Transactions API - View transaction details and statuses
Wallets API - Check wallet balances after simulated deposits
Quotes API - Create quotes before testing deposit flows
Virtual Wallets API - Create VBAs for deposit simulation

📋 Overview 💸 Mock Payout