에스크로 연동

에스크로 연동은 ① 결제창을 에스크로로 띄우고, ② 발송 시 배송정보를 전송하고, ③ 구매확정/거절 통지를 처리하는 세 단계로 이뤄져요. 전체 개념과 상태값은 에스크로 개요를 먼저 확인해요.

1에스크로 결제 요청 (프론트엔드)

일반 결제 요청에 extra.escrow: true만 추가하면 에스크로 결제가 돼요. 배송지가 필요하므로 user에 주소 정보를 함께 보내요.

import { Bootpay } from '@bootpay/client-js'

async function requestEscrowPayment() {
    const response = await Bootpay.requestPayment({
        client_key: '[ Client Key ]',
        pg: '이니시스',
        method: 'card',
        order_name: '원목 식탁',
        order_id: 'order_' + Date.now(),
        price: 150000,
        user: {
            username: '홍길동',
            phone: '01012345678',
            addr: '서울특별시 종로구 ...',   // 에스크로는 배송지 정보가 필요해요
        },
        extra: {
            escrow: true,                    // 에스크로 결제 활성화
        },
    })

    if (response.event === 'done') {
        // 결제 완료 → 서버 검증 후 '배송 준비' 상태로 주문 저장
        await verifyPayment(response.receipt_id)
    }
}javascript

결제 요청 파라미터 전반은 결제창 통합 가이드와 같아요. 서버 검증은 결제 조회를 참고해요.

2배송정보 전송 (서버)

상품을 발송하면 택배사·송장번호·배송지를 등록해요. 이 호출로 에스크로 상태가 배송시작(3)으로 바뀌고, 구매자에게 구매확정 안내가 전달돼요.

이니시스가 인식하는 delivery_corp 값​: CJ대한통운 한진 롯데 KGB 우체국 로젠 CJGLS 대신 일양로지스 호남 합동 천일 편의점 경동 기타

KCP가 인식하는 값​: 위 목록에 동부 옐로우캡 사가와 직접배달 퀵서비스 추가 (CJGLS 는 없음)

curl -X PUT "https://api.bootpay.co.kr/v2/escrow/shipping/start/RECEIPT_ID" \
  -H "Authorization: Basic $(printf '%s' 'CLIENT_KEY:SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "123456789",
    "delivery_corp": "CJ대한통운",
    "shipping_day": 2,
    "user": {
      "username": "홍길동",
      "phone": "01012345678",
      "address": "서울특별시 종로구 ...",
      "zipcode": "03000"
    },
    "company": {
      "name": "부트가구",
      "phone": "0233334444",
      "addr1": "서울특별시 종로구 ...",
      "addr2": "종로빌딩 3층"
    }
  }'bash

import { Bootpay } from '@bootpay/backend-js'

Bootpay.setConfiguration({
    client_key: process.env.BOOTPAY_CLIENT_KEY,
    secret_key: process.env.BOOTPAY_SECRET_KEY,
})

const response = await Bootpay.shippingStart({
    receipt_id: '[ receipt_id ]',
    tracking_number: '123456789',
    delivery_corp: 'CJ대한통운',
    shipping_day: 2,
    user: {
        username: '홍길동',
        phone: '01012345678',
        address: '서울특별시 종로구 ...',
        zipcode: '03000',
    },
    company: {
        name: '부트가구',
        phone: '0233334444',
        addr1: '서울특별시 종로구 ...',
        addr2: '종로빌딩 3층',
    },
})
console.log(response.escrow_data.status) // 3: 배송시작javascript

응답 예시

배송정보 전송 응답은 결제 조회와 동일한 영수증 전체 payload 이며, 그 안에 escrow_data 가 포함돼요.

{
  "receipt_id":    "6244f60c1fc19202e42e8c4e",
  "order_id":      "order_1700000000",
  "price":         150000,
  "tax_free":      0,
  "order_name":    "원목 식탁",
  "company_name":  "부트가구",
  "method":        "카드",
  "method_symbol": "card",
  "purchased_at":  "2026-06-13T11:02:00+09:00",
  "requested_at":  "2026-06-13T11:01:41+09:00",
  "status_locale": "결제완료",
  "status":        1,
  "currency":      "KRW",
  "escrow_data": {
    "status":              3,
    "status_locale":       "배송시작",
    "shipping_started_at": "2026-06-14T14:13:43+09:00",
    "escrow_confirm_url":  "https://door.bootpay.co.kr/escrow/..."
  }
}json

escrow_data 필드는 다음과 같아요.

3구매확정 / 거절 통지

배송이 시작되면 구매자가 상품을 받고 구매확정 또는 거절(반품)​​을 선택해요. 상태 변경은 두 경로로 통지돼요.

• 웹훅​: 에스크로 상태가 바뀌면 등록한 웹훅 URL로 통지돼요. 배송정보 전송·구매확정·구매거절·거절승인 모두 이 웹훅으로 통지돼요. 페이로드는 결제 웹훅과 같은 영수증 전체 payload 에 webhook_type: "ESCROW_STATUS_CHANGED", application_id, escrow_webhook: true, escrow_data 가 더해진 형태이고, 빌링키로 결제한 건이면 billing_key 에 빌링키 ID 가 담겨요. 에스크로 상태값은 escrow_data.status 하나만 보면 돼요 — 최상위에는 상태 필드가 없어요.
• webhook_type 은 API 버전 2.5 이상에서만 채워져요​: 에스크로 웹훅은 결제 웹훅과 달리 빈 값을 걸러내지 않아서, 2.5 미만 프로젝트에서는 webhook_type 키가 빠지는 대신 null 로 내려와요(billing_key 도 빌링 건이 아니면 null). webhook_type 만 보고 분기하면 에스크로 웹훅을 놓칠 수 있으니 escrow_webhook: true 도 함께 확인해요.
• 결제 조회​: 언제든 GET /v2/receipt/{receipt_id}로 현재 escrow_data.status를 확인할 수 있어요.

{
  "webhook_type": "ESCROW_STATUS_CHANGED",
  "receipt_id": "6244f60c1fc19202e42e8c4e",
  "order_id": "order_1700000000",
  "price": 150000,
  "order_name": "원목 식탁",
  "status_locale": "결제완료",
  "status": 1,
  "application_id": "65a1c0ab8f1b5b00367a0003",
  "escrow_webhook": true,
  "escrow_data": {
    "status": 1,
    "status_locale": "구매확정",
    "shipping_started_at": "2026-06-14T14:13:43+09:00",
    "receipt_confirmed_at": "2026-06-16T10:02:11+09:00"
  }
}json

상태별 처리

에러 코드

다음 단계

• 상태 변경 통지 처리는 웹훅을 확인해요.
• 거절(구매취소) 시 환불은 결제 취소을 참고해요.
• 택배사 코드는 택배사 목록을 확인해요.