빌링계정 API - 결제 수단 등록 완료 #
1. API Overview #
Target Coverage #
| PG | 결제 수단 (Payment Method) |
|---|---|
| Omise | Card |
Purpose #
결제 수단 등록 API 응답의 nextStep 필드 값이 CLIENT_ACTION이고, completionMethod 필드 값이 API인 경우 호출하는 API입니다.
현재 시스템에서는 Omise PG의 카드(CARD) 결제 수단 등록 시에만 이 API 호출이 필요합니다.
지시된 클라이언트 액션(카드 토큰화)을 수행 완료한 후 그 결과값(token)을 서버에 전달하여 결제 수단을 최종 확정합니다.
Details #
| 항목 | 값 |
|---|---|
| API Name | 결제 수단 등록 완료 |
| API Path | /api/v2/payment-methods/{paymentMethodId}/complete |
| API ID | EBP_API_121 |
| HTTP Method | POST |
| Region | Global |
2. Request Specification #
2.1 Request Header #
상세한 헤더 정보는 Common Headers 문서를 참고하세요.
Custom Headers #
| Field | Details & Description |
|---|---|
| x-ebp-context |
🔴 Required 결제 수단 생성 API( |
2.2 Path Parameters #
| Field | Details & Description |
|---|---|
| paymentMethodId |
🔴 Required 등록을 완료할 결제 수단 ID (Register API 응답값) |
2.3 Request Data Schema #
| depth | Field | Details & Description |
|---|---|---|
| 0 | paymentMethod |
🔴 Required 결제 수단 코드 e.g., CARD |
| 0 | paymentInstrumentId |
🔴 Required PG사 SDK를 통해 획득한 일회성 토큰 ID |
| 0 | paymentInstrumentType |
🔴 Required 결제 수단 정보의 유형 e.g., ONE_TIME_TOKEN |
| 0 | paymentMethodContext |
🔴 Required 결제 수단 등록 API 응답에서 받은 암호화된 컨텍스트 데이터 |
2.4 Request Examples #
{
"paymentMethod": "CARD",
"paymentInstrumentId": "tok_test_5w6v4d1d4c1...",
"paymentInstrumentType": "ONE_TIME_TOKEN",
"paymentMethodContext": "eyJhY3Rpb24iOiJUT0tFTklaRV9DQVJEIiwidG9rZW4iOiJ0b2tf..."
}
3. Response Specification #
3.1 Response Data Schema #
Response Data Schema #
| depth | Field | Details & Description |
|---|---|---|
| -1 | resultCode |
🔴 Required 결과 코드 (성공 "0", 에러 시 "EBP-A-0001" 등) |
| -1 | message |
🔴 Required 결과 메시지 (성공 또는 에러 상세) |
| -1 | requestId |
🔴 Required 추적을 위한 고유 요청 ID |
| -1 | timestamp |
🔴 Required ISO 8601 형식의 응답 타임스탬프 e.g., 2025-12-19T14:24:00+09:00 |
| -1 | data |
🔴 Required 응답 데이터 (비즈니스 결과물) |
| 0 | paymentMethodId |
🔴 Required 결제 수단 고유 식별자 |
| 0 | status |
🔴 Required 현재 결제 수단 상태 e.g., ACTIVE |
| 0 | paymentUrl |
⚪ Optional 추가 인증(HPP 등)이 필요한 경우 사용자를 리다이렉트시킬 EBP 표준 URL입니다. |
| 0 | pgResponse |
⚪ Optional PG사 응답 상세 정보 객체 |
| 1 | resultCode |
⚪ Optional PG사 자체 응답 코드 |
| 1 | pgProvider |
⚪ Optional PG사 식별자 e.g., OMISE |
| 1 | data |
⚪ Optional PG사 응답 데이터 상세. 상세 내용은 하단의 PG별 상세 응답 안내를 참조하십시오. |
| -1 | instructions |
🔴 Required 후속 처리를 위한 지침 (프로세스 제어) |
| 0 | nextStep |
🔴 Required 추가 인증이 필요한 경우의 다음 행동 지시 e.g., NONE |
| 0 | requiresClientAction |
🔴 Required 클라이언트 추가 액션(HPP 이동 등)이 필요한지 여부 |
| 0 | clientAction |
⚪ Optional 클라이언트의 추가 액션 지시 정보 객체. |
| 1 | type |
⚪ Optional 클라이언트 액션 유형 e.g., REDIRECT_TO_HPP |
| 1 | pgProvider |
⚪ Optional 액션을 처리할 PG사 |
| 0 | requiresFollowUpApi |
🔴 Required 후속 API 호출이 필수인지 여부 |
| 0 | followUpApi |
⚪ Optional 추가 액션 완료 후 호출해야 할 후속 API 정보. |
참고: 현재 시스템에서는 본 API 호출 후 추가적인 클라이언트 액션이나 후속 API 호출이 필요한 케이스는 존재하지 않습니다. (
instructions.requiresClientAction,instructions.requiresFollowUpApi는 항상false,instructions.nextStep은 항상NONE) 다만, 다른 API와의 일관성 및 향후 확장성을 위해 해당 필드들을 포함하고 있습니다.
3.2 PG별 상세 응답 (pgResponse) 안내 #
PG사 및 결제 수단별로 pgResponse.data 객체의 구성이 상이합니다.
Omise - Card (카드) #
| Field | Details & Description |
|---|---|
| type |
🔴 Required 응답 데이터 유형 e.g., OMISE_CARD_CUSTOMER |
| cardId |
🔴 Required PG사 카드 식별 ID (뒤 5자리 마스킹 처리) |
| customerId |
🔴 Required PG사 고객 식별 ID (뒤 5자리 마스킹 처리) |
| createdAt |
🔴 Required 데이터 생성 시각 e.g., 2026-04-09T14:13:44Z |
3.3 Response Samples #
Success Case: 카드 등록 즉시 완료 (Active) #
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EQ59HTGK7KYSEHV68ZZEY1C0",
"timestamp": "2026-04-09T14:29:50.381Z",
"data": {
"paymentMethodId": "7967a291ff954b23acca7e0caeb648b9",
"status": "ACTIVE",
"paymentUrl": null,
"pgResponse": {
"resultCode": "OK",
"pgProvider": "OMISE",
"data": {
"type": "OMISE_CARD_CUSTOMER",
"cardId": "card_test_67as23ugo5x0of*****",
"customerId": "cust_test_67as22ax1gdv91*****",
"createdAt": "2026-04-09T14:13:44Z"
}
}
},
"instructions": {
"nextStep": "NONE",
"requiresClientAction": false,
"requiresFollowUpApi": false
}
}