Deposit to a Budget

Add funds to a budget account. Only budget accounts in ACTIVE status can be topped up.
Request Parameters
requestIdstring
required
Idempotency key. Required for all fund-movement operations. Assign a unique value per request to safely retry without double-charging. Must be unique within your partnerId. Max 64 characters.
idstring
required
Unique budget account identifier returned by Create a Budget. Max 64 characters.
balanceTypestring
required
Source balance account type used to fund the deposit.

Valid Values:

NORMAL_BALANCE — Normal balance (e-commerce balance), the default balance type
SAME_NAME_TOP_UP_BALANCE — Same-name top-up balance, funded via a same-name bank account transfer
amountAmount
required
Deposit amount. value must be greater than 0. See Data Types.
Response Parameters
resultResult
See Result.
idstring
Unique budget account identifier. Max 64 characters.
balanceTypestring
Source balance account type used for the deposit.

Valid Values:

NORMAL_BALANCE — Normal balance (e-commerce balance), the default balance type
SAME_NAME_TOP_UP_BALANCE — Same-name top-up balance, funded via a same-name bank account transfer
amountAmount
Deposit amount. See Data Types.
statusstring
Deposit operation status (e.g., SUCCESS).
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccess.Deposit succeeded.
BUDGET_NOT_FOUNDFBudget account {id} not found.Verify the `id` is correct.
BUDGET_ACCOUNT_STATUS_INACTIVEFBudget account is not in ACTIVE status.Only `ACTIVE` budget accounts can be topped up.
BALANCE_NOT_ENOUGHFBalance insufficient.Ensure the source balance account has sufficient funds.
USER_NOT_EXISTFThe user does not exist.Retry with correct user information.
AUTHORIZATION_NOT_EXISTFThe authorization relationship does not exist.Verify the `account-id` / `access-token` authorization before retrying.
CONTRACT_CHECK_FAILFThe contract check has failed.Contact WorldFirst support to confirm the contract status, then retry.
REPEAT_REQ_INCONSISTENTFRepeated requests are inconsistent.A prior request reused this `requestId` with different parameters. Keep all parameters identical, or use a new `requestId`.
PARAM_ILLEGALFIllegal parameters exist.Verify request fields against this reference, including the `amount` structure.
PROCESS_FAILFA general business failure occurred. Do not retry.Do not retry. Contact WorldFirst support.
UNKNOWN_EXCEPTIONUAn unknown exception occurred.Server error. Retry later; contact WorldFirst support if the issue persists.
Definition
POST /api/open/v1/issuing/budgets/deposit
Request
{
"requestId": "req_deposit_20240101****",
"id": "BUDGET_20260401100101****",
"balanceType": "NORMAL_BALANCE",
"amount": {
  "currency": "USD",
  "value": 1002
}
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "Success.",
  "resultStatus": "S"
},
"id": "BUDGET_20260401100101****",
"balanceType": "NORMAL_BALANCE",
"amount": {
  "currency": "USD",
  "value": 1002
},
"status": "SUCCESS"
}