Wallet SDK Models

Reference for models returned by the Wallet SDK across iOS, Android, and React Native.

All monetary amounts are decimal strings such as "25.00" and "0.50" to avoid floating-point rounding. Dates are ISO 8601 strings. IDs are UUIDs.

WalletUser

Returned inside every wallet handle after login, onboarding, or session restore.

FieldTypeRequiredDescription
idstringYesWallet user UUID
mobilestringNoSaudi mobile number
firstNamestringNoFirst name
lastNamestringNoLast name
emailstringNoEmail address
nationalIdstringNoSaudi national ID
fullNameArstringNoFull name in Arabic from Nafath
dateOfBirthstringNoISO 8601 date
identityVerifiedAtstringNoISO 8601 timestamp of Nafath verification

WalletBalance

Returned by getBalance() and embedded in TransferResult, TopUpResult, and WalletCardSpendResult.

FieldTypeRequiredDescription
totalBalancestringYesTotal wallet balance
availableBalancestringYesSpendable balance after holds
holdBalancestringYesAmount on hold

WalletTransaction

A single ledger entry returned inside WalletTransactions.entries.

FieldTypeRequiredDescription
idstringYesTransaction UUID
journalReferencestringYesLedger journal reference
transactionTypestringNoTransaction type label
amountstringYesDecimal amount
direction"Debit" or "Credit"YesMoney direction from the wallet owner's view
descriptionstringNoHuman-readable note
createdAtstringNoISO 8601 timestamp
channelstringNoCARD, SARIE, ONLINE, or absent

WalletTransactions

Paginated wrapper returned by getTransactions() and beneficiaryTransfers().

FieldTypeRequiredDescription
entriesWalletTransaction[]YesPage of transactions
totalnumberYesTotal matching transactions
pagenumberYesCurrent 1-based page
limitnumberYesPage size

Beneficiary

A saved transfer recipient returned by listBeneficiaries(), addBeneficiary(), and verifyBeneficiary().

FieldTypeRequiredDescription
idstringYesBeneficiary UUID
beneficiaryUserIdstringYesRecipient wallet user UUID
mobilestringYesRecipient mobile number
displayNamestringNoRecipient profile name
nicknamestringNoCustom label set by caller
createdAtstringNoISO 8601 timestamp
accountNumberstringNoWallet account number
relationstringNoRelationship label
verificationRequiredbooleanNotrue when OTP was sent after addBeneficiary()
verificationExpiresInnumberNoSeconds until verification code expires

TransferResult

Returned by transfer().

FieldTypeRequiredDescription
transferIdstringYesTransfer UUID
statusstringYesTransfer status, such as COMPLETED
amountstringYesDecimal amount transferred
beneficiaryIdstringYesRecipient UUID
balanceWalletBalanceYesUpdated wallet balance

TopUpResult

Returned by topUp().

FieldTypeRequiredDescription
topUpIdstringYesTop-up UUID
statusstringYesTop-up status, such as INITIATED or COMPLETED
amountstringYesDecimal amount loaded
ncbReferencestringNoNCB bank reference when available
balanceWalletBalanceYesUpdated wallet balance

WalletCard

Returned by issueCard() and listCards().

FieldTypeRequiredDescription
idstringYesCard UUID
brandstringYesCard network, such as VISA or MADA
cardTypestringYesCREDIT or DEBIT
tierstringNoCard tier
statusstringYesCard status, such as ISSUED or ACTIVE
cardholderNamestringNoName printed on card
last4stringYesLast four PAN digits
expiryMonthnumberYesMonth from 1 to 12
expiryYearnumberYesFour-digit year
createdAtstringNoISO 8601 timestamp

WalletCardDetails

Returned by getCardDetails(). Extends WalletCard, except createdAt, with sensitive fields.

Never log, cache, or persist this object.

FieldTypeRequiredDescription
All WalletCard fields except createdAtCard data
numberstringYesFull PAN
cvvstringYesCard CVV

WalletCardSpendResult

Returned by spend().

FieldTypeRequiredDescription
spendIdstringYesSpend transaction UUID
cardIdstringYesCard UUID used
statusstringYesSpend status
amountstringYesDecimal amount spent
balanceWalletBalanceYesUpdated wallet balance

WalletSDKError

Thrown by every SDK method on failure.

FieldTypeRequiredDescription
codeWalletSDKErrorCodeYesStable machine-readable code
messagestringYesLocalized human-readable message
messageArstringNoArabic message from backend
statusCodenumberNoHTTP status for API errors
apiCodestringNoBackend error code, such as INSUFFICIENT_FUNDS

Error codes

CodeWhen
APIBackend rejected the request
NETWORKNo connectivity or timeout
DECODINGResponse could not be parsed
UNAUTHORIZEDToken expired or invalid
INVALID_MOBILE_NUMBERMobile number failed validation
CANCELLEDOperation cancelled programmatically
USER_CANCELLEDUser dismissed a native sheet
NO_ACTIVE_SESSIONNo stored session to restore
UNSUPPORTED_PLATFORMPlatform not supported
INVALID_ARGUMENTParameter failed client-side validation
UNKNOWNUnclassified error

Input option types

LoginOptions

FieldTypeRequiredDescription
mobilestringYesSaudi mobile number

OnboardingOptions

FieldTypeRequiredDescription
mobilestringYesSaudi mobile number
namestringYesFull name. First word becomes first name; remaining words become last name
emailstringNoEmail address

PageOptions

FieldTypeDefaultDescription
pagenumber11-based page number
limitnumber20Page size, up to 1000

AddBeneficiaryOptions

FieldTypeRequiredDescription
mobilestringYesRecipient mobile number
nicknamestringNoCustom recipient label

TransferOptions

FieldTypeRequiredDescription
beneficiaryIdstringYesVerified beneficiary UUID
amountstringYesDecimal string, such as "25.00"
notestringNoTransfer note

IssueCardOptions

FieldTypeRequiredDescription
cardType"CREDIT" or "DEBIT"YesCard type to issue
tierstringNoCard tier

SpendOptions

FieldTypeRequiredDescription
cardIdstringYesCard UUID
amountstringYesDecimal amount
descriptionstringNoSpend description

Built-in screens

wallet.show(kind) accepts these screen names:

ScreenDescription
balanceBalance overview
transactionsTransaction history
beneficiariesSaved recipients list
transferTransfer flow
topUpTop-up flow
cardsCard management