1. Overdraft
Virtual Account Services
  • Introduction
  • Terminologies
  • Webhooks
  • Authentication
  • Account
    • Create Account
      POST
    • Balance Inquiry
      GET
    • Rename Account
      POST
    • Create Bulk Accounts
      POST
    • List Accounts
      GET
  • Transaction
    • Credit Account
      POST
    • Debit Account
      POST
    • Credit Account [Agency Banking]
      POST
    • Debit Account [Agency Banking]
      POST
    • Transaction Query
      GET
    • Transaction Details
      GET
    • Transaction History
      GET
  • Transfer
    • Interbank Transfer
      • Interbank Transfer
      • Interbank Transfer [Sync]
      • Transfer Query
      • Transfer Enquiry
    • Intrabank Transfer
      • Intrabank Transfer [Same Groupcode]
      • Intrabank Transfer [Different Group Codes]
      • Intrabank Transfer [Savings Account]
      • Intrabank Transfer Query
    • Name Inquiry
      POST
    • Get Institutions
      GET
  • Invoice
    • Create Invoice
      POST
    • Get Invoice Detail
      GET
    • Get Invoice Status
      GET
    • List Merchant Invoices
      GET
  • Refunds
    • Get Refunds
    • Initiate Refund
    • Get Refund Status
  • Notifications
    • Notification
    • Send Notification
  • Group Code
    • Create Group Code
  • Overdraft
    • Draw Overdraft
      POST
  • Merchant
    • Account
      • Get Account
      • Activate Sub Ledger For Merchant
      • Get SubLedger Callback Urls
      • Set SubLedger Callback Urls
      • Get Collection Accounts
    • Transfer
      • Get Transfer Details
      • Name Inquiry
      • Get Transfer History
      • Get Subledger transfers
    • Refund
      • Refund Details
    • Create Merchant Account
    • Activate Sub Ledger For Merchant
    • Get KYC Information
    • Get Group Code Collection Account
    • Get Collection Accounts
    • Set Collection Account
    • Get Transfer Details
    • Name Inquiry
  • Admin
    • Accounting
      • Get Classification Codes
      • Get GL Accounts
    • Dashboard
      • Dashboard Summary
      • Dashboard Transaction Details
      • Dashboard Transactions
    • Group Codes
      • Create Group Code
      • Set Collection Account
      • Get Group Codes
    • Reporting
      • Get Report Parameters
      • Get Reports
      • Create Report
      • Get Reports Details
      • Get Reports
    • Get Reports
    • Get Report Parameters
  • Schemas
    • VACreateGroupCodeRequest
    • SubLedgerGroup
    • InvalidParameterError
    • TransactionPointError
    • UnauthorizedError
    • SpringDefaultError
  1. Overdraft

Draw Overdraft

POST
/va/overdraft/draw

Draw a subledger overdraft#

Obtains an overdraft: debits a subledger overdraft account and credits any other subledger account in the system.

Request body#

FieldTypeRequiredDescription
overdraftAccountCodestringYesUnique code of the subledger overdraft account to draw on, for example POWER_1. Shown on the Subledger Overdraft page.
beneficiaryAccountIDstringYesSubledger account to credit. It must exist and must not be the settlement subledger of an overdraft account.
amountnumber (decimal)YesAmount to draw. Minimum 0.01.
transactionReferencestringNoYour own unique reference. Sending the same reference again returns the original draw instead of drawing twice. If omitted, one is generated.
narrationstringNoNarration for the transaction. Defaults to Overdraft - <account name>.

Response#

200 OK#

FieldTypeDescription
accountCodestringThe overdraft account that was drawn on.
transRefstringReference of the draw (your transactionReference when you sent one).
amountnumberAmount drawn.
outstandingBalancenumberWhat the overdraft account owes after the draw. 0 while it is in credit.
creditBalancenumberCredit the overdraft account still holds after the draw. 0 while it owes.
messagestringOverdraft drawn, or Overdraft already drawn with this reference when the request repeated an earlier transactionReference.

How a draw behaves#

Credit is spent first. If the overdraft account has been funded (it holds credit), the draw uses that credit before any overdraft. Only the remainder is overdraft, and only that remainder increases outstandingBalance.
Limit. A draw is allowed up to the account's credit plus its overdraft limit.
A limit of 0 means no overdraft: the account must be funded first, and a draw above its credit is rejected.
An account with no limit accepts any amount.
Idempotency. Re-sending the same transactionReference for the same account returns the original result with the message Overdraft already drawn with this reference and does not draw again. Using a reference that belongs to a different account or to a settlement is rejected.
Beneficiary notification. The beneficiary subledger is credited and its webhook is called as for a NIP credit transfer.
Repayment is not part of this API. An overdraft is settled by crediting the account's settlement subledger (or from the Subledger Overdraft page); see the settlement flow in the admin UI.

Errors#

The gateway returns the standard API error body. core banking's own messages are passed through in detailedMessage. The exact status code for a core banking rejection follows core banking.
{
  "error": "...",
  "detailedMessage": "...",
  "httpStatusCode": 400,
  "errorCode": "...",
  "parameter": "...",
  "value": "...",
  "errors": []
}
CauseMessage (or part of it)
Missing or invalid field`overdraftAccountCode` is required, `beneficiaryAccountID` is required, `amount` is required, Amount must be 0.01 or greater
No client id on the request`clientID` is required
Client has no permission row for this accountNo Access To Core Banking (no rows at all) or Access Denied (no row covering this account)
Feature switched offSubledger Overdraft Is Disabled
Unknown overdraft accountSubledger Overdraft Account `<code>` Not Found
Account not activeSubledger Overdraft Account Is Not Active
Beneficiary is an overdraft settlement subledgerA Subledger Overdraft Settlement Subledger Cannot Be The Beneficiary
Beneficiary does not existThe subledger system's own not-found error
Over the overdraft limitOverdraft Limit Exceeded. Available: <amount>
Zero-limit account without enough creditInsufficient funds. This account does not allow overdraft. Available: <amount>
Reference already used by another account or a settlementReference `<transactionReference>` Has Already Been Used

Request

Authorization
OAuth 2.0
Client Credentials
Add the parameter
Authorization
to Headers
,whose value is to concatenate the Token after the Bearer.
Example:
Authorization: Bearer ********************
Token URL: {{tpGatewayHostUrl}}/security/authenticate
or
Body Params application/json

Example
{
  "overdraftAccountCode": "POWER_1",
  "beneficiaryAccountID": "0000000128",
  "amount": 500000,
  "transactionReference": "PAYROLL-1294-77-042",
  "narration": "Sample narration"
}

Request Code Samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/va/overdraft/draw' \
--header 'Content-Type: application/json' \
--data '{
  "overdraftAccountCode": "POWER_1",
  "beneficiaryAccountID": "0000000128",
  "amount": 500000,
  "transactionReference": "PAYROLL-1294-77-042",
  "narration": "Sample narration"
}'

Responses

🟢200Response
application/json
Bodyapplication/json

Examples
{
  "accountCode": "ADEPT_1",
  "transRef": "PAYROLL-2026-10-001",
  "amount": 500000,
  "outstandingBalance": 1500000,
  "creditBalance": 0,
  "message": "Overdraft drawn"
}
🟠400| Source | Error | When |
🟠401| Source | Error | When |
🟠403| Source | Error | When |
🟠404| Source | Error | When |
🔴500| Source | Error | When |
Modified at 2026-11-02 12:41:29
Previous
Create Group Code
Next
Get Account
Built with