Direct Deposits
Credit a user's SwitchLock wallet directly from an external bank transfer. No payment link, no buyer action — your server posts the deposit and funds appear immediately.
What direct deposits are for
A direct deposit is how external bank money enters the SwitchLock system. Unlike a payment link — where the buyer pays from an existing wallet balance — a deposit is called by your server when you receive confirmation of an external bank transfer and want to reflect that balance inside SwitchLock.
A seller deposits via EFT from their bank. Your reconciliation job calls this endpoint to credit their SwitchLock account.
Pre-load a merchant's wallet so they can accept payment links immediately without waiting for buyer funds.
Set isTransit: true to route the deposit into a CLEARING account — the system then moves funds to escrow automatically.
Use deposits to fund each employee wallet before a payout run — pairs with the payout endpoints.
POST /v1/payments/deposit
Requires an API key and x-company-id. The response is the saved transaction record with a generated reference in the form DEP-{receiptNumber}.
Include an x-idempotency-key header on every deposit. Duplicate requests with the same key return the original transaction instead of crediting the wallet twice. Use your bank reference or a deterministic UUID as the key.
Amounts are in cents. $50.00 USD = 5000. ZiG 200.00 = 20000. Never pass decimals.
curl -X POST "https://api.switchlock.co.zw/v1/payments/deposit" \
-H "x-api-key: sl_live_a1b2c3d4e5f6..." \
-H "x-company-id: cmp_01HXYZ..." \
-H "x-idempotency-key: bank-ref-ZB-20260623-00441" \
-H "Content-Type: application/json" \
-d '{
"amount": 500000,
"currency": "USD",
"userId": "usr_01HABC...",
"externalReference": "ZB-20260623-00441",
"userReference": "SELLER-001",
"isTransit": false
}'| Field | Type | Required | Notes |
|---|---|---|---|
| amount | integer (cents) | Yes | Min 1. $500.00 USD = 50000. |
| currency | USD | ZIG | Yes | Must match the user's account currency. |
| userId | UUID string | No | If provided, credits this user's wallet directly. |
| externalReference | string | No | Bank reference or other external ID — stored on the transaction. |
| userReference | string | No | Fallback lookup: matched against ledger entityId, then customReference. |
| isTransit | boolean | No | Default false. If true, credits the CLEARING account instead of BANK_COLLECTION. |
{
"id": "txn_01HDEP...",
"reference": "DEP-000441",
"status": "COMPLETED",
"amount": "500000",
"currency": "USD",
"externalReference": "ZB-20260623-00441",
"createdAt": "2026-06-23T09:10:00.000Z",
"entries": [
{
"accountType": "BANK_COLLECTION",
"direction": "DEBIT",
"amount": "500000"
},
{
"accountType": "USER_WALLET",
"direction": "CREDIT",
"amount": "500000",
"userId": "usr_01HABC..."
}
]
}How the user is matched
The API tries three strategies in order to find the wallet to credit. If none match, the deposit is recorded but lands in the UNALLOCATED system account.
Direct UUID lookup. Most reliable — use this when you know exactly which user to credit.
Matches the userReference string against the entityId on each user ledger. Useful when you store your own reference on the ledger.
Falls back to matching against the customReference field on the ledger. Use for bank account numbers or other stable identifiers.
If no user is found by any method, funds are credited to the system's UNALLOCATED account. The transaction's metadata.note is set to "Unallocated deposit assigned to UNALLOCATED account". Review and reallocate from your admin dashboard.
Transit deposits (isTransit: true)
Setting isTransit: true routes the credit to the CLEARING account instead of BANK_COLLECTION. This is used internally whenever the accept-payment flow funds an escrow — funds are deposited in transit first, then EscrowService.initiateEscrow moves them into the escrow GL.
If isTransit: true and the escrow initiation subsequently fails, the transit deposit is automatically reversed — no manual rollback needed.
Retrieve a transaction
Look up any transaction by its ID to confirm a deposit was applied correctly.
curl "https://api.switchlock.co.zw/v1/payments/transaction/txn_01HDEP..." \
-H "x-api-key: sl_live_a1b2c3d4e5f6..." \
-H "x-company-id: cmp_01HXYZ..."Transactions are scoped to your company — you cannot retrieve transactions belonging to other tenants even with a valid API key.