결제 연동

이미 받은 PG 가맹점 키(MID 등)를 하위 프로젝트에 넣고 결제수단을 켜고 끕니다. 아직 MID 가 없는 판매자는 PG 가맹 신청 을 사용합니다.

인증·권한 오류는 각 표에 없어도 공통 오류 가 날 수 있습니다.

1PG·필수 연동 값 목록

가맹점 생성·프로젝트 생성·PG 리소스 갱신 의 resources[] 에 넣을 수 있는 PG·결제수단과, 결제수단마다 resource 에 넣어야 하는 키를 돌려줍니다.

동작 규칙

• resources[].pg 에는 PG 의 symbols 중 하나, resources[].method 에는 결제수단의 symbols 중 하나를 넣습니다.
• resource_keys 중 required 가 true 인 키만 필수입니다. 하나라도 비면 RESOURCE_KEY_BLANK 로 거부됩니다. required 가 false 인 키는 PG 사가 준 경우에만 넣습니다(빼거나 빈 값이어도 됩니다). 부트페이 관리자 화면의 연동 정보 저장과 같은 기준입니다.
• 결제 모드가 있는 결제수단(일부 PG)은 새로 붙일 때의 기본 결제 모드 기준으로 required 를 줍니다. 관리자 화면에서 다른 모드를 고른 결제수단을 갱신하면 그 모드의 필수 키로 검사합니다.
• 값은 가맹 계약 뒤 PG 사가 알려 줍니다. description 은 부트페이 관리자 화면의 안내 문구라 HTML 이 섞여 있을 수 있습니다.
• input_type 이 textarea 인 키는 여러 줄 값(예: 인증서 PEM)입니다.
• 사용 중인 PG·결제수단만 나옵니다. pg 를 주면 그 PG 하나만 옵니다.
• 모든 리셀러가 같은 목록을 봅니다.

API 정보

1-1. 요청 파라미터

1-2. 코드 예제

import fetch from 'node-fetch'

const RESELLER_AUTH = 'Basic ' + Buffer
  .from(`${process.env.BOOTPAY_RESELLER_CLIENT_KEY}:${process.env.BOOTPAY_RESELLER_SECRET_KEY}`)
  .toString('base64')

const res = await fetch('https://api.bootpay.co.kr/v2/reseller/pgs?pg=nicepay', {
    headers: { 'Authorization': RESELLER_AUTH }
})
const { list } = await res.json()
const card = list[0].methods.find(m => m.method === 'card')
console.log(card.resource_keys.filter(k => k.required).map(k => k.key)) // resource 에 꼭 넣을 키javascript

import base64, os, requests

auth = 'Basic ' + base64.b64encode(
    f"{os.environ['BOOTPAY_RESELLER_CLIENT_KEY']}:{os.environ['BOOTPAY_RESELLER_SECRET_KEY']}".encode()
).decode()

res = requests.get('https://api.bootpay.co.kr/v2/reseller/pgs', headers={'Authorization': auth})
for pg in res.json()['list']:
    print(pg['pg'], [m['method'] for m in pg['methods']])python

RESELLER_AUTH=$(printf '%s' "$BOOTPAY_RESELLER_CLIENT_KEY:$BOOTPAY_RESELLER_SECRET_KEY" | base64)

curl "https://api.bootpay.co.kr/v2/reseller/pgs?pg=nicepay" -H "Authorization: Basic $RESELLER_AUTH"bash

1-3. 응답

{
  "list": [
    {
      "pg":      "nicepay",
      "pg_name": "나이스페이먼츠",
      "symbols": ["nicepay"],
      "methods": [
        {
          "method":            "card",
          "method_name":       "카드",
          "display_name":      "신용카드",
          "symbols":           ["card", "카드"],
          "group":             2,
          "sandbox_supported": true,
          "resource_keys": [
            { "key": "mid",        "description": "상점 아이디를 입력해주세요.",        "input_type": "input", "required": true },
            { "key": "mkey",       "description": "상점키를 입력해주세요.",             "input_type": "input", "required": true },
            { "key": "cancel_pwd", "description": "결제 취소 비밀번호를 입력해주세요.", "input_type": "input", "required": false }
          ]
        }
      ]
    }
  ]
}json

1-4. 에러 코드

2PG 리소스 갱신

프로젝트(app) 에 등록되어 있는 PG·결제수단·발급키를 갱신합니다. 신규 결제수단을 추가하거나 PG 사가 발급한 가맹점 키가 바뀌었을 때 호출합니다.

동작 규칙

• resources 배열에 포함된 결제수단은 추가 또는 갱신됩니다. 배열에 빠진 결제수단은 그대로 유지됩니다 — 전체 덮어쓰기가 아닙니다.
• 기존에 등록된 PG·결제수단 묶음에 같은 pg + method 조합이 들어오면 발급키만 갱신됩니다.
• sandbox: true 면 테스트 모드로 등록합니다. 테스트 결제는 부트페이가 결제수단마다 가진 테스트 키로 하므로, 연동 값이 아직 없으면 resource 없이 sandbox: true 만 보내도 됩니다. 운영으로 바꿀 때는 resource 와 sandbox: false(또는 생략)를 보냅니다.
• 원소에 status: "off" 를 보내면 그 결제수단을 끕니다(결제창에서 빠집니다). 지우지 않으므로 연동 값·기록이 남고, status: "on" 으로 다시 켤 수 있습니다. 켜기·끄기만 할 때는 resource 를 보내지 않아도 됩니다.
• 응답으로 프로젝트의 최신 정보(application_keys, payment_apps) 가 다시 내려옵니다. 프로젝트 비밀키(private_key)는 나오지 않고, 결제수단 resource 는 가린 값(앞 5자 + *****)입니다.
• 지금 붙어 있는 결제수단은 결제수단 목록, PG 마다 resource 에 넣을 키는 PG·필수 연동 값 목록 에서 확인합니다. 필수는 그 목록의 required: true 인 키만입니다(부트페이 관리자 화면과 같은 기준). 같은 PG 라도 결제수단마다 다릅니다 — 예: 나이스페이먼츠 카드는 mid·mkey, 카드자동은 mid·mkey·cancel_pwd.
• 같은 결제수단 심볼(예: card)을 여러 PG 로 한 요청에 보내도 각 원소는 그 원소의 pg 결제수단에 저장됩니다.
• 가맹점이나 리셀러가 결제 설정 잠금 을 켜 두었어도 이 API 는 그대로 동작합니다. 잠금은 가맹점 관리자 화면에서의 수정만 막습니다.

API 정보

2-1. 요청 파라미터

resources 배열 형식

결제수단 끄기·다시 켜기

status 만 보내면 연동 값은 그대로 두고 켜짐·꺼짐만 바꿉니다. 같은 요청에 연동 값을 바꿀 원소와 섞어 보내도 됩니다.

{
  "resources": [
    { "pg": "nicepay", "method": "카드자동", "status": "off" },
    { "pg": "nicepay", "method": "카드", "status": "on" }
  ]
}json

연동 값 없이 테스트 모드로 붙이기

PG 계약 전이라 연동 값이 없어도 sandbox: true 만 보내면 그 결제수단을 테스트 모드로 붙입니다(없으면 추가, 있으면 테스트 모드로 바꿉니다). 테스트 결제는 부트페이 테스트 키로 하고, 이미 저장된 연동 값·MID 기록은 그대로 둡니다. 테스트 모드를 지원하는지는 PG·필수 연동 값 목록 의 sandbox_supported 로 확인합니다.

{
  "resources": [
    { "pg": "nicepay", "method": "카드", "sandbox": true },
    { "pg": "nicepay", "method": "카드자동", "sandbox": true, "status": "on" }
  ]
}json

운영으로 바꿀 때는 PG 에서 받은 연동 값을 resource 에 넣고 sandbox: false 로 다시 보냅니다.

2-2. 코드 예제

import fetch from 'node-fetch'

const RESELLER_AUTH = 'Basic ' + Buffer
  .from(`${process.env.BOOTPAY_RESELLER_CLIENT_KEY}:${process.env.BOOTPAY_RESELLER_SECRET_KEY}`)
  .toString('base64')

const appId = '65a1c0ab8f1b5b00367a0010'

const res = await fetch(`https://api.bootpay.co.kr/v2/reseller/seller/app/resource/${appId}`, {
    method: 'PATCH',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': RESELLER_AUTH
    },
    body: JSON.stringify({
        resources: [
            {
                pg:     'nicepay',
                method: '카드',
                sandbox: false,
                resource: {
                    mid:          process.env.NICEPAY_MID,
                    mkey:         process.env.NICEPAY_MKEY
                }
            },
            {
                pg:     'nicepay',
                method: '카드자동',
                sandbox: false,
                resource: {
                    mid:          process.env.NICEPAY_MID,
                    mkey:         process.env.NICEPAY_MKEY,
                    cancel_pwd:   process.env.NICEPAY_CANCEL_PWD // 카드자동은 결제 취소 비밀번호도 필수
                }
            }
        ]
    })
})
const data = await res.json()
console.log(data)javascript

import base64, os, requests

auth = 'Basic ' + base64.b64encode(
    f"{os.environ['BOOTPAY_RESELLER_CLIENT_KEY']}:{os.environ['BOOTPAY_RESELLER_SECRET_KEY']}".encode()
).decode()

app_id = '65a1c0ab8f1b5b00367a0010'

payload = {
    'resources': [
        {
            'pg':     'nicepay',
            'method': '카드',
            'sandbox': False,
            'resource': {
                'mid':          os.environ['NICEPAY_MID'],
                'mkey':         os.environ['NICEPAY_MKEY']
            }
        },
        {
            'pg':     'nicepay',
            'method': '카드자동',
            'sandbox': False,
            'resource': {
                'mid':          os.environ['NICEPAY_MID'],
                'mkey':         os.environ['NICEPAY_MKEY'],
                'cancel_pwd':   os.environ['NICEPAY_CANCEL_PWD']  # 카드자동은 결제 취소 비밀번호도 필수
            }
        }
    ]
}

res = requests.patch(
    f'https://api.bootpay.co.kr/v2/reseller/seller/app/resource/{app_id}',
    json=payload,
    headers={'Authorization': auth}
)
print(res.json())python

RESELLER_AUTH=$(printf '%s' "$BOOTPAY_RESELLER_CLIENT_KEY:$BOOTPAY_RESELLER_SECRET_KEY" | base64)
APP_ID='65a1c0ab8f1b5b00367a0010'

curl -X PATCH "https://api.bootpay.co.kr/v2/reseller/seller/app/resource/$APP_ID" \
  -H "Authorization: Basic $RESELLER_AUTH" \
  -H 'Content-Type: application/json' \
  -d '{
    "resources": [
      {
        "pg": "nicepay",
        "method": "카드",
        "sandbox": false,
        "resource": {
          "mid": "'"$NICEPAY_MID"'",
          "mkey": "'"$NICEPAY_MKEY"'"
        }
      },
      {
        "pg": "nicepay",
        "method": "카드자동",
        "sandbox": false,
        "resource": {
          "mid": "'"$NICEPAY_MID"'",
          "mkey": "'"$NICEPAY_MKEY"'",
          "cancel_pwd": "'"$NICEPAY_CANCEL_PWD"'"
        }
      }
    ]
  }'bash

2-3. 응답

프로젝트의 최신 상태가 내려옵니다. 프로젝트 비밀키(private_key)는 프로젝트 생성·키 재발급 응답에서만 나오므로 여기에는 없고, resource 는 가린 값입니다.

{
  "app_id":   "65a1c0ab8f1b5b00367a0010",
  "app_name": "한입가게 — 정기구독",
  "real":     { "name": "비실물", "value": 0, "desc": "" },
  "unit":     "KRW",
  "application_keys": [
    { "type": 1, "name": "WEB",     "key": "65a1c0ab8f1b5b00367a0011" },
    { "type": 2, "name": "Android", "key": "65a1c0ab8f1b5b00367a0012" },
    { "type": 3, "name": "iOS",     "key": "65a1c0ab8f1b5b00367a0013" },
    { "type": 4, "name": "REST",    "key": "65a1c0ab8f1b5b00367a0014" }
  ],
  "payment_apps": [
    {
      "payment_resource_id": "65a1c0ab8f1b5b00367a0015",
      "pg_id":               "6098a1b2c3d4e5f600000101",
      "pg_name":             "나이스페이먼츠",
      "pg_alias":            "nicepay",
      "method_id":           "6098a1b2c3d4e5f600000201",
      "method_name":         "카드",
      "method_alias":        "card",
      "resource_mode":       null,
      "sandbox_mode":        false,
      "easypay":             false,
      "updated_at":          "2024-01-12T18:04:11+09:00",
      "status":              1,
      "resource": {
        "mid":          "nicep*****",
        "mkey":         "EYzu8*****"
      }
    },
    {
      "payment_resource_id": "65a1c0ab8f1b5b00367a0016",
      "pg_id":               "6098a1b2c3d4e5f600000101",
      "pg_name":             "나이스페이먼츠",
      "pg_alias":            "nicepay",
      "method_id":           "6098a1b2c3d4e5f600000202",
      "method_name":         "카드자동",
      "method_alias":        "card_rebill",
      "resource_mode":       null,
      "sandbox_mode":        false,
      "easypay":             false,
      "updated_at":          "2024-01-12T18:04:11+09:00",
      "status":              0,
      "resource": {
        "mid":          "nicep*****",
        "mkey":         "EYzu8*****",
        "cancel_pwd":   "pw123*****"
      }
    }
  ],
  "status": 20
}json

응답 파라미터

2-4. 동작 규칙

2-5. 에러 코드

3결제수단 목록

하위 프로젝트에 설정된 결제수단을 모두 돌려줍니다. 켜진 것과 꺼 둔 것이 함께 나옵니다. 결제수단을 붙이거나 끄고 켜는 것은 PG 리소스 갱신 으로 합니다.

동작 규칙

• status 가 1 이면 켜짐(결제창에 나옵니다), 0 이면 꺼짐입니다. 꺼 둔 결제수단도 연동 값과 기록이 그대로 남아 있어 다시 켤 수 있습니다.
• resource 는 키 이름은 그대로, 값은 가린 값​​입니다(앞 5자 + *****, 10자보다 짧은 값은 앞 절반 + *****). PG 가맹점 키 원문이 응답에 실리는 곳은 가맹점 생성 뿐이고, 그 밖의 리셀러 API 는 가린 값만 줍니다.
• sandbox_mode 가 true 면 테스트 모드입니다.
• cert_expire_at 은 인증서가 필요한 결제수단(예: KCP 휴대폰 자동결제)의 가장 이른 인증서 만료 시각입니다. 인증서가 없으면 null 입니다.
• 프로젝트를 만들 때 함께 붙는 부트페이 기본 결제수단(테스트 모드)도 목록에 나옵니다.
• payment_setting_lock 은 이 프로젝트의 결제 설정 잠금 상태입니다(가맹점 잠금 seller_locked · 리셀러 잠금 reseller_locked). 잠금과 상관없이 리셀러 API 로는 결제수단을 바꿀 수 있습니다 — 결제 설정 잠금

API 정보

3-1. 요청 파라미터

3-2. 코드 예제

import fetch from 'node-fetch'

const RESELLER_AUTH = 'Basic ' + Buffer
  .from(`${process.env.BOOTPAY_RESELLER_CLIENT_KEY}:${process.env.BOOTPAY_RESELLER_SECRET_KEY}`)
  .toString('base64')

const appId = '65a1c0ab8f1b5b00367a0010'
const res = await fetch(`https://api.bootpay.co.kr/v2/reseller/seller/app/${appId}/payment-methods`, {
    headers: { 'Authorization': RESELLER_AUTH }
})
const { list } = await res.json()
console.log(list.filter(pm => pm.status === 1).map(pm => `${pm.pg_alias}/${pm.method_alias}`))javascript

import base64, os, requests

auth = 'Basic ' + base64.b64encode(
    f"{os.environ['BOOTPAY_RESELLER_CLIENT_KEY']}:{os.environ['BOOTPAY_RESELLER_SECRET_KEY']}".encode()
).decode()

res = requests.get('https://api.bootpay.co.kr/v2/reseller/seller/app/65a1c0ab8f1b5b00367a0010/payment-methods', headers={'Authorization': auth})
print(res.json())python

RESELLER_AUTH=$(printf '%s' "$BOOTPAY_RESELLER_CLIENT_KEY:$BOOTPAY_RESELLER_SECRET_KEY" | base64)

curl "https://api.bootpay.co.kr/v2/reseller/seller/app/65a1c0ab8f1b5b00367a0010/payment-methods" \
  -H "Authorization: Basic $RESELLER_AUTH"bash

3-3. 응답

{
  "app_id": "65a1c0ab8f1b5b00367a0010",
  "list": [
    {
      "payment_resource_id": "65a1c0ab8f1b5b00367a0015",
      "pg_id":               "6098a1b2c3d4e5f600000101",
      "pg_name":             "나이스페이먼츠",
      "pg_alias":            "nicepay",
      "method_id":           "6098a1b2c3d4e5f600000201",
      "method_name":         "카드",
      "method_alias":        "card",
      "resource_mode":       null,
      "sandbox_mode":        false,
      "easypay":             false,
      "updated_at":          "2026-10-27T10:00:00+09:00",
      "status":              1,
      "resource": {
        "mid":          "nicep*****",
        "mkey":         "EYzu8*****"
      },
      "cert_expire_at": null
    }
  ],
  "payment_setting_lock": {
    "seller_locked":       false,
    "seller_changed_at":   null,
    "reseller_locked":     true,
    "reseller_changed_at": "2026-10-29T15:00:00+09:00"
  }
}json

3-4. 에러 코드

4결제 설정 잠금

하위 프로젝트의 결제 설정을 리셀러가 잠그거나 풉니다. 잠기면 가맹점은 부트페이 관리자 화면에서 결제수단을 켜고 끄거나, 테스트 모드(샌드박스)를 바꾸거나, 연동 값(MID 등)을 저장할 수 없습니다.

동작 규칙

• 잠금은 프로젝트(app_id) 하나에 걸립니다. 그 프로젝트의 모든 결제수단에 적용됩니다.
• 가맹점은 이 잠금을 풀 수 없습니다. 가맹점 화면에는 "리셀러가 잠가 둔 결제 설정"이라고 보이고, 바꾸려면 리셀러에게 문의하라고 안내됩니다.
• 가맹점도 자기 화면에서 따로 잠글 수 있습니다(가맹점 잠금). 두 잠금은 서로 다른 값입니다 — 이 API 는 리셀러 잠금만 바꾸고, 가맹점 잠금이 켜져 있어도 리셀러 잠금을 바꿀 수 있습니다.
• 리셀러 API 는 두 잠금과 상관없이 동작합니다. PG 리소스 갱신(결제수단 추가·연동 값 갱신·켜기·끄기)은 리셀러 잠금이나 가맹점 잠금이 켜져 있어도 그대로 됩니다.
• 지금 잠금 상태는 결제수단 목록·프로젝트 조회 응답의 payment_setting_lock 으로도 볼 수 있습니다.
• 리셀러 관리자 콘솔의 하위 가맹점 상세 화면에서도 프로젝트마다 잠그고 풀 수 있습니다.

API 정보

4-1. 요청 파라미터

4-2. 코드 예제

import fetch from 'node-fetch'

const RESELLER_AUTH = 'Basic ' + Buffer
  .from(`${process.env.BOOTPAY_RESELLER_CLIENT_KEY}:${process.env.BOOTPAY_RESELLER_SECRET_KEY}`)
  .toString('base64')

const appId = '65a1c0ab8f1b5b00367a0010'
const res = await fetch(`https://api.bootpay.co.kr/v2/reseller/seller/app/${appId}/payment-lock`, {
    method:  'PUT',
    headers: { 'Authorization': RESELLER_AUTH, 'Content-Type': 'application/json' },
    body:    JSON.stringify({ locked: true })
})
const { payment_setting_lock } = await res.json()
console.log(payment_setting_lock.reseller_locked) // truejavascript

import base64, os, requests

auth = 'Basic ' + base64.b64encode(
    f"{os.environ['BOOTPAY_RESELLER_CLIENT_KEY']}:{os.environ['BOOTPAY_RESELLER_SECRET_KEY']}".encode()
).decode()

res = requests.put(
    'https://api.bootpay.co.kr/v2/reseller/seller/app/65a1c0ab8f1b5b00367a0010/payment-lock',
    headers={'Authorization': auth},
    json={'locked': True}
)
print(res.json()['payment_setting_lock'])python

RESELLER_AUTH=$(printf '%s' "$BOOTPAY_RESELLER_CLIENT_KEY:$BOOTPAY_RESELLER_SECRET_KEY" | base64)

curl -X PUT "https://api.bootpay.co.kr/v2/reseller/seller/app/65a1c0ab8f1b5b00367a0010/payment-lock" \
  -H "Authorization: Basic $RESELLER_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"locked": true}'bash

4-3. 응답

{
  "app_id": "65a1c0ab8f1b5b00367a0010",
  "payment_setting_lock": {
    "seller_locked":       false,
    "seller_changed_at":   null,
    "reseller_locked":     true,
    "reseller_changed_at": "2026-10-29T15:00:00+09:00"
  }
}json

4-4. 잠기면 가맹점 화면에서 막히는 것

막힌 동작을 가맹점이 시도하면 PM_RESELLER_SETTING_LOCKED(8220, "리셀러가 잠가 둔 결제 설정입니다. 바꾸려면 리셀러에게 문의해 주세요.")로 거절됩니다. 리셀러 API 와 부트페이 운영팀의 처리는 막지 않습니다.

4-5. 에러 코드