SamaPay | Shared Ledger & Disbursement Hub

SamaPay allows merchants to disburse funds directly from their balance to any active Wave mobile number or supported bank account through our high-concurrency Payout API.

Payout Overview

Use payouts to handle:

Payroll: Disburse salaries directly to employee Wave accounts.
Vendor Payments: Instantly pay suppliers for goods received.
Micro-lending: Distribute loan amounts to borrowers' mobile wallets.
Refunds: Return funds to customers without manual intervention.

Create a Payout

Create a payout from your merchant balance.

Endpoint

POST /api/payouts

Parameters

mobilestringRequired

The full MSISDN mobile number of the recipient (e.g., +2207771234).

amountnumberRequired

The absolute amount to disburse. Must be less than or equal to your current balance.

currencystringDefault: GMD

Supported values: GMD.

descriptionstring

Internal reference description for your merchant records.

Header

x-api-key: Your merchant secret API key.

Sample Request

curl -X POST https://api.samapay.techhive.gm/api/payouts \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250,
    "mobile": "+2207123456",
    "description": "Weekly Salary: Modou Bah"
  }'

Shield (Fraud Prevention)

Every payout is analyzed by SamaPay Shield.

Velocity Checks: Payouts are limited to 50 requests per hour for established merchants.
Value Limits: Individual payouts above 50,000 GMD are automatically flagged for manual review and will return a FLAG status.
New Merchant Safeguards: New accounts are restricted to 10 payouts per 24 hours for the first 3 days.

Insufficient funds in your merchant balance will result in a 400 Bad Request error. Ensure your balance is topped up via customer checkouts before attempting disbursements.

Error Responses

Status Code	Meaning
`400`	Insufficient funds or invalid mobile format.
`401`	Unauthorized (Invalid or missing API key).
`403`	Shield Block: High-risk transaction detected.
`500`	Internal server connectivity error.