Create an account

Creates an active account for an owner in one settlement currency.

POST/accounts

Request

curl -X POST "<BASE_URL>/accounts" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerId": "customer_123",
    "currency": "USD"
  }'

Authorization

OAuth scope: accounts.writeThe access token must carry this scope.
Action: createAccount

Headers

AuthorizationstringRequired
OAuth 2.0 client-credentials flow for machine workloads.
X-Request-IduuidOptional
UUID unique to this HTTP request. The gateway echoes a valid caller-supplied value or generates one when the header is omitted. The resulting value is returned in X-Request-Id and structured error responses.
Idempotency-KeystringOptional
Unique key for safely retrying an identical resource-creation request.
Content-TypestringRequired
Always application/json.

Request body

currencystringRequired
No description yet.
pattern ^[A-Z]{3}$
ownerIdstringRequired
No description yet.
minimum length 1

Response

Status 201. Account created successfully.

balanceMinorintegerRequired
Available balance expressed as an integer in the currency's minor unit.
currencystringRequired
Three-letter ISO 4217 settlement currency code.
pattern ^[A-Z]{3}$
iduuidRequired
Stable account identifier.
ownerIdstringRequired
Customer or legal-entity identifier that owns the account.
minimum length 1
statusenumRequired
Current account lifecycle state.
Allowed values
- pending
- active
- frozen
- closed

Errors

Every error carries an HTTP status. Where it also carries a code, branch on the code, not on the message.

400INVALID_ARGUMENTThe request is malformed.
401UNAUTHENTICATEDAuthentication failed.
403PERMISSION_DENIEDThe principal is not authorized for this operation.
409ALREADY_EXISTSThe resource or idempotency key conflicts with existing state.
429RESOURCE_EXHAUSTEDA rate or concurrency limit was exceeded.
503UNAVAILABLEThe service is temporarily unavailable.