# 구매 API - 결제 생성
## 1. API Overview
### Purpose
[context]
이 API는 실제 결제 리소스를 생성하고, 최종적인 승인 및 매입 프로세스를 완료합니다.
**결제 의사 생성** 응답의 `completionMethod`가 `API`인 경우 호출하며, 이전 단계에서 발급된 암호화된 컨텍스트(`paymentContext`)와 PG 인증 정보(Token, Source 등)를 함께 전달해야 합니다.
특히, 요청 시 필수 필드인 `authRequestId`와 `authSignature`는 연동 방식에 따라 다음의 경로로 발급된 값을 반드시 사용해야 합니다.
- **저장된 결제 수단**: 사전에 완료된 **결제 비밀번호 확인 API**의 결과값 사용
- **그 외 일반 결제**: **결제 의사 생성 API**의 응답(`pgResponse.data`)으로 발급된 결과값 사용
[/context]
### Details
[table:key-value]
| 항목 | 값 |
| :-------------- | :---------------------------- |
| **API Name** | 결제 생성 |
| **API Path** | /api/v2/payments |
| **API ID** | EBP_API_230 |
| **HTTP Method** | [badge:POST,blue,lg] |
| **Region** | [badge:Global,green-subtle,lg] |
[/table]
## 2. Request Specification
### 2.1 Request Header
| depth | Field | Details & Description |
|:------|:------------------|:-------------------------------------------------------------------------------------|
| 0 | X-EBP-Context | [type:string] [req:Yes] [desc:결제 의사 생성 API의 응답으로 받은 data.paymentHeaderContext 값입니다.] |
| 0 | X-Idempotency-Key | [type:string] [req:Yes] [desc:동일한 결제 생성 요청에 대한 중복 처리를 방지하기 위한 멱등 키] |
### 2.2 Request Data Schema
모든 유형의 결제 수단에 대해 요청 구조가 통합되어 있습니다.
| depth | Field | Details & Description |
|:------|:-----------------------|:-----------------------------------------------------------------------------------------------|
| 0 | authRequestId | [type:string] [req:Yes] [desc:인증 성공 또는 결제 준비 시 발급되는 고유 식별자. 저장된 결제수단(SAVED_PAYMENT_METHOD)은 '결제 비밀번호 확인 API'의 data.requestId 값을, 그 외 일반 결제는 '결제 의사 생성 API'의 data.pgResponse.data.authRequestId 값을 사용합니다.] |
| 0 | authSignature | [type:string] [req:Yes] [desc:authRequestId에 대한 보안 서명 값. 저장된 결제수단(SAVED_PAYMENT_METHOD)은 '결제 비밀번호 확인 API'의 data.signature 값을, 그 외 일반 결제는 '결제 의사 생성 API'의 data.pgResponse.data.authSignature 값을 사용합니다.] |
| 0 | paymentMethod | [type:string] [req:Yes] [desc:사용된 결제 수단 (예: CARD, DIRECT_DEBIT).] |
| 0 | paymentInstrumentId | [type:string] [req:Yes] [desc:결제 수단 식별자. PG 토큰, 소스 ID 또는 EBP에 저장된 결제수단 ID가 될 수 있다.] |
| 0 | paymentInstrumentType | [type:string] [req:Yes] [desc:제공된 식별자의 유형.] [eg:ONE_TIME_TOKEN, ONE_TIME_SOURCE, SAVED_PAYMENT_METHOD] |
| 0 | paymentContext | [type:string] [req:Yes] [desc:결제 의사 생성 API에서 받은 암호화된 결제 컨텍스트. 주문 및 세션 정보를 복원하는 데 사용된다.] |
| 0 | initiatedType | [type:string] [req:Optional] [desc:거래를 시작한 주체 (CUSTOMER 또는 MERCHANT).] [eg:CUSTOMER] |
| 0 | billingAddress | [type:object] [req:Optional] [desc:부정거래 검증(FDS)을 위한 Billing Address 정보.] |
| 1 | firstName | [type:string] [req:Optional] [desc:구매자의 이름] |
| 1 | lastName | [type:string] [req:Optional] [desc:구매자의 성] |
| 1 | addressLine1 | [type:string] [req:Yes] [desc:첫 번째 기본 주소] |
| 1 | addressLine2 | [type:string] [req:Optional] [desc:두 번째 보조 주소] |
| 1 | city | [type:string] [req:Yes] [desc:도시 이름] |
| 1 | stateOrProvince | [type:string] [req:Optional] [desc:주 또는 성의 이름] |
| 1 | postalCode | [type:string] [req:Yes] [desc:우편번호] |
| 1 | countryCode | [type:string] [req:Yes] [desc:ISO 3166-1 표준에 따른 국가 코드] |
| 1 | phoneNumber | [type:string] [req:Optional] [desc:구매자의 전화번호] |
### 2.3 Request Examples
#### JSON Example
[tabs]
[tab:One-Time Token : Card]
```json
{
"authRequestId": "06EKTCYP2Q4GP462WH2Q53WQK0",
"authSignature": "srpLIW9X8WbU7ebDix8uZD6jrKo0fNufPmIS643Ie4I=",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcDd+mvVFP+R5/p2YmxXD4...",
"paymentMethod": "CARD",
"paymentInstrumentId": "tokn_test_676q2zf3cn4bduksgow",
"paymentInstrumentType": "ONE_TIME_TOKEN",
"initiatedType": "CUSTOMER"
}
```
[tab:One-Time Source : Installment (Thailand)]
```json
{
"authRequestId": "06EN49J7PZK1V01T0XPX222ZZ4",
"authSignature": "sf7IBgCG3KkXQPDE58+XEUzSa/XrzUY2+wHeYB9Pmos=",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcMX1fkli8RHkegtbrY9S63tDWhV/...",
"paymentMethod": "INSTALLMENT",
"paymentInstrumentId": "src_test_678bcrzd2xisbinnuya",
"paymentInstrumentType": "ONE_TIME_SOURCE"
}
```
[tab:One-Time Source : Bank Transfer (Thailand)]
```json
{
"authRequestId": "06EN4A99K70F6ZFNF3JY0PXEC0",
"authSignature": "czPZUs/zmdaQcjkknHGSwrkGbmemA1rS1txGz1Nzp4A=",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcLodPeyDSsE9PhRTbqZ2osZDWhV/+...",
"paymentMethod": "BANK_TRANSFER",
"paymentInstrumentId": "src_test_678bdvr1nzpud7qb7r9",
"paymentInstrumentType": "ONE_TIME_SOURCE"
}
```
[tab:Saved Method]
```json
{
"authRequestId": "06EDP0W5343S17MGFGESCG0JV0",
"authSignature": "0aOw85SbsSb3Lg8JNzwCwMpo/+gD1qfdej1f5x7knZU=",
"paymentContext": "GAkdwQJ8gx5w6IbCtGxTwMp+z1tGd1FFHz/QNhAv...",
"paymentMethod": "CARD",
"paymentInstrumentId": "46ee7bd8331744b5902509c28879ad16",
"paymentInstrumentType": "SAVED_PAYMENT_METHOD",
"initiatedType": "CUSTOMER"
}
```
[/tabs]
## 3. Response Specification
### 3.1 Response Data Schema
@@include:standard-response.md@@
| -1 | data | [type:object] [req:Yes] [desc:응답 데이터 (비즈니스 결과물)] |
| 0 | orderNo | [type:string] [req:Yes] [desc:EBP 주문 번호] |
| 0 | paymentUrl | [type:string] [req:Optional] [desc:추가 인증(3DS 등)이 필요한 경우 사용자를 이동시킬 URL입니다. EBP에서 제공하는 브릿지 페이지이거나 PG사에서 직접 제공하는 인증 페이지일 수 있습니다. `requiresClientAction`이 `true`인 경우 필수적으로 참조합니다.] |
| 0 | pgResponse | [type:object] [req:Yes] [desc:추가 PG 상세 정보] |
| 1 | resultCode | [type:string] [req:Yes] [desc:PG에서 반환한 결과 코드.] |
| 1 | pgProvider | [type:string] [req:Yes] [desc:PG(Payment Gateway) 명칭.] |
| 1 | data | [type:object] [req:Optional] [desc:PG로부터 전달받은 상세 결과 데이터. 내부 필드는 PG사에 따라 다르게 구성됩니다. 상세 내용은 하단의 [**PG별 상세 응답 데이터**](#32-pg별-상세-응답-데이터-pgresponsedata) 섹션을 참조하세요.] |
| -1 | instructions | [type:object] [req:Yes] [desc:후속 처리를 위한 지시 사항 (프로세스 제어)] |
| 0 | status | [type:string] [req:Yes] [desc:결제 프로세스의 현재 상태.] [eg:AUTHORIZED, ACTION_REQUIRED] |
| 0 | requiresClientAction | [type:boolean] [req:Yes] [desc:클라이언트 추가 액션(인증 리다이렉트 등)이 필요한지 여부] |
| 0 | clientAction | [type:object] [req:Optional] [desc:클라이언트의 추가 액션 지시 정보 객체. `requiresClientAction`이 `true`인 경우 필수적으로 참조합니다.] |
| 1 | type | [type:string] [req:Optional] [desc:클라이언트 액션 유형] [eg:REDIRECT_TO_HPP] |
| 1 | pgProvider | [type:string] [req:Optional] [desc:액션을 처리할 PG사] |
| 1 | method | [type:string] [req:Optional] [desc:리다이렉트 시 사용할 HTTP Method] [eg:GET, POST] |
| 0 | requiresFollowUpApi | [type:boolean] [req:Yes] [desc:후속 API 호출이 필수인지 여부] |
| 0 | followUpApi | [type:object] [req:Optional] [desc:클라이언트 액션 완료 후 호출해야 할 후속 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
| depth | Field | Details & Description |
|:------|:---------------|:--------------------------------------------------------------------------------------|
| 0 | type | [type:string] [req:Yes] [desc:PG 응답 데이터 구조를 식별하기 위한 타입 값.] [eg:OMISE_TOKEN, OMISE_SOURCE] |
| 0 | pgTransactionId| [type:string] [req:Yes] [desc:PG 측 주문 참조 번호 또는 거래 ID.] |
| 0 | amount | [type:number] [req:Yes] [desc:PG에서 처리된 금액.] |
| 0 | currencyCode | [type:string] [req:Yes] [desc:거래에 사용된 통화 코드.] |
| 0 | chargedAt | [type:string] [req:Yes] [desc:PG 측 결제 완료 일시.] |
| 0 | authorizeUri | [type:string] [req:Optional] [desc:추가 인증이 필요한 경우 이동할 PG사 원천 URL (예: 3DS 인증 등).] |
### 3.3 응답 샘플 (Response Samples)
[tabs]
[tab:Card (Omise)]
```json
{
"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
}
}
```
[tab:Installment (Omise)]
```json
{
"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
}
}
```
[tab:BankTransfer (Thailand)]
```json
{
"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
}
}
```
[tab:Saved Method (Card)]
```json
{
"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
}
}
```
[/tabs]