API Route Guide

Auto-registered (optional) proxy endpoints provided by the laravel-xpresswallet package when XPRESSWALLET_ROUTES_ENABLED=true.

Security: Always apply authentication/authorization middleware (e.g. auth:sanctum) via XPRESSWALLET_ROUTES_MIDDLEWARE. These endpoints move funds and manage sensitive resources.

Overview

All routes are grouped under the configurable prefix (default /xpresswallet) and named with the xpresswallet. namespace. Errors surface as JSON with Laravel's standard validation format (422), or downstream API errors (mapped exceptions) standardised by the package.

Successful responses simply proxy the upstream API JSON body (with minimal wrapping).

Customers

MethodPathNameDescriptionValidation
GET/customersxpresswallet.customers.indexList customers (supports query params like page)-
POST/customersxpresswallet.customers.storeCreate customerfirst_name,last_name,email,phone required; see form request
GET/customers/{id}xpresswallet.customers.showRetrieve customer by ID-
GET/customers/phone/{phone}xpresswallet.customers.find-by-phoneFind by phone-
PUT/customers/{id}xpresswallet.customers.updateUpdate customerAt least one mutable field
Create Customer Payload 
{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "ada@example.test",
  "phone": "+2348012345678",
  "metadata": {"tier": "gold"}
}

Wallets

MPathNameDescriptionValidation
GET/walletswallets.indexList wallets-
GET/wallets/customer/{customerId}wallets.customerWallets for a customer-
POST/walletswallets.storeCreate walletcustomer_id|customer_identifier,currency,type
POST/wallets/{id}/creditwallets.creditCredit walletamount required
POST/wallets/{id}/debitwallets.debitDebit walletamount required
POST/wallets/{id}/freezewallets.freezeFreeze wallet-
POST/wallets/{id}/unfreezewallets.unfreezeUnfreeze wallet-
POST/wallets/batch/creditwallets.batch.creditBatch creditarray of credits
POST/wallets/batch/debitwallets.batch.debitBatch debitarray of debits
POST/wallets/customer/batch/creditwallets.customer.batch.creditBatch credit via customer IDsarray of entries
POST/wallets/fund-sandboxwallets.fund-sandboxFund sandbox merchant walletamount

Transactions

MPathNameDescription
GET/transactionstransactions.merchantList merchant transactions (query filters)
GET/transactions/{reference}transactions.showTransaction details

Transfers

MPathNameDescriptionValidation
GET/transfers/bankstransfers.banksList supported banks-
GET/transfers/account-detailstransfers.account-detailsResolve account detailsbank_code,account_number query
POST/transfers/banktransfers.bankSingle bank transferbank_code, account_number, amount, currency
POST/transfers/bank/customertransfers.bank.customerCustomer bank transfercustomer_id + bank transfer fields
POST/transfers/bank/batchtransfers.bank.batchBatch bank transferstransfers[] array
POST/transfers/wallettransfers.walletWallet to wallet transfersource_wallet_id,destination_wallet_id,amount

Cards

MPathNameDescriptionValidation
GET/cardscards.indexList cards-
POST/cards/setupcards.setupInitiate card setupcustomer_id,type,currency
POST/cards/activatecards.activateActivate cardcard_id,code
GET/cards/{cardId}/balancecards.balanceCard balance-
POST/cards/fundcards.fundFund cardcard_id,amount,currency

Merchant

MPathNameDescription
POST/merchant/password/request-changemerchant.password.request-changeRequest password reset code
POST/merchant/password/changemerchant.password.changeChange password using reset code
POST/merchant/verifymerchant.verifyVerify merchant
POST/merchant/resend-verificationmerchant.resend-verificationResend verification code
POST/merchant/resend-activationmerchant.resend-activationResend activation code
POST/merchant/complete-registrationmerchant.complete-registrationComplete registration
GET/merchant/profilemerchant.profileMerchant profile
GET/merchant/access-keysmerchant.access-keysList access keys
POST/merchant/access-keys/generatemerchant.access-keys.generateGenerate new access keys
GET/merchant/account-modemerchant.account-modeCurrent account mode
POST/merchant/account-mode/switchmerchant.account-mode.switchSwitch account mode
GET/merchant/summarymerchant.summarySummary metrics
GET/merchant/walletmerchant.walletMerchant wallet info

Team

MPathNameDescription
GET/team/invitationsteam.invitationsList invitations
POST/team/invitationsteam.invitations.inviteInvite member
POST/team/invitations/resendteam.invitations.resendResend invitation
POST/team/invitations/acceptteam.invitations.acceptAccept invitation
GET/team/membersteam.membersList members
GET/team/merchantsteam.merchantsList accessible merchants
POST/team/merchants/switchteam.merchants.switchSwitch active merchant
GET/team/permissionsteam.permissionsList permissions
GET/team/rolesteam.rolesList roles

Validation Reference

This table summarises required fields; see source src/Http/Requests/* for complete rules (including lengths, enums).

Form RequestRequiredNotes
CustomerCreateRequestfirst_name,last_name,email,phonecountry optional ISO2
CustomerUpdateRequest(any subset)"sometimes" semantics
WalletCreateRequestcustomer_id|customer_identifier,currency,typemutually exclusive id fields
WalletAdjustRequestamountcredit/debit operations
TransferBankRequestbank_code,account_number,amount,currency
TransferBankCustomerRequestcustomer_id + bank transfer fields
TransferBankBatchRequesttransfers[]1..100 entries
TransferWalletRequestsource_wallet_id,destination_wallet_id,amount,currencydest != source
CardSetupRequestcustomer_id,type,currency
CardFundRequestcard_id,amount,currency
MerchantCompleteRegistrationRequestbusiness_name,business_email,business_phone,country,contact_first_name,contact_last_name,contact_email,contact_phonedocs[] optional
MerchantChangePasswordRequestreset_code,password,password_confirmationmin length 8
TeamInviteRequestemail,role
TeamResendInvitationRequestinvitation_id
TeamAcceptInvitationRequestinvitation_id,code

Error Handling

Version

Guide generated for package version 0.3.0.