EngineModule referencesettlement

@withpotter/settlement — module reference

HTTP routes this module mounts, plus its internal use-cases, entities, and repositories. The exhaustive request/response contract is the engine’s OpenAPI document at /docs; the layered structure below follows the package internal architecture.

HTTP routes

Settlements /settlements

MethodPathAuthDescription
GET/settlementsYesList settlements
GET/settlements/bank-accountsYesList merchant bank accounts
GET/settlements/banksYesList available banks
GET/settlements/banks/resolveYesResolve bank account details
GET/settlements/summaryYesGet settlements summary
POST/settlements/bank-accountsYesAdd a new bank account
POST/settlements/bank-accounts/:id/defaultYesSet bank account as default
POST/settlements/reconcileYesReconcile historical transactions
POST/settlements/syncYesSync settlements from payment provider
DELETE/settlements/bank-accounts/:idYesDelete a bank account

Internals

Use-cases

Application operations. Each is a single-purpose class with one execute() method.

Use-caseSignature
AddBankAccountUseCaseexecute(tenantId: string, dto: AddBankAccountDto): Promise<BankAccountResponse>
DeleteBankAccountUseCaseexecute(tenantId: string, accountId: string): Promise<{ success: boolean }>
GetSettlementSummaryUseCaseexecute(tenantId: string, startDate?: string, endDate?: string): Promise<SettlementSummaryResponse>
GetSettlementsUseCaseexecute(tenantId: string, options: { page?: number; limit?: number; startDate?: string; endDate?: string; } = {}): Promise<SettlementListResponse>
ListBankAccountsUseCaseexecute(tenantId: string): Promise<BankAccountResponse[]>
ListBanksUseCaseexecute(): Promise<{ banks: BankListResponse[] }>
ReconcileTransactionsUseCaseexecute(tenantId: string, params?: { startDate?: string; endDate?: string }): Promise<ReconciliationResult>
RequestWithdrawalUseCaseexecute(tenantId: string, params: RequestWithdrawalParams): Promise<WithdrawalResult>
ResolveAccountUseCaseexecute(accountNumber: string, bankCode: string): Promise<ResolveAccountResponse>
SetDefaultBankAccountUseCaseexecute(tenantId: string, accountId: string): Promise<{ success: boolean }>
SyncSettlementsUseCaseexecute(tenantId: string): Promise<SyncResult>

Entities

Sequelize models owned by this module.

MerchantBankAccount — table merchant_bank_accounts

FieldType
idstring
tenantIdstring
bankCodestring
bankNamestring
accountNumberstring
accountNamestring
paystackSubaccountCodestring
paystackSubaccountIdstring
splitPercentagenumber
statusBankAccountStatus
isDefaultboolean
failureReasonstring
metadataRecord<string, unknown>
createdAtDate
updatedAtDate

Settlement — table settlements

FieldType
idstring
tenantIdstring
bankAccountIdstring
transactionIdstring
paystackSettlementIdstring
paystackTransferCodestring
grossAmountnumber
paystackFeenumber
platformFeenumber
netAmountnumber
currencystring
statusSettlementStatus
settlementTypeSettlementType
periodStartDate
periodEndDate
settledAtDate
failureReasonstring
metadataRecord<string, unknown>
createdAtDate
updatedAtDate

Repositories

Data-access classes wrapping the entities.

MerchantBankAccountRepository

create · findById · findByTenantId · findDefaultByTenantId · getDefaultForTenant · findBySubaccountCode · update · setAsDefault · delete

SettlementRepository

create · findById · findByTransactionId · findByPaystackSettlementId · findByPaystackTransferCode · findByBankAccountId · updateStatus · listByTenant · getSummary · update · getRecentSettlements

Ports

DI contracts other modules bind adapters to.

  • ResolvedAccount, BankListEntry, CreateSubaccountInput, CreatedSubaccount, CreateTransferRecipientInput, InitiateTransferInput, InitiatedTransfer, SettlementBankingPort — token SETTLEMENT_BANKING
  • PaymentConnectedNotification, SettlementNotifierPort — token SETTLEMENT_NOTIFIER
  • ProviderSettlement, ListSettlementsParams, ListSettlementsResult, SettlementProviderInterface — token SETTLEMENT_PROVIDER

Generated from the module’s source. Routes are relative to the engine root (default http://localhost:3001). For full request/response schemas use the live OpenAPI document.

sequelize-adaptersshared