Design Payment Accounts

TIP

Before you start, complete the wallet_request setup in the Digital Payment tutorial. Run the examples below in the shell where the Base URL, API Key, and HMAC key environment variables and the wallet_request function are configured.

Use two account roles for the payment flow.

Role	account_type	Purpose	Example uid
Customer wallet	USER	Customer deposit address, balance, and payment funds	user-{customer_id}
Merchant payment account	BUSINESS	Receives customer payments and initiates settlement	business-{merchant}-payment

The merchant payment account is an OOLIN Wallet API account that holds received payments. Request a withdrawal from this account to settle funds externally.

Create or reuse the customer account

POST /accounts is not idempotent. Look up existing accounts for the customer uid before creating another one.

wallet_request GET '/users/user-tutorial-001/accounts' | jq

Create the account only when the required USER account does not exist.

If it exists, set the variable below to its returned ID and skip customer account creation. When several accounts exist, select one using your persisted customer mapping.

export USER_ACCOUNT_ID='{existing-active-user-account-id}'

Run the following code only when the account is absent.

user_account_body='{"uid":"user-tutorial-001","account_type":"USER","metadata":{"source":"payment-tutorial"}}'
user_account_response="$(wallet_request POST '/accounts' "$user_account_body")"
export USER_ACCOUNT_ID="$(printf '%s' "$user_account_response" | jq -r '.data.account_id')"

wallet_request GET "/accounts/$USER_ACCOUNT_ID" | jq

Persist the association between your customer ID and USER_ACCOUNT_ID.

Create or reuse the merchant payment account

Create one BUSINESS account for the merchant or operational entity receiving payments. Do not create one per customer.

wallet_request GET '/users/business-demo-payment/accounts' | jq

If the intended active BUSINESS account exists, set this variable and skip creation.

export PAYMENT_ACCOUNT_ID='{existing-active-business-account-id}'

Run the following code only when the account is absent.

payment_account_body='{"uid":"business-demo-payment","account_type":"BUSINESS","metadata":{"purpose":"OFFLINE_PAYMENT","asset":"USDT"}}'
payment_account_response="$(wallet_request POST '/accounts' "$payment_account_body")"
export PAYMENT_ACCOUNT_ID="$(printf '%s' "$payment_account_response" | jq -r '.data.account_id')"

wallet_request GET "/accounts/$PAYMENT_ACCOUNT_ID" | jq

Store and validate account roles

If a create response is lost, query accounts for the same uid first. Serialize concurrent provisioning for the same customer or merchant, and investigate a locked or disabled account rather than bypassing its state with another account.

Keep USER_ACCOUNT_ID and PAYMENT_ACCOUNT_ID in separate fields. At application startup, validate the persisted account's uid, account_type, and status. Mixing the IDs can send a payment or settlement from the wrong owner.

Next: Fund payment assets.