이전(승계) 요청 | Bootpay 커머스 매뉴얼

기존 구독을 다른 사용자에게 넘겨 계약 흐름을 이어 붙여요.

구독 계약을 다른 사용자에게 이전(승계)해요. 기존 구독자의 계약이 새로운 사용자에게 넘어가요.

API 엔드포인트

POSThttps://api.bootapi.com/v1/order_subscriptions/requests/ing/transferBasic Auth

사용자 요청 vs 관리자 요청

구분	사용자 요청	관리자 요청
호출 주체	고객 (사용자 토큰)	관리자 (관리자 토큰)
승인 필요	예	설정에 따라 즉시 처리 가능
인수자 지정	필수	필수

요청 파라미터

파라미터	타입	필수	설명
`order_subscription_id`	String	필수	구독 계약 ID
`new_user_id`	String	필수	새 구독자의 사용자 ID
`new_username`	String	선택	새 구독자 이름
`new_user_email`	String	선택	새 구독자 이메일
`new_user_phone`	String	선택	새 구독자 전화번호
`new_user_address`	String	선택	새 구독자 주소
`wallet_id`	String	선택	새 구독자의 결제 수단 (지갑 ID)
`reason`	String	선택	이전 사유

코드 예제

curl -X POST "https://api.bootapi.com/v1/order_subscriptions/requests/ing/transfer" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{
    "order_subscription_id": "sub_abc123",
    "new_user_id": "user_new_001",
    "new_username": "김철수",
    "reason": "구독 승계 요청"
  }'bash

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

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

const response = await commerce.orderSubscriptionRequest.transfer({
    order_subscription_id: 'sub_abc123',
    new_user_id: 'user_new_001',
    new_username: '김철수',
    reason: '구독 승계 요청'
});
console.log(response);javascript

from bootpay_backend.commerce import BootpayCommerce

commerce = BootpayCommerce('{client_key}', '{secret_key}')
response = commerce.order_subscription_request_transfer({
    'order_subscription_id': 'sub_abc123',
    'new_user_id': 'user_new_001',
    'new_username': '김철수',
    'reason': '구독 승계 요청'
})
print(response)python

use Bootpay\ServerPhp\BootpayCommerceApi;

$commerce = new BootpayCommerceApi("{client_key}", "{secret_key}");
$response = $commerce->orderSubscriptionRequestTransfer([
    'order_subscription_id' => 'sub_abc123',
    'new_user_id' => 'user_new_001',
    'new_username' => '김철수',
    'reason' => '구독 승계 요청'
]);
print_r($response);php

import kr.co.bootpay.store.BootpayStore;
import kr.co.bootpay.store.model.request.TokenPayload;
import kr.co.bootpay.store.model.response.BootpayStoreResponse;
import kr.co.bootpay.store.model.request.orderSubscription.request.ing.OrderSubscriptionTransferParams;

TokenPayload tokenPayload = new TokenPayload("{client_key}", "{secret_key}");
BootpayStore commerce = new BootpayStore(tokenPayload).withToken();

OrderSubscriptionTransferParams params = new OrderSubscriptionTransferParams();
params.orderSubscriptionId = "sub_abc123";
params.newUserId = "user_new_001";
params.newUsername = "김철수";
params.reason = "구독 승계 요청";

BootpayStoreResponse response = commerce.orderSubscription.requestIng.transfer(params);
System.out.println(response);java

require 'bootpay-backend-ruby'

commerce = BootpayStore::RestClient.new(client_key: '{client_key}', secret_key: '{secret_key}')
response = commerce.order_subscription_requests_ing_transfer(
  order_subscription_id: 'sub_abc123',
  new_user_id: 'user_new_001',
  new_username: '김철수',
  reason: '구독 승계 요청'
)
puts responseruby

commerce := bootpay.NewCommerceApi("{client_key}", "{secret_key}")
response, err := commerce.OrderSubscriptionRequestTransfer(map[string]interface{}{
    "order_subscription_id": "sub_abc123",
    "new_user_id":           "user_new_001",
    "new_username":          "김철수",
    "reason":                "구독 승계 요청",
})
fmt.Println(response)go

var commerce = new BootpayCommerceApi("{client_key}", "{secret_key}");
var response = await commerce.OrderSubscriptionRequestTransfer(new {
    order_subscription_id = "sub_abc123",
    new_user_id = "user_new_001",
    new_username = "김철수",
    reason = "구독 승계 요청"
});
Console.WriteLine(response);csharp

응답

{
  "id": "req_transfer_001",
  "status": 0,
  "request_type": 3,
  "new_user_id": "user_new_001",
  "transfer_status": "pending"
}json

응답 파라미터

파라미터	타입	설명
id	String	요청 고유 ID
status	Integer	요청 상태 (`0`: 대기, `1`: 승인, `-1`: 거절)
request_type	Integer	요청 유형 (`3`: 이전(승계))
new_user_id	String	새 구독자 사용자 ID
transfer_status	String	이전 처리 상태

에러 코드

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

코드	메시지	대처 방법
`SUBSCRIPTION_TRANSFER_NOT_ALLOWED`	해당 구독 상품은 계약 이전/승계를 지원하지 않아요	구독 설정에서 이전/승계를 활성화해요
`SUBSCRIPTION_TRANSFER_USER_INFO_REQUIRED`	신규 사용자 정보가 필요해요.	new_user 정보를 입력해요
`ORDER_SUBSCRIPTION_TRANSFER_REQUEST_DUPLICATE`	이미 대기 중인 이전/승계 요청이 있어요. 관리자가 처리 중이니 잠시만 기다려라.	기존 요청 처리를 기다려라