Customers API

Create, verify, and manage customers on your Payscribe account.

Create Customer (Basic)

Create a new customer on your integration with basic details.

POST /customers/create

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.
Content-Type	string	Yes	Must be set to `application/json`.

Body Parameters

Parameter	Type	Required	Description
first_name	string	Yes	Customer's first name.
last_name	string	Yes	Customer's last name.
email	string	Yes	Customer's email address.
phone	string	Yes	Customer's phone number.

Request

cURL
Node.js
Python
Go

curl -X POST https://sandbox.payscribe.ng/api/v1/customers/create \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "2348012345678"
  }'

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/create', {
  method: 'POST',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "2348012345678"
}),
});

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

import os
import requests
import json

payload = json.loads(r'''{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "2348012345678"
}''')

response = requests.post(
    'https://sandbox.payscribe.ng/api/v1/customers/create',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}", 'Content-Type': 'application/json'},
    json=payload,
    timeout=20,
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
  body := strings.NewReader(`{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "2348012345678"
}`)
  request, err := http.NewRequest(http.MethodPost, "https://sandbox.payscribe.ng/api/v1/customers/create", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))
  request.Header.Set("Content-Type", "application/json")

  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))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Customer created successfully.",
  "message": {"details": {
    "customer_id": "cus_xyz789",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "2348012345678",
    "country": "NG",
    "tier": 0,
    "created_at": "2026-08-28 12:00:00"
  }},
  "status_code": 200
}

Add Customer Profile and Address

Add the customer's date of birth, address, and identification details. The address must be a JSON object; this endpoint supports both POST and PATCH.

PATCH /customers/create/tier1

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.
Content-Type	string	Yes	Must be set to `application/json`.

Body Parameters

Parameter	Type	Required	Description
customer_id	string	Yes	The ID of the customer to update.
dob	string	Yes	Date of birth in `YYYY-MM-DD` format.
address	object	Yes	Address object with `street`, `city`, `state`, `country`, and `postal_code`.
identification_type	string	Yes	Identification type, for example `bvn` or `nin`.
identification_number	string	Yes	Identification number.
photo	string	No	Identity-document image URL or encoded value.

Request

cURL
Node.js
Python
Go

curl -X PATCH https://sandbox.payscribe.ng/api/v1/customers/create/tier1 \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "dob": "1990-01-15",
    "address": {"street": "12 Broad Street", "city": "Lagos", "state": "Lagos", "country": "NG", "postal_code": "100001"},
    "identification_type": "bvn",
    "identification_number": "12345678901"
  }'

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/create/tier1', {
  method: 'PATCH',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({
  customer_id: 'cus_xyz789', dob: '1990-01-15', identification_type: 'bvn', identification_number: '12345678901',
  address: {street: '12 Broad Street', city: 'Lagos', state: 'Lagos', country: 'NG', postal_code: '100001'},
}),
});

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

import os
import requests
import json

payload = {
    'customer_id': 'cus_xyz789', 'dob': '1990-01-15', 'identification_type': 'bvn', 'identification_number': '12345678901',
    'address': {'street': '12 Broad Street', 'city': 'Lagos', 'state': 'Lagos', 'country': 'NG', 'postal_code': '100001'},
}

response = requests.patch(
    'https://sandbox.payscribe.ng/api/v1/customers/create/tier1',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}", 'Content-Type': 'application/json'},
    json=payload,
    timeout=20,
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
  body := strings.NewReader(`{
  "customer_id": "cus_xyz789",
  "dob": "1990-01-15",
  "address": {"street": "12 Broad Street", "city": "Lagos", "state": "Lagos", "country": "NG", "postal_code": "100001"},
  "identification_type": "bvn",
  "identification_number": "12345678901"
}`)
  request, err := http.NewRequest(http.MethodPatch, "https://sandbox.payscribe.ng/api/v1/customers/create/tier1", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))
  request.Header.Set("Content-Type", "application/json")

  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))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Customer details updated successfully.",
  "message": {"details": {"customer_id": "cus_xyz789"}},
  "status_code": 200
}

Add Customer Identity Document

Add an identity document to an existing customer. The identity value must be a JSON object; this endpoint supports both POST and PATCH.

PATCH /customers/create/tier2

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.
Content-Type	string	Yes	Must be set to `application/json`.

Body Parameters

Parameter	Type	Required	Description
customer_id	string	Yes	The ID of the customer to update.
identity	object	Yes	Identity object with `type`, `number`, and `image`; `country` defaults to `NG`.

Request

cURL
Node.js
Python
Go

curl -X PATCH https://sandbox.payscribe.ng/api/v1/customers/create/tier2 \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "identity": {"type": "nin", "number": "12345678901", "image": "https://example.com/identity-document.jpg", "country": "NG"}
  }'

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/create/tier2', {
  method: 'PATCH',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({
  customer_id: 'cus_xyz789',
  identity: {type: 'nin', number: '12345678901', image: 'https://example.com/identity-document.jpg', country: 'NG'},
}),
});

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

import os
import requests
import json

payload = {
    'customer_id': 'cus_xyz789',
    'identity': {'type': 'nin', 'number': '12345678901', 'image': 'https://example.com/identity-document.jpg', 'country': 'NG'},
}

response = requests.patch(
    'https://sandbox.payscribe.ng/api/v1/customers/create/tier2',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}", 'Content-Type': 'application/json'},
    json=payload,
    timeout=20,
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
  body := strings.NewReader(`{
  "customer_id": "cus_xyz789",
  "identity": {"type": "nin", "number": "12345678901", "image": "https://example.com/identity-document.jpg", "country": "NG"}
}`)
  request, err := http.NewRequest(http.MethodPatch, "https://sandbox.payscribe.ng/api/v1/customers/create/tier2", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))
  request.Header.Set("Content-Type", "application/json")

  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))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Customer details updated successfully.",
  "message": {"details": {"customer_id": "cus_xyz789"}},
  "status_code": 200
}

Create Customer (Full)

Create and fully onboard a customer in one call with all KYC details.

POST /customers/create/full

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.
Content-Type	string	Yes	Must be set to `application/json`.

Body Parameters

Parameter	Type	Required	Description
first_name	string	Yes	Customer's first name.
last_name	string	Yes	Customer's last name.
email	string	Yes	Customer's email address.
phone	string	Yes	Customer's phone number.
country	string	Yes	Two-letter customer country code, for example `NG`.
dob	string	Yes	Date of birth in `YYYY-MM-DD` format.
address	object	Yes	Address object with `street`, `city`, `state`, `country`, and `postal_code`.
identification_type	string	Yes	Identification type, for example `nin`.
identification_number	string	Yes	Identification number.
identity	object	Yes	Identity object with `type`, `number`, and document `image`.

Request

cURL
Node.js
Python
Go

curl -X POST https://sandbox.payscribe.ng/api/v1/customers/create/full \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "2348012345678",
    "country": "NG",
    "dob": "1990-01-15",
    "address": {"street": "12 Broad Street", "city": "Lagos", "state": "Lagos", "country": "NG", "postal_code": "100001"},
    "identification_type": "nin",
    "identification_number": "12345678901",
    "identity": {"type": "nin", "number": "12345678901", "image": "https://example.com/identity-document.jpg", "country": "NG"}
  }'

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/create/full', {
  method: 'POST',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "2348012345678",
  "country": "NG", "dob": "1990-01-15",
  "address": {street: '12 Broad Street', city: 'Lagos', state: 'Lagos', country: 'NG', postal_code: '100001'},
  "identification_type": "nin", "identification_number": "12345678901",
  "identity": {type: 'nin', number: '12345678901', image: 'https://example.com/identity-document.jpg', country: 'NG'},
}),
});

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

import os
import requests
import json

payload = json.loads(r'''{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "2348012345678",
  "country": "NG",
  "dob": "1990-01-15",
  "address": {"street": "12 Broad Street", "city": "Lagos", "state": "Lagos", "country": "NG", "postal_code": "100001"},
  "identification_type": "nin",
  "identification_number": "12345678901",
  "identity": {"type": "nin", "number": "12345678901", "image": "https://example.com/identity-document.jpg", "country": "NG"}
}''')

response = requests.post(
    'https://sandbox.payscribe.ng/api/v1/customers/create/full',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}", 'Content-Type': 'application/json'},
    json=payload,
    timeout=20,
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
  body := strings.NewReader(`{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "2348012345678",
  "country": "NG",
  "dob": "1990-01-15",
  "address": {"street": "12 Broad Street", "city": "Lagos", "state": "Lagos", "country": "NG", "postal_code": "100001"},
  "identification_type": "nin",
  "identification_number": "12345678901",
  "identity": {"type": "nin", "number": "12345678901", "image": "https://example.com/identity-document.jpg", "country": "NG"}
}`)
  request, err := http.NewRequest(http.MethodPost, "https://sandbox.payscribe.ng/api/v1/customers/create/full", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))
  request.Header.Set("Content-Type", "application/json")

  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))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Customer created successfully.",
  "message": {"details": {
    "customer_id": "cus_xyz789",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "2348012345678",
    "country": "NG",
    "tier": 2,
    "created_at": "2026-08-28 12:00:00"
  }},
  "status_code": 200
}

Get Customer Details

Retrieve the details of an existing customer.

GET /customers/{id}/details

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the customer to retrieve.

Request

cURL
Node.js
Python
Go

curl -X GET https://sandbox.payscribe.ng/api/v1/customers/cus_xyz789/details \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY"

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/cus_xyz789/details', {
  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);

import os
import requests

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

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/customers/cus_xyz789/details", 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))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Customer details fetched.",
  "message": {
    "details": {
      "customer_id": "cus_xyz789",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "2348012345678",
      "email": "john@example.com",
      "dob": "1990-01-15",
      "identification_number": "12345678901",
      "identity": {"type": "nin", "number": "12345678901", "image": "https://example.com/identity-document.jpg", "country": "NG"},
      "address": {"street": "12 Broad Street", "city": "Lagos", "state": "Lagos", "country": "NG", "postal_code": "100001"},
      "access": {
        "can_create_card": true,
        "can_create_account": true,
        "can_save": true
      },
      "accounts": [
        {
          "account": "1234567890",
          "currency": "NGN",
          "bank": "9 Payment Service Bank",
          "account_type": "static",
          "created_at": "2025-06-20 10:30:00",
          "status": "active"
        }
      ],
      "country": "NG",
      "status": "active",
      "created_at": "2025-06-20 10:30:00",
      "updated_at": "2025-06-20 11:15:00"
    }
  },
  "status_code": 200
}

There is no id, customer_code, tier, identified, bvn, id_type/id_number, total_transactions, or total_transaction_value field on this endpoint. access reflects what the customer is currently eligible for based on whether they have an address and identity on file and an active status; accounts lists their virtual accounts, if any.

Lookup Customer by Email or Phone

Look up a customer's details using their email address or phone number in the username field.

POST /customers/details

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.
Content-Type	string	Yes	Must be set to `application/json`.

Body Parameters

Parameter	Type	Required	Description
username	string	Yes	Customer's email address or phone number.

Request

cURL
Node.js
Python
Go

curl -X POST https://sandbox.payscribe.ng/api/v1/customers/details \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john@example.com"
  }'

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/details', {
  method: 'POST',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({
  username: 'john@example.com'
}),
});

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

import os
import requests
import json

payload = {'username': 'john@example.com'}

response = requests.post(
    'https://sandbox.payscribe.ng/api/v1/customers/details',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}", 'Content-Type': 'application/json'},
    json=payload,
    timeout=20,
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
  body := strings.NewReader(`{
  "username": "john@example.com"
}`)
  request, err := http.NewRequest(http.MethodPost, "https://sandbox.payscribe.ng/api/v1/customers/details", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))
  request.Header.Set("Content-Type", "application/json")

  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))
}

Known issue

Calling this endpoint currently returns 400 The source field is required. regardless of a valid payload — a server-side defect, not a documentation error. Use Get Customer Details (GET /customers/{id}/details) until this is fixed.

Response

Status: 200 OK

This endpoint shares its implementation with Get Customer Details, so once the known issue above is resolved it returns the same shape:

{
  "status": true,
  "description": "Customer details fetched.",
  "message": {
    "details": {
      "customer_id": "cus_xyz789",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "2348012345678",
      "email": "john@example.com",
      "dob": "1990-01-15",
      "identification_number": "12345678901",
      "identity": {"type": "nin", "number": "12345678901", "image": "https://example.com/identity-document.jpg", "country": "NG"},
      "address": {"street": "12 Broad Street", "city": "Lagos", "state": "Lagos", "country": "NG", "postal_code": "100001"},
      "access": {
        "can_create_card": true,
        "can_create_account": true,
        "can_save": true
      },
      "accounts": [],
      "country": "NG",
      "status": "active",
      "created_at": "2025-06-20 10:30:00",
      "updated_at": "2025-06-20 11:15:00"
    }
  },
  "status_code": 200
}

Blacklist Customer

Blacklist a customer to restrict their activities on your integration.

POST /customers/blacklist

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.
Content-Type	string	Yes	Must be set to `application/json`.

Body Parameters

Parameter	Type	Required	Description
customer_id	string	Yes	The ID of the customer to update.
blacklist	integer	Yes	Use `1` to blacklist or `0` to reactivate the customer.

Request

cURL
Node.js
Python
Go

curl -X POST https://sandbox.payscribe.ng/api/v1/customers/blacklist \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "blacklist": 1
  }'

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/blacklist', {
  method: 'POST',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({
  customer_id: 'cus_xyz789',
  blacklist: 1,
}),
});

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

import os
import requests
import json

payload = {'customer_id': 'cus_xyz789', 'blacklist': 1}

response = requests.post(
    'https://sandbox.payscribe.ng/api/v1/customers/blacklist',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}", 'Content-Type': 'application/json'},
    json=payload,
    timeout=20,
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
  body := strings.NewReader(`{
  "customer_id": "cus_xyz789",
  "blacklist": 1
}`)
  request, err := http.NewRequest(http.MethodPost, "https://sandbox.payscribe.ng/api/v1/customers/blacklist", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))
  request.Header.Set("Content-Type", "application/json")

  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))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Customer details updated successfully.",
  "message": {"details": {"customer_id": "cus_xyz789"}},
  "status_code": 200
}

Get Customer Transactions

Retrieve all transactions for a specific customer.

POST /customers/{id}/transactions

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The ID of the customer.

Body Parameters

Parameter	Type	Required	Description
start_date	string	Yes	Start date in `YYYY-MM-DD`; must be in the same month as `end_date`.
end_date	string	Yes	End date in `YYYY-MM-DD`.
page	integer	Yes	Page number, for example `1`.
page_size	integer	Yes	Number of records per page, for example `20`.

Request

cURL
Node.js
Python
Go

curl -X POST https://sandbox.payscribe.ng/api/v1/customers/cus_xyz789/transactions \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start_date":"2026-08-01","end_date":"2026-08-28","page":1,"page_size":20}'

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/cus_xyz789/transactions', {
  method: 'POST',
  headers: {Authorization: `Bearer ${process.env.PAYSCRIBE_API_KEY}`, 'Content-Type': 'application/json'},
  body: JSON.stringify({start_date: '2026-08-01', end_date: '2026-08-28', page: 1, page_size: 20}),
});

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

import os
import requests

response = requests.post(
    'https://sandbox.payscribe.ng/api/v1/customers/cus_xyz789/transactions',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}"},
    json={'start_date': '2026-08-01', 'end_date': '2026-08-28', 'page': 1, 'page_size': 20},
    timeout=20,
)
response.raise_for_status()
print(response.json())

package main

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

func main() {
  body := strings.NewReader(`{"start_date":"2026-08-01","end_date":"2026-08-28","page":1,"page_size":20}`)
  request, err := http.NewRequest(http.MethodPost, "https://sandbox.payscribe.ng/api/v1/customers/cus_xyz789/transactions", body)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer "+os.Getenv("PAYSCRIBE_API_KEY"))
  request.Header.Set("Content-Type", "application/json")

  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))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Customer transactions fetched.",
  "message": {
    "details": {
      "transactions": [
        {
          "trans_id": "TXN-2026080101",
          "ref": "ref_abc123",
          "amount": 5000,
          "fee": 50,
          "currency": "NGN",
          "description": "Card top-up",
          "service": "CARDS",
          "service_id": "card_abc123",
          "created_at": "2026-08-01 10:00:00",
          "status": "success"
        }
      ],
      "total": 1,
      "page": 1,
      "page_size": 20
    }
  },
  "status_code": 200
}

The row array is transactions, not data, and a total count is included alongside page/page_size.

List All Customers

Retrieve a paginated list of all customers on your integration.

GET /customers/

Headers

Parameter	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number to retrieve. Defaults to `1`.
page_size	integer	No	Number of records per page. Defaults to `10`.

Request

cURL
Node.js
Python
Go

curl -X GET "https://sandbox.payscribe.ng/api/v1/customers/?page=1&page_size=10" \
  -H "Authorization: Bearer $PAYSCRIBE_API_KEY"

const response = await fetch('https://sandbox.payscribe.ng/api/v1/customers/?page=1&page_size=10', {
  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);

import os
import requests

response = requests.get(
    'https://sandbox.payscribe.ng/api/v1/customers/?page=1&page_size=10',
    headers={'Authorization': f"Bearer {os.environ['PAYSCRIBE_API_KEY']}"},
    timeout=20,
)
response.raise_for_status()
print(response.json())

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/customers/?page=1&page_size=10", 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))
}

Response

Status: 200 OK

{
  "status": true,
  "description": "Customers Fetched successfully.",
  "message": {
    "details": {
      "customers": [
        {
          "customer_id": "cus_xyz789",
          "name": "John Doe",
          "email": "john@example.com",
          "status": "active"
        },
        {
          "customer_id": "cus_abc456",
          "name": "Jane Smith",
          "email": "jane@example.com",
          "status": "active"
        }
      ],
      "total": 2,
      "page": 1,
      "page_size": 10
    }
  },
  "status_code": 200
}

The list is nested at message.details.customers, alongside total/page/page_size in the same object — there is no top-level meta key. Each row is {customer_id, name, email, status} only — name is not split into first_name/last_name, and there is no id, customer_code, phone, tier, identified, or created_at on this endpoint (use Get Customer Details for those).

Webhooks

Event	Description
`customers.created`	A new customer was created on your integration.
`customers.update`	An existing customer's details were updated.

See Webhooks for payload format and signature verification.

Was this page helpful?

Report a docs issue →

Create Customer (Basic)​

Headers​

Body Parameters​

Request​

Response​

Add Customer Profile and Address​

Headers​

Body Parameters​

Request​

Response​

Add Customer Identity Document​

Headers​

Body Parameters​

Request​

Response​

Create Customer (Full)​

Headers​

Body Parameters​

Request​

Response​

Get Customer Details​

Headers​

Path Parameters​

Request​

Response​

Lookup Customer by Email or Phone​

Headers​

Body Parameters​

Request​

Response​

Blacklist Customer​

Headers​

Body Parameters​

Request​

Response​

Get Customer Transactions​

Headers​

Path Parameters​

Body Parameters​

Request​

Response​

List All Customers​

Headers​

Query Parameters​

Request​

Response​

Webhooks​

Create Customer (Basic)

Headers

Body Parameters

Request

Response

Add Customer Profile and Address

Headers

Body Parameters

Request

Response

Add Customer Identity Document

Headers

Body Parameters

Request

Response

Create Customer (Full)

Headers

Body Parameters

Request

Response

Get Customer Details

Headers

Path Parameters

Request

Response

Lookup Customer by Email or Phone

Headers

Body Parameters

Request

Response

Blacklist Customer

Headers

Body Parameters

Request

Response

Get Customer Transactions

Headers

Path Parameters

Body Parameters

Request

Response

List All Customers

Headers

Query Parameters

Request

Response

Webhooks