Create a Budget

Create a budget account to allocate and hold funds for card issuing. Each merchant account supports up to 3 budget accounts. A budget account cannot be closed once it has been created.
Request Parameters
requestIdstring
required
Idempotency key. Assign a unique value (e.g., UUID) per request to safely retry without creating duplicate budget accounts. Max 64 characters.
namestring
Budget account name. If omitted, the system assigns a name automatically. Max 50 characters.
Response Parameters
resultResult
See Result.
idstring
Unique budget account identifier. Use this ID for subsequent query, deposit, and withdraw operations. Max 64 characters.
namestring
Budget account name. Echoes the request value, or the system-assigned name if name was omitted.
statusstring
Current budget account status.

Valid Values:

ACTIVE — Account is activated and ready to use.
FAILED — Account creation failed.
createdAtdatetime
Timestamp when the budget account was created. ISO 8601 extended format (e.g., 2026-07-21T12:46:26Z).
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSSuccess.N/A
BUDGET_ACCOUNT_NUMBER_OVER_LIMITFThe number of budget accounts exceeds the limit.Each account may hold at most 3 budget accounts. Reuse an existing budget account.
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.
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/create
Request
{
"requestId": "req_budget_20260808****",
"name": "Marketing Cards Q3"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultStatus": "S"
},
"id": "BUDGET_20260401100101****",
"name": "Marketing Cards Q3",
"status": "ACTIVE",
"createdAt": "2026-08-08T12:46:26Z"
}