Quickstart

Make your first authenticated Payscribe sandbox request in about 10 minutes. You will retrieve your wallet balances, verify the response, and choose a complete flow to build next.

By the endYour server can call the Payscribe sandbox with an API key and read a real API response.

Before you begin

You need a Payscribe account and a sandbox API key from Settings → API Keys in the dashboard. Sandbox requests use test data and do not move real money.

Keep the key server-side

Use a ps_pk_test_... key for sandbox development. Do not add it to browser JavaScript, a mobile app, a client-side bundle, screenshots, or source control.

1. Set a local environment variable

Use a name your application can read. These examples use PAYSCRIBE_API_KEY.

macOS / Linux

export PAYSCRIBE_API_KEY="ps_pk_test_your_api_key"

PowerShell

$env:PAYSCRIBE_API_KEY = "ps_pk_test_your_api_key"

For a deployed application, set the variable in your hosting provider or server configuration—not in your codebase. See Authentication for secure key-handling guidance.

2. Retrieve your sandbox balances

Copy the example for your server environment. It calls the sandbox URL and passes the API key in the Authorization header.

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', {
  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}): ${result?.description ?? 'Unknown error'}`);
}

console.log(result.message.details);

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()['message']['details'])

Go

package main

import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
  "os"
)

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

  response, err := http.DefaultClient.Do(request)
  if err != nil { log.Fatal(err) }
  defer response.Body.Close()
  if response.StatusCode < 200 || response.StatusCode > 299 {
    log.Fatalf("Payscribe request failed: %s", response.Status)
  }

  var result map[string]any
  if err := json.NewDecoder(response.Body).Decode(&result); err != nil { log.Fatal(err) }
  message, _ := result["message"].(map[string]any)
  fmt.Println(message["details"])
}

3. Verify the result

You should receive 200 OK, "status": true, and a message.details array with one entry per wallet. Your wallet ID and balances will differ.

{
  "status": true,
  "description": "Account balance fetched successfully.",
  "message": {
    "details": [
      {
        "id": "wlt_abc123",
        "currency": "NGN",
        "available_balance": 2450000,
        "collection": 2500000,
        "ledger": 2450000
      }
    ]
  },
  "status_code": 200
}

Success checkIf you can see a wallet currency and available_balance, your sandbox connection is working.

If the request fails

The API returns JSON errors with a status code and description. Treat the code as the recovery signal; do not display raw error payloads or credentials to your end users.

Example error response

{
  "status": false,
  "description": "Invalid API key",
  "status_code": 401
}

What you see	Check this first	Next action
401 or 403	The key prefix and authorization header	Use a valid ps_pk_test_... key; keep it server-side.
404	The base URL and endpoint path	Use https://sandbox.payscribe.ng/api/v1 and the documented route.
400 or 422	Required fields and formats	Correct the request; do not retry unchanged input.
Timeout or 5xx on a write request	Your request ref and transaction state	Keep the same ref, then reconcile before retrying.

Read Common errors, Errors, and Idempotency before implementing money-moving requests.

4. Build one complete flow

Your connection works. Now build a workflow that includes its API calls, expected state changes, and webhook confirmation.

CollectionsReceive a paymentCreate a customer and virtual account, simulate payment, then confirm it from a webhook.Build the recipe →PayoutsSend moneyValidate a recipient, send a payout, track status, and recover safely from failures.Build a payout flow →CardsIssue your first cardCreate a customer, issue and fund a card, then inspect its activity.Build the recipe →

Before production

Test webhooks, duplicate handling, validation failures, and production configuration before moving real funds. Continue with Sandbox testing, Webhooks, and the go-live checklist.