결제 계정 구조 설계

TIP

시작하기 전에 Digital Payment 튜토리얼의 wallet_request 준비를 완료하십시오. 아래 예제는 Base URL·API Key·HMAC Key 환경 변수와 wallet_request 함수가 설정된 셸에서 실행합니다.

결제 흐름에서는 두 가지 계정 역할을 사용합니다.

구분	account_type	용도	uid 예시
고객 지갑	USER	고객 입금 주소, 잔액, 결제 자금 관리	user-{customer_id}
가맹점 결제 계정	BUSINESS	고객 결제 수취 및 외부 정산 요청	business-{merchant}-payment

가맹점 결제 계정은 결제 수취 잔액을 관리하는 OOLIN Wallet API 계정입니다. 외부 정산은 이 계정에서 출금을 요청하는 방식으로 진행합니다.

고객 계정 생성 또는 재사용

POST /accounts는 멱등 API가 아닙니다. 계정을 추가로 만들기 전에 고객 uid의 기존 계정을 조회합니다.

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

필요한 USER 계정이 없을 때만 생성합니다.

이미 있다면 조회한 실제 ID로 아래 변수를 설정하고 고객 계정 생성 코드는 건너뜁니다. 여러 계정 중에서는 고객사에 저장한 연결 정보를 기준으로 선택합니다.

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

계정이 없는 경우에만 다음 코드를 실행합니다.

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

고객 시스템의 사용자 ID와 USER_ACCOUNT_ID의 연결 관계를 영구 저장합니다.

가맹점 결제 계정 생성 또는 재사용

결제를 수취할 가맹점 또는 운영 주체마다 하나의 BUSINESS 계정을 만듭니다. 고객마다 생성하지 않습니다.

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

의도한 활성 BUSINESS 계정이 있으면 아래 변수를 설정하고 생성을 건너뜁니다.

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

계정이 없는 경우에만 다음 코드를 실행합니다.

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

역할별 ID 저장과 검증

생성 응답이 유실되면 같은 uid의 계정 목록을 먼저 조회합니다. 같은 고객·가맹점의 동시 생성을 직렬화하고, 잠금·비활성 계정을 추가 계정 생성으로 우회하지 않습니다.

USER_ACCOUNT_ID와 PAYMENT_ACCOUNT_ID를 별도 필드로 관리합니다. 애플리케이션 시작 시 저장된 계정의 uid, account_type, status를 검증하십시오. 두 ID를 혼용하면 잘못된 주체에서 결제 또는 정산이 실행될 수 있습니다.

다음: 결제용 자산 충전