Wallet funding

Fund a business wallet before using products that debit it, such as payouts, cards, and bills.

Engineering flowBuild, verify, then reconcile

Test this flow in sandbox →

1. 01Choose funding pathUse the intended bank-transfer or stablecoin deposit path.
2. 02Send fundsUse the exact account or network returned for that wallet.
3. 03Receive settlementWait for the confirmed collection or deposit event.
4. 04Check walletReconcile the resulting wallet balance before spending.

Use a dashboard-issued sandbox API key on your server. Do not enter credentials into this documentation site.

Funding paths

Path	Use it for	Confirm with
Bank transfer	Naira wallet funding	Verified collection event and wallet balance
Stablecoin deposit	Supported on-chain funding	Confirmed deposit/settlement event and wallet balance

Never treat a customer transfer screen or blockchain broadcast as final funding. Reconcile the credited wallet amount through signed events and the wallet record.

Check balances

A newly created Sandbox business can return 404 with Wallet balances not generated for this business yet. This means wallet provisioning or the selected funding path is not available for that business yet; it is not a zero balance. Handle the response as a setup state and do not attempt a debit until the balances endpoint returns a wallet record.

{
  "status": false,
  "description": "Wallet balances not generated for this business yet.",
  "status_code": 404
}

cURL

curl https://sandbox.payscribe.ng/api/v1/my-account/balances \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY"

Node.js

const response = await fetch('https://sandbox.payscribe.ng/api/v1/my-account/balances', {
  method: 'GET',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`},
});

const result = await response.json().catch(() => null);
if (!response.ok) throw new Error(`Payscribe request failed: ${response.status}`);
console.log(result);

Python

import os
import requests

response = requests.get(
    'https://sandbox.payscribe.ng/api/v1/my-account/balances',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}"},
    timeout=20,
)
response.raise_for_status()
print(response.json())

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "os"
)

func main() {
  var body io.Reader
  request, err := http.NewRequest(http.MethodGet, "https://sandbox.payscribe.ng/api/v1/my-account/balances", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()
  responseBody, _ := io.ReadAll(response.Body)
  if response.StatusCode < 200 || response.StatusCode > 299 { panic(fmt.Sprintf("Payscribe request failed: %s", response.Status)) }
  fmt.Println(string(responseBody))
}

For the wallet response and account-history endpoints, see My Account. For deposit-address creation and stablecoin settlement, see Stablecoin & Crypto and the Stablecoin API reference.