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:

http
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

json
{  "transaction_reference": "string",  "expected_status": "successful" | "failed"}
FieldTypeRequiredDescription
transaction_referencestringYesThe transaction reference of an existing payout transaction
expected_statusstringYesExpected webhook status: "successful" or "failed"

Success Response (200 OK)

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

Response Fields

FieldTypeDescription
successbooleanIndicates if the mock webhook was sent successfully
messagestringHuman-readable message
data.transaction_referencestringThe transaction reference that was processed
data.expected_statusstringThe expected status that was simulated
data.webhook_sentbooleanIndicates if the webhook was successfully sent

Error Responses

Status CodeDescription
400Invalid request (missing fields, invalid status, etc.)
401Unauthorized - Invalid or missing API key or signature
403Forbidden - Endpoint blocked in production environment
404Transaction not found
422Unprocessable entity (transaction in invalid state)
500Internal server error

Example: cURL

bash
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

http
POST /api/v1/client/mock/payout-webhook HTTP/1.1Host: api.sznd.appx-api-key: your_api_key_herex-timestamp: 2025-01-30T12:20:15Zx-signature: generated_signature_hereContent-Type: application/json
{  "transaction_reference": "TXN123456789",  "expected_status": "successful"}

Use Cases

  1. Testing Payout Flows - Simulate payout webhooks to test your payout handling logic
  2. Transaction Status Testing - Verify transaction statuses update correctly after payouts
  3. Webhook Testing - Test webhook handling without real payouts
  4. Integration Testing - Test end-to-end payout flows in staging environments
  5. 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

  1. Use Real Transaction References - Always use actual transaction references from your test environment
  2. Test Both Statuses - Test both "successful" and "failed" statuses to ensure error handling works
  3. Verify Transaction States - Ensure transactions are in the correct state before simulating webhooks
  4. Check Transaction Updates - After simulating webhooks, verify transaction statuses updated correctly
  5. 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