EBP API Docs v0.5.12
KR

구매 API - 결제 생성 #

1. API Overview #

Purpose #

이 API는 실제 결제 리소스를 생성하고, 최종적인 승인 및 매입 프로세스를 완료합니다.
결제 의사 생성 응답의 completionMethod가 API인 경우 호출하며, 이전 단계에서 발급된 암호화된 컨텍스트(paymentContext)와 PG 인증 정보(Token, Source 등)를 함께 전달해야 합니다.
특히, 요청 시 필수 필드인 authRequestId와 authSignature는 연동 방식에 따라 다음의 경로로 발급된 값을 반드시 사용해야 합니다.

  • 저장된 결제 수단: 사전에 완료된 결제 비밀번호 확인 API의 결과값 사용
  • 그 외 일반 결제: 결제 의사 생성 API의 응답(pgResponse.data)으로 발급된 결과값 사용

Details #

항목값
API Name결제 생성
API Path/api/v2/payments
API IDEBP_API_230
HTTP MethodPOST
RegionGlobal

2. Request Specification #

2.1 Request Header #

depthFieldDetails & Description
0X-EBP-Context

string

🔴 Required

결제 의사 생성 API의 응답으로 받은 data.paymentHeaderContext 값입니다.

0X-Idempotency-Key

string

🔴 Required

동일한 결제 생성 요청에 대한 중복 처리를 방지하기 위한 멱등 키

2.2 Request Data Schema #

모든 유형의 결제 수단에 대해 요청 구조가 통합되어 있습니다.

depthFieldDetails & Description
0authRequestId

string

🔴 Required

인증 성공 또는 결제 준비 시 발급되는 고유 식별자. 저장된 결제수단(SAVED_PAYMENT_METHOD)은 '결제 비밀번호 확인 API'의 data.requestId 값을, 그 외 일반 결제는 '결제 의사 생성 API'의 data.pgResponse.data.authRequestId 값을 사용합니다.

0authSignature

string

🔴 Required

authRequestId에 대한 보안 서명 값. 저장된 결제수단(SAVED_PAYMENT_METHOD)은 '결제 비밀번호 확인 API'의 data.signature 값을, 그 외 일반 결제는 '결제 의사 생성 API'의 data.pgResponse.data.authSignature 값을 사용합니다.

0paymentMethod

string

🔴 Required

사용된 결제 수단 (예: CARD, DIRECT_DEBIT).

0paymentInstrumentId

string

🔴 Required

결제 수단 식별자. PG 토큰, 소스 ID 또는 EBP에 저장된 결제수단 ID가 될 수 있다.

0paymentInstrumentType

string

🔴 Required

제공된 식별자의 유형.

e.g., ONE_TIME_TOKEN, ONE_TIME_SOURCE, SAVED_PAYMENT_METHOD
0paymentContext

string

🔴 Required

결제 의사 생성 API에서 받은 암호화된 결제 컨텍스트. 주문 및 세션 정보를 복원하는 데 사용된다.

0initiatedType

string

⚪ Optional

거래를 시작한 주체 (CUSTOMER 또는 MERCHANT).

e.g., CUSTOMER
0billingAddress

object

⚪ Optional

부정거래 검증(FDS)을 위한 Billing Address 정보.

1firstName

string

⚪ Optional

구매자의 이름

1lastName

string

⚪ Optional

구매자의 성

1addressLine1

string

🔴 Required

첫 번째 기본 주소

1addressLine2

string

⚪ Optional

두 번째 보조 주소

1city

string

🔴 Required

도시 이름

1stateOrProvince

string

⚪ Optional

주 또는 성의 이름

1postalCode

string

🔴 Required

우편번호

1countryCode

string

🔴 Required

ISO 3166-1 표준에 따른 국가 코드

1phoneNumber

string

⚪ Optional

구매자의 전화번호

2.3 Request Examples #

JSON Example #

One-Time Token : Card
One-Time Source : Installment (Thailand)
One-Time Source : Bank Transfer (Thailand)
Saved Method
{
  "authRequestId": "06EKTCYP2Q4GP462WH2Q53WQK0",
  "authSignature": "srpLIW9X8WbU7ebDix8uZD6jrKo0fNufPmIS643Ie4I=",
  "paymentContext": "QfAy+og0Pc7OaUKV92YAcDd+mvVFP+R5/p2YmxXD4...",
  "paymentMethod": "CARD",
  "paymentInstrumentId": "tokn_test_676q2zf3cn4bduksgow",
  "paymentInstrumentType": "ONE_TIME_TOKEN",
  "initiatedType": "CUSTOMER"
}

{
  "authRequestId": "06EN49J7PZK1V01T0XPX222ZZ4",
  "authSignature": "sf7IBgCG3KkXQPDE58+XEUzSa/XrzUY2+wHeYB9Pmos=",
  "paymentContext": "QfAy+og0Pc7OaUKV92YAcMX1fkli8RHkegtbrY9S63tDWhV/...",
  "paymentMethod": "INSTALLMENT",
  "paymentInstrumentId": "src_test_678bcrzd2xisbinnuya",
  "paymentInstrumentType": "ONE_TIME_SOURCE"
}

{
  "authRequestId": "06EN4A99K70F6ZFNF3JY0PXEC0",
  "authSignature": "czPZUs/zmdaQcjkknHGSwrkGbmemA1rS1txGz1Nzp4A=",
  "paymentContext": "QfAy+og0Pc7OaUKV92YAcLodPeyDSsE9PhRTbqZ2osZDWhV/+...",
  "paymentMethod": "BANK_TRANSFER",
  "paymentInstrumentId": "src_test_678bdvr1nzpud7qb7r9",
  "paymentInstrumentType": "ONE_TIME_SOURCE"
}

{
  "authRequestId": "06EDP0W5343S17MGFGESCG0JV0",
  "authSignature": "0aOw85SbsSb3Lg8JNzwCwMpo/+gD1qfdej1f5x7knZU=",
  "paymentContext": "GAkdwQJ8gx5w6IbCtGxTwMp+z1tGd1FFHz/QNhAv...",
  "paymentMethod": "CARD",
  "paymentInstrumentId": "46ee7bd8331744b5902509c28879ad16",
  "paymentInstrumentType": "SAVED_PAYMENT_METHOD",
  "initiatedType": "CUSTOMER"
}

3. Response Specification #

3.1 Response Data Schema #

depthFieldDetails & Description
-1resultCode

string

🔴 Required

결과 코드 (성공 "0", 에러 시 "EBP-A-0001" 등)

-1message

string

🔴 Required

결과 메시지 (성공 또는 에러 상세)

-1requestId

string

🔴 Required

추적을 위한 고유 요청 ID

-1timestamp

string

🔴 Required

ISO 8601 형식의 응답 타임스탬프

e.g., 2025-12-19T14:24:00+09:00
-1data

object

🔴 Required

응답 데이터 (비즈니스 결과물)

0orderNo

string

🔴 Required

EBP 주문 번호

0paymentUrl

string

⚪ Optional

추가 인증(3DS 등)이 필요한 경우 사용자를 이동시킬 URL입니다. EBP에서 제공하는 브릿지 페이지이거나 PG사에서 직접 제공하는 인증 페이지일 수 있습니다. requiresClientAction이 true인 경우 필수적으로 참조합니다.

0pgResponse

object

🔴 Required

추가 PG 상세 정보

1resultCode

string

🔴 Required

PG에서 반환한 결과 코드.

1pgProvider

string

🔴 Required

PG(Payment Gateway) 명칭.

1data

object

⚪ Optional

PG로부터 전달받은 상세 결과 데이터. 내부 필드는 PG사에 따라 다르게 구성됩니다. 상세 내용은 하단의 [PG별 상세 응답 데이터

(#32-pg별-상세-응답-데이터-pgresponsedata) 섹션을 참조하세요.]
-1instructions

object

🔴 Required

후속 처리를 위한 지시 사항 (프로세스 제어)

0status

string

🔴 Required

결제 프로세스의 현재 상태.

e.g., AUTHORIZED, ACTION_REQUIRED
0requiresClientAction

boolean

🔴 Required

클라이언트 추가 액션(인증 리다이렉트 등)이 필요한지 여부

0clientAction

object

⚪ Optional

클라이언트의 추가 액션 지시 정보 객체. requiresClientAction이 true인 경우 필수적으로 참조합니다.

1type

string

⚪ Optional

클라이언트 액션 유형

e.g., REDIRECT_TO_HPP
1pgProvider

string

⚪ Optional

액션을 처리할 PG사

1method

string

⚪ Optional

리다이렉트 시 사용할 HTTP Method

e.g., GET, POST
0requiresFollowUpApi

boolean

🔴 Required

후속 API 호출이 필수인지 여부

0followUpApi

object

⚪ Optional

클라이언트 액션 완료 후 호출해야 할 후속 API 정보. requiresFollowUpApi가 true인 경우 필수적으로 참조합니다.

결제 흐름 및 필드 활용 가이드:

  1. instructions.status: 결제의 현재 처리 상태입니다. AUTHORIZED(승인/매입 완료)라면 결제가 최종 성공한 것이며, ACTION_REQUIRED라면 추가 인증 단계가 남았음을 의미합니다.
  2. instructions.requiresClientAction 및 data.paymentUrl: 추가 인증 프로세스를 위해 사용자를 리다이렉트해야 하는지 나타냅니다. requiresClientAction이 true라면 제공된 paymentUrl로 사용자를 즉시 이동시켜야 합니다.
  3. paymentUrl 특징: 이 URL에는 결제 컨텍스트가 포함되어 있으며, EBP가 제공하는 브릿지 페이지를 통해 안전하게 PG사 인증 화면으로 연결됩니다.

3.2 PG별 상세 응답 데이터 (pgResponse.data) #

pgResponse.data 객체의 내부 필드는 연동된 PG사 규격에 따라 다르게 구성됩니다.

Omise #

depthFieldDetails & Description
0type

string

🔴 Required

PG 응답 데이터 구조를 식별하기 위한 타입 값.

e.g., OMISE_TOKEN, OMISE_SOURCE
0pgTransactionId

string

🔴 Required

PG 측 주문 참조 번호 또는 거래 ID.

0amount

number

🔴 Required

PG에서 처리된 금액.

0currencyCode

string

🔴 Required

거래에 사용된 통화 코드.

0chargedAt

string

🔴 Required

PG 측 결제 완료 일시.

0authorizeUri

string

⚪ Optional

추가 인증이 필요한 경우 이동할 PG사 원천 URL (예: 3DS 인증 등).

3.3 응답 샘플 (Response Samples) #

Card (Omise)
Installment (Omise)
BankTransfer (Thailand)
Saved Method (Card)
{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06EN43NFZ2P3N7MD6M5K1ND2W0",
  "timestamp": "2026-04-03T06:36:29.021557700Z",
  "data": {
    "orderNo": "ORD_7202604037731729",
    "paymentUrl": null,
    "pgResponse": {
      "resultCode": "OK",
      "pgProvider": "OMISE",
      "data": {
        "type": "OMISE_TOKEN",
        "pgTransactionId": "chrg_test_678b3p4rhqk7fl2iu71",
        "amount": 129,
        "currencyCode": "THB",
        "chargedAt": "2026-04-02T21:36:28Z",
        "authorizeUri": null
      }
    }
  },
  "instructions": {
    "status": "AUTHORIZED",
    "requiresClientAction": false,
    "requiresFollowUpApi": false
  }
}

{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06EN49JGVDMKNQMZXY9QSG8H1M",
  "timestamp": "2026-04-03T07:02:17.503946500Z",
  "data": {
    "orderNo": "ORD_7202604037731753",
    "paymentUrl": "https://pay.omise.co/offsites/ofsp_test_678bcs88ibmtqhjzsbs/pay?acs=false",
    "pgResponse": {
      "resultCode": "OK",
      "pgProvider": "OMISE",
      "data": {
        "type": "OMISE_SOURCE",
        "pgTransactionId": "chrg_test_678bcs862cers7axonh",
        "amount": 2500.0,
        "currencyCode": "THB",
        "chargedAt": "2026-04-02T22:02:17Z",
        "authorizeUri": "https://pay.omise.co/offsites/ofsp_test_678bcs88ibmtqhjzsbs/pay?acs=false"
      }
    }
  },
  "instructions": {
    "status": "ACTION_REQUIRED",
    "requiresClientAction": true,
    "clientAction": {
      "type": "REDIRECT_TO_HPP",
      "pgProvider": "OMISE",
      "method": "GET"
    },
    "requiresFollowUpApi": false
  }
}

{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06EN4A9GAYG551E1KCG5TVB41C",
  "timestamp": "2026-04-03T07:05:25.222386700Z",
  "data": {
    "orderNo": "ORD_7202604037731757",
    "paymentUrl": "https://pay.omise.co/payments/pay2_test_678bdvvvi2viwx9kpu6/authorize?acs=false",
    "pgResponse": {
      "resultCode": "OK",
      "pgProvider": "OMISE",
      "data": {
        "type": "OMISE_SOURCE",
        "pgTransactionId": "chrg_test_678bdvvtu4d2cj6xpq1",
        "amount": 2500.0,
        "currencyCode": "THB",
        "chargedAt": "2026-04-02T22:05:24Z",
        "authorizeUri": "https://pay.omise.co/payments/pay2_test_678bdvvvi2viwx9kpu6/authorize?acs=false"
      }
    }
  },
  "instructions": {
    "status": "ACTION_REQUIRED",
    "requiresClientAction": true,
    "clientAction": {
      "type": "REDIRECT_TO_HPP",
      "pgProvider": "OMISE",
      "method": "GET"
    },
    "requiresFollowUpApi": false
  }
}

{
  "resultCode": "0",
  "message": "SUCCESS",
  "requestId": "06ESKVY4A72M40Y978E19W0FK0",
  "timestamp": "2026-04-17T05:35:23.383039500Z",
  "data": {
    "orderNo": "ORD_7202604177734784",
    "paymentUrl": null,
    "pgResponse": {
      "resultCode": "PROC",
      "pgProvider": "WORLDPAY",
      "resultMessage": "AUTHORISED",
      "data": {
        "type": "WORLDPAY_TOKEN",
        "orderCode": "PGI_7202604177734786",
        "amount": 1800.0,
        "currencyCode": "AUD",
        "paymentCompletedAt": "2026-04-17T05:35:23Z"
      }
    }
  },
  "instructions": {
    "status": "AUTHORIZED",
    "requiresClientAction": false,
    "requiresFollowUpApi": false
  }
}
Last updated: 2026-04-24 07:45:12 © 2026 LG Electronics Inc. All rights reserved.