Data Dictionary

Centralized reference for all enumeration types, status values, and code tables used across the Payscribe platform.

---

Cards

Card status

Value	Description
active	Card is active and usable for transactions
frozen	Card is temporarily frozen. Can be unfrozen via API or dashboard.
inactive	Card is inactive (expired or manually deactivated)
terminated	Card is permanently terminated. Cannot be reactivated.

The terminate column (0/1) is the authoritative flag — when set to 1, the dashboard displays the card as terminated regardless of the status column value.

Card type

Value	Description
virtual	Digital card issued instantly, usable online
physical	Physical plastic card shipped to an address

Card brand

Value	Description
VISA	Visa network
MASTERCARD	Mastercard network

Card action

Value	Description
freeze	Temporarily block the card
unfreeze	Reactivate a frozen card
terminate	Permanently close the card

---

Wallet balances

Balance	Description
available_balance	Funds ready for transfers, card funding, bills
collection_balance	Unsettled VA collections (auto-swept on schedule)
due_balance	Outstanding amount owed
facility_balance	Credit facility line (used by facility-backed purchases such as airtime-facility)

---

Transactions

Transaction status

Value	Description
pending	Initial state, awaiting processing
processing	Being processed by the provider
success	Completed successfully
fail / failed	Failed
approved	Approved (alternate success state)
refund / refunded	Refunded
queued	Queued for processing
review	Under review / flagged

Payment method

Value	Description
wallet	Paid from internal wallet balance
bank_transfer	Paid via bank transfer
stablecoin	Paid with USDT/USDC
sandbox	Sandbox/test payment

Ref type

Value	Description
accounts	Virtual account operation
cards	Card operation
wallets	Wallet operation
invoices	Invoice payment
links	Payment link transaction
savings	Savings plan transaction

Settlement status

Value	Description
pending	Awaiting settlement
processing	Being settled
success	Settled successfully
fail	Settlement failed

---

Virtual accounts

Account type

Value	Description
static	Permanent account number, reusable for unlimited payments
dynamic	Single-use account with fixed amount and expiry

Bank provider

Provider	Bank name	Code
9psb	9 Payment Service Bank	120001
palmpay	PALMPAY	100033
safehaven	Safehaven MFB	090286
providus	Providus Bank	—

Settlement mode

Value	Description
collection	Funds settle to collection balance, swept to main wallet on schedule
wallet	Funds credit available balance immediately

---

Bills

Bill categories

Slug	Product ID	Category
airtime	2	Airtime (NG)
data	1	Data bundles (NG)
electricity / power	4	Electricity prepaid/postpaid
tv / cable	3	Cable TV
betting	19	Betting
internet	18	ISP/Internet data
education	—	Education ePins
gift_card	—	Gift cards
insurance	—	Insurance
transfer	22	P2P/Wallet transfer

Airtime providers

Provider
mtn
airtel
glo
9mobile

---

Webhooks

Webhook status

Value	Description
queue / queued	Waiting to be picked up by the worker
pending	Awaiting retry
sending	Currently being delivered
success	Delivered successfully
fail	Delivery failed (will retry if attempts remain)
dead	Max retries exhausted
blacklisted	Domain permanently blocked

Webhook event types

Event	Product	Description
accounts.payment.status	Collections	Inbound VA payment detected
accounts.simulation	Collections	Simulate transfer executed (live test path; not emitted by the sandbox simulate-transfer endpoint)
payouts.created	Transfers	Transfer initiated
bills.created	Bills	Bill payment request created
bills.status	Bills	Bill status updated
bills.updated	Bills	Bill delivery receipt updated
bills.batch.status	Bills	Batch bill status updated
cards.auth.approved	Cards	Card authorization approved
cards.auth.settled	Cards	Authorization captured/settled
cards.auth.declined	Cards	Authorization declined
cards.auth.verified	Cards	$1 verification auth approved
cards.auth.activation	Cards	Contactless card activated at POS
cards.adjusted.refund	Cards	Refund settled
cards.adjusted.crossborder	Cards	Cross-border transaction settled
cards.adjusted.terminated	Cards	Card terminated
cards.adjusted.{status}	Cards	Card status changed
payment_link.paid	Payment Links	Payment link paid
invoice.sent	Invoices	Invoice emailed
invoice.paid	Invoices	Invoice fully paid
invoice.partially_paid	Invoices	Partial payment received
invoice.overdue	Invoices	Invoice past due date
savings.plans.created	Savings	Savings plan created
savings.plans.paused	Savings	Plan paused/resumed/cancelled
issuing.created.successful	Issuing	Card created
stablecoin.deposit.settled	Stablecoin	Deposit settled and credited
stablecoin.card.created	Stablecoin	Card funded via stablecoin
stablecoin.card.topped_up	Stablecoin	Card topped up via stablecoin

---

Savings

Savings plan status

Value	Description
active	Plan is actively collecting contributions
paused	Contributions temporarily stopped
completed	Target reached or end date passed
cancelled	Plan cancelled before completion
failed	Could not collect contributions

Savings plan type

Value	Description
target	Goal-based savings (target amount)
fixed	Fixed deposit (locked for a period)
spend_save	Round-up / spend-and-save

Savings frequency

Value
daily
weekly
monthly

---

Invoices

Invoice status

Value	Description
draft	Draft, not yet sent
sent	Emailed to customer
paid	Fully paid
partially_paid	Partial payment received
overdue	Past due date
voided	Voided by merchant
cancelled	Cancelled
pending	Awaiting payment

---

Payment links

Link status

Value	Description
active	Link is active and can receive payments
inactive	Link is disabled
draft	Saved as draft

---

Businesses

Business KYC status

Value	Description
pending	Registration started, awaiting review
active	Approved and active
inactive	Rejected or deactivated
suspended	Temporarily suspended
blacklist	Blacklisted

Risk level

Value	Score range	Description
low	0–40	Low risk
medium	41–70	Medium risk
high	71–100	High risk

Onboarding step

Step	Stage
1	Business information
2	Director information
3	Document upload
4	Address verification
5	Identity verification
6	Biometric verification
7	Risk assessment
8	Approval

---

Customers

Customer KYC level

Level	Requirements
0	No KYC completed
1	Address proof provided (basic)
2	Address + identity proof (full KYC)
3	Enhanced KYC (additional verification)

Customer status

Value	Description
active	Customer is active
inactive	Customer is inactive/disabled

Customer document type

Value	Description
utility_bill	Utility bill (electricity, water, etc.)
bank_statement	Bank statement
government_correspondence	Government-issued correspondence

---

Stablecoin

Asset

Value	Description
USDT	Tether (USD-pegged)
USDC	USD Coin

Network

Value	Blockchain
BEP20	Binance Smart Chain
ERC20	Ethereum
TRC20	Tron

Stablecoin order action

Value	Description
create	Create a new card funded via stablecoin
topup	Top up an existing card via stablecoin

Stablecoin order status

Value	Description
pending	Awaiting blockchain confirmation
processing	Being processed
fulfilled	Completed
failed	Failed
expired	Confirmation window expired

---

Users

User status

Value	Description
active	Account active
inactive	Account inactive/disabled
suspended	Temporarily suspended

---

Currencies

Code	Type
NGN	Fiat — Nigerian Naira
USD	Fiat — US Dollar
GBP	Fiat — British Pound
EUR	Fiat — Euro
USDT	Stablecoin — Tether
USDC	Stablecoin — USD Coin

---

API keys

Status	Description
active	Key is active and can authenticate requests
revoked	Key has been revoked
blocked	Key has been blocked

---

Fraud

Fraud flag status

Value	Description
open	Flag raised, not yet reviewed
reviewed	Flag has been reviewed
dismissed	Flag dismissed as non-fraudulent
actioned	Action taken based on flag

Fraud severity

Value	Description
low	Low severity
medium	Medium severity
high	High severity
critical	Critical severity

---

Remittance

Remittance status

Value	Description
pending	Awaiting processing
pending_mlro	Awaiting Money Laundering Reporting Officer review
processing	Being processed
completed	Completed successfully
failed	Failed
cancelled	Cancelled

---

Referrals

Referral status

Value	Description
active	Referral tracked, awaiting reward
rewarded	Reward paid

Referral milestone types

Value	Scope
signup	Individual
first_topup	Individual
first_bill	Individual
first_card_txn	Individual
first_transfer	Individual
first_virtual_account	Individual
first_fx	Individual
b2b_signup	Business
b2b_kyb_completed	Business
b2b_first_transaction	Business
p2p_receive	Individual

---

Webhook retry schedule

Attempt	Delay
1	30 seconds
2	60 seconds
3	120 seconds
4	240 seconds
5	480 seconds (8 minutes)

Max retries: 6 (configurable in dashboard) Final state after exhaustion: dead Stuck timeout: 5 minutes (webhooks stuck in sending state are reset) Alert threshold: 5 failures/hour (configurable)