통합 결제 설정

그룹 안 구독 건을 지정한 결제일에 한꺼번에 청구해요. 날짜는 1~21 이 안전해요.

고객 그룹의 구독 통합 결제(Aggregate Transaction) 설정을 관리해요. 그룹 내 구독 건들을 지정된 결제일에 한꺼번에 처리할 수 있어요.

API 엔드포인트

PUThttps://api.bootapi.com/v1/user-groups/:id/aggregate-transactionBasic Auth

필요 scope: manager:aggregate_transaction. Bootpay-Role 헤더와 무관하게 이 scope를 검사해요. v1 회원 그룹 API 상세 명세에서 인증과 응답 필드를 확인해요.

요청 파라미터

파라미터	타입	필수	설명
`id`	String	필수	그룹 고유 ID (URL 파라미터)
`use_subscription_aggregate_transaction`	Boolean	선택	통합 결제 사용 여부
`subscription_month_day`	Integer	선택	월 단위 결제일 (1~21 권장)
`subscription_week_day`	Integer	선택	주 단위 결제일. `1`(월)~`5`(금) — 주 단위 결제일 참고

보내지 않은 값은 기존 설정을 유지해요. 서버는 결제일 값의 범위를 검사하지 않으므로 유효한 값을 보내요. 월 결제일은 1~21 사이를 권장해요. 28일 이후는 월마다 일수가 달라 예측이 어려워요.

코드 예제

const { BootpayCommerce } = require('@bootpay/backend-js');

const commerce = new BootpayCommerce({
    client_key: '{client_key}',
    secret_key: '{secret_key}'
});

const userGroupId = '67e2052b03d0cb4e4117b0af';
const response = await commerce.userGroup.aggregateTransaction(userGroupId, {
    use_subscription_aggregate_transaction: true,
    subscription_month_day: 15,  // 매월 15일
    subscription_week_day: 3     // 매주 수요일
});
console.log(response);javascript

from bootpay_backend.commerce import BootpayCommerce

commerce = BootpayCommerce('{client_key}', '{secret_key}')
user_group_id = '67e2052b03d0cb4e4117b0af'
response = commerce.user_group.aggregate_transaction(user_group_id, {
    'use_subscription_aggregate_transaction': True,
    'subscription_month_day': 15,
    'subscription_week_day': 3
})
print(response)python

use Bootpay\ServerPhp\BootpayCommerceApi;

$commerce = new BootpayCommerceApi("{client_key}", "{secret_key}");
$userGroupId = '67e2052b03d0cb4e4117b0af';
$response = $commerce->userGroup->aggregateTransaction($userGroupId, [
    'use_subscription_aggregate_transaction' => true,
    'subscription_month_day' => 15,
    'subscription_week_day' => 3
]);
print_r($response);php

import kr.co.bootpay.store.BootpayStore;
import kr.co.bootpay.store.model.request.TokenPayload;
import kr.co.bootpay.store.model.request.userGroup.UserGroupAggregateTransactionParams;

TokenPayload tokenPayload = new TokenPayload("{client_key}", "{secret_key}");
BootpayStore bootpay = new BootpayStore(tokenPayload).withToken();
UserGroupAggregateTransactionParams params = new UserGroupAggregateTransactionParams();
params.userGroupId = "67e2052b03d0cb4e4117b0af";
params.useSubscriptionAggregateTransaction = true;
params.subscriptionMonthDay = 15;
params.subscriptionWeekDay = 3;

var response = bootpay.userGroup.aggregateTransaction(params);
System.out.println(response.getData());java

require 'bootpay'

commerce = BootpayStore::RestClient.new(client_key: '{client_key}', secret_key: '{secret_key}')
user_group_id = '67e2052b03d0cb4e4117b0af'
response = commerce.user_group_aggregate_transaction(
  user_group_id: user_group_id,
  use_subscription_aggregate_transaction: true,
  subscription_month_day: 15,
  subscription_week_day: 3
)
puts responseruby

commerce := bootpay.NewCommerceApi("{client_key}", "{secret_key}")
userGroupId := "67e2052b03d0cb4e4117b0af"
response, err := commerce.UserGroup.AggregateTransaction(userGroupId, map[string]interface{}{
    "use_subscription_aggregate_transaction": true,
    "subscription_month_day":                 15,
    "subscription_week_day":                  3,
})
fmt.Println(response)go

using Bootpay.Commerce;

var commerce = new BootpayCommerceApi("{client_key}", "{secret_key}");
var userGroupId = "67e2052b03d0cb4e4117b0af";
var response = await commerce.UserGroup.AggregateTransaction(userGroupId, new {
    use_subscription_aggregate_transaction = true,
    subscription_month_day = 15,
    subscription_week_day = 3
});
Console.WriteLine(response);csharp

응답

성공 응답

{
  "use_subscription_aggregate_transaction": true,
  "subscription_month_day": 15,
  "subscription_week_day": 3
}json

주 단위 결제일 (`subscription_week_day`)

요일 번호예요. enum 키가 아니라 숫자 그대로 주고받아요. 0(일요일)부터 시작하는 체계라 Date#wday·JavaScript getDay() 와 같은 번호예요.

값	요일	선택 가능
`0`	일요일	—
`1`	월요일	✅
`2`	화요일	✅
`3`	수요일	✅
`4`	목요일	✅
`5`	금요일	✅
`6`	토요일	—

관리자 화면이 월~금만 제공해서, 실제로 설정되는 값은 1~`5` 예요.

API 는 이 값을 검사하지 않아서 0(일)·6(토)을 보내면 오류 없이 그대로 저장돼요. 하지만 지원 대상이 아니라 동작을 보장하지 않으니 평일 값만 보내주세요.

에러 코드

인증·권한 관련 에러는 에러 코드표를 참고해요.

코드	메시지	대처 방법
`USER_GROUP_NOT_FOUND`	회원 그룹 정보를 찾지 못했어요. 다시 로그인해요.	user_group_id를 확인해요
`USER_GROUP_NOT_AUTHORIZED`	그룹 정보를 설정할 권한이 없어요.	그룹 관리자 권한이 있는지 확인해요