Mock Payout Webhook

Simulate external provider payout webhooks for testing purposes. This endpoint constructs webhook payloads that match the exact format expected by real webhook handlers.

Endpoint

POST /api/v1/client/mock/payout-webhook

Description

Simulates payout webhooks from external providers. The endpoint:

Constructs webhook payloads matching real provider formats
Sends them to the appropriate webhook handlers
Updates transaction statuses accordingly
Supports both successful and failed payout scenarios

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

x-api-key: <your-api-key>
x-timestamp: <RFC3339-timestamp>
x-signature: <HMAC-signature>

Note: For HMAC authentication details, see the Authentication guide.

Request Body

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

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

Success Response (200 OK)

{
  "success": true,
  "message": "Mock payout 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 (missing fields, invalid status, etc.)
`401`	Unauthorized - Invalid or missing API key or signature
`403`	Forbidden - Endpoint blocked in production environment
`404`	Transaction not found
`422`	Unprocessable entity (transaction in invalid state)
`500`	Internal server error

Example: cURL

curl -X POST "https://api.sznd.app/api/v1/client/mock/payout-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/payout-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 Payout Flows - Simulate payout webhooks to test your payout handling logic
Transaction Status Testing - Verify transaction statuses update correctly after payouts
Webhook Testing - Test webhook handling without real payouts
Integration Testing - Test end-to-end payout flows in staging environments
Error Handling - Test both successful and failed payout scenarios

Important Notes

Transaction Must Exist: The transaction reference must point to an existing payout transaction
Production Blocked: This endpoint is automatically blocked in production environments
Webhook Processing: The simulated webhook goes through the same processors as real webhooks
Transaction Updates: Successful webhooks will update transaction statuses accordingly

Best Practices

Use Real Transaction References - Always use actual transaction references from your test environment
Test Both Statuses - Test both "successful" and "failed" statuses to ensure error handling works
Verify Transaction States - Ensure transactions are in the correct state before simulating webhooks
Check Transaction Updates - After simulating webhooks, verify transaction statuses updated correctly
Handle Errors Gracefully - Mock endpoints can fail; ensure your code handles errors appropriately

Security Considerations

Production Blocking: This endpoint is automatically blocked in production environments
Authentication Required: Requires valid HMAC authentication
Transaction Validation: Endpoint validates transaction states before processing

Related Endpoints

Mock Deposit - Simulate deposit webhooks
Transactions API - View transaction details and statuses
Wallets API - Check wallet balances
Quotes API - Create quotes before testing payout flows

💰 Mock Deposit