빌링계정 API - 결제 수단 생성 #

1. API Overview #

Target Coverage #

Purpose #

Details #

[!INFO] 빌링 계정 생성 시점
빌링 계정은 별도의 가입 절차 없이, 사용자가 최초로 토큰을 등록하거나 결제를 요청할 때 전달된 스토어 ID(X-Store-Id)와 사용자 번호(userNo)를 기준으로 시스템에 자동 생성됩니다.

2. Request Specification #

2.1 Request Header #

상세한 헤더 정보는 Common Headers 문서를 참고하세요.

2.2 Request Data Schema #

직불계좌 결제 정보 (directDebitType) 안내

태국 직불계좌 결제(DIRECT_DEBIT) 이용 시 다음의 지원 은행 코드를 확인하십시오.

• direct_debit_bay (Krungsri Bank)
• direct_debit_kbank (Kasikorn Bank)
• direct_debit_ktb (Krungthai Bank)
• direct_debit_scb (Siam Commercial Bank)

2.3 Request Examples #

JSON Example #

{
  "userNo": "AU1234567890",
  "userId": "gildong.hong@example.com",
  "email": "gildong.hong@example.com",
  "paymentMethod": "CARD",
  "successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/success",
  "failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/failure"
}

{
  "userNo": "TH1234567890",
  "userId": "gildong.hong@example.com",
  "email": "gildong.hong@example.com",
  "paymentMethod": "DIRECT_DEBIT",
  "successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/success",
  "failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/failure",
  "directDebitType": "direct_debit_bay"
}

3. Response Specification #

3.1 Response Data Schema #

Response Data Schema #

3.2 Response Samples #

Case 1: Worldpay 카드 등록 (리다이렉트 + 웹훅 완료) #

PG사의 결제 페이지(HPP)를 통해 카드 정보를 입력받는 방식입니다. 사용자가 정보를 입력하면 PG사에서 EBP로 웹훅을 보내 등록이 최종 완료됩니다.

• Next Step: REDIRECT (PG사 HPP로 이동 필요)
• Completion: WEBHOOK (사용자 인증 완료 후 웹훅에 의해 비동기로 완료됨)

{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06EFX0CRR7ME0KCSSTFEEDRDVG",
  "timestamp": "2026-01-27T04:39:47.222978900Z",
  "data": {
    "paymentMethodId": "3e104ef7b98f4123948a8c248d0da4c5",
    "orderNo": "ORD_7202603277730794",
    "status": "ACTION_REQUIRED",
    "paymentUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/wrapping",
    "paymentHeaderContext": "eyJhY3Rpb24iOiJSRURJUkVDVF9UT19IUFAiLCJwcm92aWRlciI6IldPUkxEUEFZIiwiY29udGV4dCI6I...",
    "pgResponse": {
      "resultCode": "PASS",
      "data": {
        "pgRefId": "3579052412",
        "returnUrl": "https://payments-test.worldpay.com/app/hpp/...",
        "referenceUrl": "https://payments-test.worldpay.com/app/hpp/..."
      }
    },
    "successUrl": "http://<yourhost>/v2/ebp/test/token/success",
    "failureUrl": "http://<yourhost>/v2/ebp/test/token/fail"
  },
  "instructions": {
    "nextStep": "REDIRECT",
    "completionMethod": "WEBHOOK",
    "requiresClientAction": true,
    "clientAction": {
      "type": "REDIRECT_TO_HPP",
      "pgProvider": "WORLDPAY"
    },
    "requiresFollowUpApi": false
  }
}

Case 2: Omise 카드 등록 (클라이언트 액션 + API 완료) #

클라이언트가 Omise JS SDK를 사용하여 카드 정보를 직접 토큰화하는 방식입니다. 획득한 토큰을 EBP의 등록 완료 API로 전달하여 등록을 확정합니다.

• Next Step: CLIENT_ACTION (JS SDK 호출 및 토큰 획득 필요)
• Completion: API (획득한 토큰을 사용하여 결제 수단 등록 완료 API 호출 필요)

{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06EFWD32XT8HCBDCYR9RK7R0PC",
  "timestamp": "2026-01-27T04:39:50.123456700Z",
  "data": {
    "paymentMethodId": "3a9437e612ac4ccb9beaa6585e899321",
    "orderNo": "ORD_7202603277730795",
    "status": "ACTION_REQUIRED",
    "paymentUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/card/wrapping",
    "paymentHeaderContext": "eyJhY3Rpb24iOiJUT0tFTklaRV9DQVJEIiwicHJvdmlkZXIiOiJPTUlTRSIsImNvbnRleHQiOiI...",
    "pgResponse": {
      "resultCode": "SUCCESS",
      "data": {
        "publicKey": "pkey_test_46lmsec8z06uh..."
      }
    }
  },
  "instructions": {
    "nextStep": "CLIENT_ACTION",
    "completionMethod": "API",
    "requiresClientAction": true,
    "clientAction": {
      "type": "TOKENIZE_CARD",
      "pgProvider": "OMISE"
    },
    "requiresFollowUpApi": true,
    "followUpApi": {
      "method": "POST",
      "url": "/api/v2/payment-methods/3a9437e612ac4ccb9beaa6585e899321/complete",
      "description": "카드 토큰화 완료 후 이 API를 호출하여 등록을 확정해야 합니다."
    }
  }
}

Case 3: Omise 직불계좌 등록 (클라이언트 액션 + 인증 필요) #

클라이언트가 Omise JS SDK를 사용하여 계좌 정보를 소스화(SourceId 생성)하는 방식입니다. 획득한 소스 ID를 사용하여 응답받은 paymentUrl을 통해 사용자가 은행 인증을 진행하게 됩니다. 최종 등록은 인증 완료 후 웹훅을 통해 처리됩니다.

• 1단계 (현재 API): CLIENT_ACTION (JS SDK 호출 및 SourceId 획득 필요)
• 2단계 (인증): 응답받은 paymentUrl로 사용자 리다이렉트 및 은행 인증
• 최종 완료: WEBHOOK (사용자 인증 완료 후 웹훅에 의해 비동기로 활성화됨)

{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06EP2JWT2DHQEQGBC3W3RRK72W",
  "timestamp": "2026-04-06T05:37:22.536Z",
  "data": {
    "paymentMethodId": "1fc83f065287471987ee754ef01e7d40",
    "orderNo": "ORD_7202603277730796",
    "status": "ACTION_REQUIRED",
    "paymentUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/direct-debit/wrapping",
    "paymentHeaderContext": "eyJhY3Rpb24iOiJDUkVBVEVfU09VUkNFIiwicHJvdmlkZXIiOiJPTUlTRSIsImNvbnRleHQiOiI...",
    "successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/success",
    "failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/failure",
    "pgResponse": {
      "resultCode": "OK",
      "pgProvider": "OMISE",
      "data": {
        "type": "OMISE_DIRECT_DEBIT",
        "linkedAccountId": "lnac_test_679grm7z8axarr41r6m",
        "registrationUri": "https://pay.omise.co/registrations/linked_accounts/lnac_test_679grm7z8axarr41r6m/authorize"
      }
    }
  },
  "instructions": {
    "nextStep": "CLIENT_ACTION",
    "completionMethod": "WEBHOOK",
    "requiresClientAction": true,
    "clientAction": {
      "type": "CREATE_SOURCE",
      "pgProvider": "OMISE"
    },
    "requiresFollowUpApi": false
  }
}