Developer onboarding

Sandbox-first setup · About 15 minutes

Start building with Payscribe

Set up a secure sandbox connection, make one useful API request, and follow a complete money-movement workflow from start to finish.

Make your first requestChoose a workflow →

01Get accessCreate an account and use sandbox first.

→

02Connect securelyKeep your API key on your server.

→

03Build one flowConfirm the final result with a webhook.

→

04Go liveComplete the production-readiness checks.

Before you begin

You need a Payscribe account, access to the dashboard, and a server-side environment where you can keep an API key. Sandbox requests use test data and do not move real money.

Keep API keys off the client

API keys authorize business API requests. Never put one in browser JavaScript, a mobile app, a client-side bundle, a screenshot, or source control.

1. Get sandbox access

Create an account, then complete the dashboard onboarding steps. When access is ready, open Settings → API Keys and create or copy a sandbox API key.

Credential	Typical prefix	Where it belongs	Purpose
Sandbox API key	ps_pk_test_...	Server environment	Authenticates sandbox API requests
Production API key	ps_pk_live_...	Production server environment	Authenticates live API requests
Webhook secret	ps_test_... / ps_live_...	Server environment	Verifies webhook signatures; it does not authenticate API requests

Set the sandbox key in the environment used by your server. This example uses PAYSCRIBE_API_KEY:

PAYSCRIBE_API_KEY=ps_pk_test_your_api_key

Do not commit credentials to a .env file or repository. Rotate a key immediately if it is exposed. See Authentication for request headers and production guidance.

2. Make your first sandbox request

Retrieve wallet balances to verify that your sandbox URL and authorization header are correct. Replace the placeholder—or set the environment variable—with your own sandbox API key.

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}`},
});

if (!response.ok) throw new Error(`Payscribe request failed: ${response.status}`);
const result = await response.json();
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"
)

type balanceResponse struct {
  Status  bool `json:"status"`
  Message struct {
    Details []struct {
      Currency string `json:"currency"`
      AvailableBalance float64 `json:"available_balance"`
    } `json:"details"`
  } `json:"message"`
}

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 balanceResponse
  if err := json.NewDecoder(response.Body).Decode(&result); err != nil { log.Fatal(err) }
  fmt.Println(result.Message.Details)
}

Know that it worked

You should receive a 200 response with "status": true and a message.details array. Your wallet values will differ from this example.

{
  "status": true,
  "description": "Account balance fetched successfully.",
  "message": {
    "details": [
      {
        "currency": "NGN",
        "available_balance": 2450000.0
      }
    ]
  },
  "status_code": 200
}

Expected resultYour request returns 200 with wallet data. You are ready to build a workflow.

If it failsConfirm that the URL is sandbox and the key begins with ps_pk_test_..., then check Authentication and Common errors.

Test a live sandbox response

Use the console below to send a real, read-only request to the sandbox and inspect its response. It accepts only a dashboard-issued sandbox key (ps_pk_test_...), never a live key.

Sandbox API consoleSelect an endpointGET /my-account/profileGET /my-account/balancesGET /payouts/bank/list

Sandbox API key

Sandbox keys only. Your key is held only in this browser tab and sent directly to the sandbox API; it is never stored or sent to the documentation site.

GET https://sandbox.payscribe.ng/api/v1/my-account/profile
Authorization: Bearer ps_pk_test_...

Select a read-only endpoint, enter your sandbox key, and inspect the real sandbox response.

Keep live credentials out

The console holds the sandbox key only in the current browser tab and sends it directly to the sandbox API. It does not persist the key or send it to the documentation site. Do not use a production key, and do not use this pattern in your own browser or mobile application.

Handle errors deliberately

Do not treat every non-200 response as a generic failure. Read the status code, log the request reference without logging credentials, and choose the next action deliberately.

Example validation error

{
  "status": false,
  "description": "Validation failed",
  "status_code": 422
}

Response	Your integration should do	Do not do
400 or 422	Show an actionable validation message and let the user correct input.	Retry unchanged input repeatedly.
401 or 403	Stop the request and check credentials or permissions securely.	Expose the key or raw authorization header in logs.
429	Back off with jitter and retry later.	Send parallel retries.
5xx or timeout after a write	Keep the same ref, then reconcile the operation before retrying.	Create a new reference and risk a duplicate operation.

See Errors, Common errors, and Idempotency and duplicate handling for the full recovery guidance.

3. Choose your workflow

Build a complete workflow rather than stitching together endpoints in isolation. Each recommended starting point includes the API calls, expected outcome, and the webhook you need to confirm final status.

CollectionsReceive a paymentCreate a customer and virtual account, simulate an inbound payment, then verify the webhook.Start collection flow →PayoutsSend moneyValidate a recipient, create a transfer, track its outcome, and handle failures safely.Start payout flow →CardsIssue a cardCreate a customer, issue and fund a card, then inspect card activity.Start card flow →

4. Verify webhooks before going live

An API response tells you Payscribe accepted a request. A webhook tells your system when an asynchronous action—such as an incoming payment or completed payout—reaches its final state.

Before production, make sure your application can:

• Receive the relevant events at a publicly reachable HTTPS endpoint.
• Verify the webhook signature using the raw request body.
• Return a successful response quickly, then process the event asynchronously.
• Safely handle duplicate deliveries.

Follow the Webhooks guide, then exercise the full flow in Sandbox testing.

Integration progress

Your launch checklist

0 of 5 complete

1. ✓Create your Payscribe account
2. ✓Store a sandbox API key on your server
3. ✓Make a successful sandbox balance request
4. ✓Choose and complete one product workflow
5. ✓Verify a webhook before going live

Progress is saved only in this browser.

Need a hand?

Detailed first requestUse the expanded Quickstart for response handling and more context.AuthenticationCheck headers, credentials, and secure key handling.Resolve an errorUnderstand common API responses and what to do next.Ready for production?Complete the go-live checklist before processing real money.