# Purchase API - Create Payment Intent
## 1. API Overview
### Purpose
[context]
This API initializes a payment intent to start the payment process. It supports various payment methods including card, bank transfer, installment, and e-wallet. You can choose an integration method that suits your environment: either a redirect method using the EBP-provided payment URL (`paymentUrl`) or a direct integration method using the PG response data (`pgResponse`). After creating a payment intent, the user proceeds with the payment directly through the PG depending on the integration method, and EBP then receives the result to send a Webhook or the merchant calls the Payment Creation API to finalize the transaction.
[/context]
### Details
[table:key-value]
| Item | Value |
| :-------------- | :-------------------- |
| **API Name** | Create Payment Intent |
| **API Path** | /api/v2/payment-intents |
| **API ID** | EBP_API_224 |
| **HTTP Method** | [badge:POST,blue,lg] |
| **Region** | [badge:Global,green-subtle,lg] |
[/table]
@@include:billing-account-creation.md@@
> After creating a payment intent, if the user completes authentication via the payment method, EBP sends a Webhook to the store to notify the result.
> Detailed documentation for the Webhook can be found at the link below.
> [**Go to Payment Authorized Webhook**](/docs/webhooks/payment-authorized)
## 2. Request Specification
### 2.1 Request Header
@@include:common-headers-link.md@@
| depth | Field | Details & Description |
|:------|:------------------|:-----------------------------------------------------------------------|
| 0 | X-Idempotency-Key | [type:string] [req:Yes] [desc:Idempotency key to prevent duplicate processing for identical payment intent creation requests.] |
### 2.2 Request Data Schema
| depth | Field | Details & Description |
|:------|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 0 | userNo | [type:string] [req:Yes] [desc:사용자 번호] |
| 0 | userName | [type:string] [req:Conditional] [desc:구매자 이름. Tamara 결제 수단 이용 시 필수입니다.] |
| 0 | email | [type:string] [req:Conditional] [desc:구매자 이메일 주소. Tamara 결제 수단 이용 시 필수입니다.] |
| 0 | phone | [type:string] [req:Optional] [desc:구매자 연락처] |
| 0 | paymentMethod | [type:string] [req:Yes] [desc:결제 수단 코드 [modal:appendix/payment-method-codes#payment-methods]][eg:CARD, INSTALLMENT, DIRECT_DEBIT, BANK_TRANSFER ... etc] |
| 0 | purchaseChannel | [type:string] [req:Yes] [desc:구매 채널 구분] [eg:WEB, APP] |
| 0 | merchantId | [type:string] [req:Optional] [desc:상점 ID] |
| 0 | successUrl | [type:string] [req:Yes] [desc: 결제 성공 후 리다이렉트될 URL] |
| 0 | failureUrl | [type:string] [req:Yes] [desc: 결제 실패 시 리다이렉트될 URL] |
| 0 | totalAmount | [type:number] [req:Yes] [desc:실 결제 총 금액.] |
| 0 | subtotalAmount | [type:number] [req:Yes] [desc:할인 전 금액.] |
| 0 | totalDiscountAmount | [type:number] [req:Yes] [desc:총 할인 금액.] |
| 0 | discountAmount | [type:number] [req:Yes] [desc:판매자 할인 금액.] |
| 0 | lgeDiscountAmount | [type:number] [req:Yes] [desc:LG전자 할인 금액.] |
| 0 | nonCancelableAmount | [type:number] [req:Yes] [desc:취소 불가 금액.] |
| 0 | itemName | [type:string] [req:Yes] [desc:결제 화면에 노출될 대표 상품명] |
| 0 | useSavedPaymentMethod | [type:boolean] [req:Optional] [desc:저장된 결제 수단 사용 여부. true 설정 시 이전에 저장된 정보를 사용해 결제를 진행합니다.] [eg:true/false] [def: false] |
| 0 | savePaymentMethod | [type:boolean] [req:Optional] [desc:결제 수단 저장 여부. true 설정 시 결제 성공 후 해당 결제 수단을 안전하게 저장하며, 저장된 정보는 추후 '결제 생성' 시 사용됩니다.] [eg:true/false] [def: false] |
| 0 | autoCapture | [type:boolean] [req:Optional] [desc:자동 매입(Capture) 여부. true 설정 시 결제 승인(Authorized) 후 즉시 매입 처리를 진행합니다. false일 경우 추후 별도의 매입 API 호출이 필요합니다.] [eg:true/false] [def: false] |
| 0 | nonTaxableAmount | [type:number] [req:Optional] [desc:비과세 대상 금액] |
| 0 | taxAmount | [type:number] [req:Optional] [desc:스토어에서 계산한 부가세 금액] |
| 0 | shippingAddress | [type:object] [req:Conditional] [desc:배송지 주소 정보입니다. Tabby, Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | addressLine1 | [type:string] [req:Conditional] [desc:배송지 기본 주소입니다. Tabby, Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | addressLine2 | [type:string] [req:Optional] [desc:배송지 상세 주소입니다.] |
| 1 | city | [type:string] [req:Conditional] [desc:배송지 도시 정보입니다. Tabby, Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | stateOrProvince | [type:string] [req:Optional] [desc:배송지 주/도/지역 정보입니다.] |
| 1 | postalCode | [type:string] [req:Conditional] [desc:배송지 우편번호입니다. Tabby 결제 수단 이용 시 필수입니다.] |
| 1 | countryCode | [type:string] [req:Conditional] [desc:배송지 국가 코드(ISO 3166-1 alpha-2)입니다. Tabby, Tamara 결제 수단 이용 시 필수입니다.] |
| 0 | billingAddress | [type:object] [req:Conditional] [desc:청구지(빌링) 주소 정보입니다. Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | firstName | [type:string] [req:Conditional] [desc:청구지 수령인 이름입니다. Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | lastName | [type:string] [req:Conditional] [desc:청구지 수령인 성입니다. Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | phoneNumber | [type:string] [req:Conditional] [desc:청구지 연락처 번호입니다. Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | addressLine1 | [type:string] [req:Conditional] [desc:청구지 기본 주소입니다. Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | addressLine2 | [type:string] [req:Optional] [desc:청구지 상세 주소입니다.] |
| 1 | city | [type:string] [req:Conditional] [desc:청구지 도시 정보입니다. Tamara 결제 수단 이용 시 필수입니다.] |
| 1 | stateOrProvince | [type:string] [req:Optional] [desc:청구지 주/도/지역 정보입니다.] |
| 1 | postalCode | [type:string] [req:Optional] [desc:청구지 우편번호입니다.] |
| 1 | countryCode | [type:string] [req:Conditional] [desc:청구지 국가 코드(ISO 3166-1 alpha-2)입니다. Tamara 결제 수단 이용 시 필수입니다.] |
| 0 | bankTransferSource | [type:string] [req:Conditional] [desc:태국 Bank Transfer 결제 수단 이용 시 필수입니다.] [eg: mobile_banking_bay, mobile_banking_bbl, mobile_banking_kbank, mobile_banking_ktb, mobile_banking_scb] |
| 0 | platformType | [type:string] [req:Conditional] [desc:태국 Bank Transfer 결제 수단 이용 시 필수입니다.] [eg: IOS, ANDROID] |
| 0 | installmentSource | [type:string] [req:Conditional] [desc:태국 Installment 결제 수단 이용 시 필수입니다.] [eg: installment_bay, installment_kbank, ...] |
| 0 | installmentTerm | [type:number] [req:Conditional] [desc:태국 Installment 결제 수단 이용 시 필수입니다.] [eg: 3, 5 ...] |
@@include:items.md@@
@@include:item-type.md@@
> **할부 결제 정보 (installmentSource & installmentTerm) 안내**
>
> 태국 할부 결제(`INSTALLMENT`) 이용 시 다음의 조건 및 제한 사항을 확인하십시오.
> - **결제 금액 조건**: **총 결제 금액이 2,000 THB 이상**이어야 하며, **매월 납부 금액(총 금액 / 개월 수)이 500 THB 이상**인 경우에만 이용 가능합니다.
> - **지원 금융사별 기간**: 선택한 `installmentSource`에 따라 사용 가능한 `installmentTerm`(개월 수)이 다릅니다.
> - **installment_bay** (Krungsri Bank): `[3, 4, 6, 9, 10]`
> - **installment_kbank** (Kasikorn Bank): `[3, 4, 6, 10]`
> - **installment_ktc** (Krungthai Card): `[3, 4, 5, 6, 7, 8, 9, 10]`
> - **installment_bbl** (Bangkok Bank): `[4, 6, 8, 9, 10]`
> - **installment_first_choice** (Krungsri First Choice): `[3, 4, 6, 9, 10, 12, 18, 24, 36]`
> - **installment_scb** (Siam Commercial Bank): `[3, 4, 6, 9, 10]`
> - **installment_ttb** (TMBThanachart Bank): `[3, 4, 6, 10]`
> - **installment_uob** (United Overseas Bank): `[3, 4, 6, 10]`
> Note:
>
> - 배송그룹번호(deliveryGroupNo) 관련 예제는 여기[modal:modals/payment/delivery-group#delivery-group]에서 확인하세요.
### 2.3 Request Examples
[tabs]
[tab:Card]
```json : scrollable
{
"userNo": "AU1741850000100",
"userName": "James Cook",
"email": "james.cook@example.au",
"phone": "+61-412-345-100",
"shippingAddress": null,
"billingAddress": null,
"purchaseChannel": "WEB",
"successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/success",
"failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/failure",
"totalAmount": 1815,
"subtotalAmount": 1815,
"totalDiscountAmount": 0,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"nonCancelableAmount": 0,
"nonTaxableAmount": 0,
"taxAmount": 0,
"itemName": "LG Gram 16\" Laptop",
"savePaymentMethod": false,
"items": [
{
"seq": 1,
"sellerNo": "SELLER-001",
"itemType": "PHYSICAL",
"itemId": "AU_PROD_01",
"itemName": "LG Gram 16\" Laptop",
"quantity": 1,
"unitPrice": 1800,
"netAmount": 1800,
"grossAmount": 1800,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
},
{
"seq": 2,
"sellerNo": "SELLER-001",
"itemType": "DELIVERY",
"itemId": "AU_SHIP_01",
"itemName": "Standard Delivery",
"quantity": 1,
"unitPrice": 15,
"netAmount": 15,
"grossAmount": 15,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
}
],
"paymentMethod": "CARD",
"useSavedPaymentMethod": false
}
```
[tab:Paypal]
```json : scrollable
{
"userNo": "AU1741850000100",
"userName": "James Cook",
"email": "james.cook@example.au",
"phone": "+61-412-345-100",
"shippingAddress": null,
"billingAddress": null,
"purchaseChannel": "WEB",
"successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/success",
"failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/worldpay/failure",
"totalAmount": 1800,
"subtotalAmount": 1800,
"totalDiscountAmount": 0,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"nonCancelableAmount": 0,
"nonTaxableAmount": 0,
"taxAmount": 0,
"itemName": "LG Gram 16\" Laptop",
"savePaymentMethod": false,
"items": [
{
"seq": 1,
"sellerNo": "SELLER-001",
"itemType": "PHYSICAL",
"itemId": "AU_PROD_01",
"itemName": "LG Gram 16\" Laptop",
"quantity": 1,
"unitPrice": 1800,
"netAmount": 1800,
"grossAmount": 1800,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
}
],
"paymentMethod": "PAYPAL",
"useSavedPaymentMethod": false
}
```
[tab:Bank Transfer (Thailand)]
```json : scrollable
{
"userNo": "TH1741850000100",
"userName": "Somchai Pak",
"email": "somchai.p@example.th",
"phone": "+66-81-234-1000",
"shippingAddress": null,
"billingAddress": null,
"purchaseChannel": "WEB",
"successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/success",
"failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/failure",
"totalAmount": 26100,
"subtotalAmount": 26100,
"totalDiscountAmount": 0,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"nonCancelableAmount": 0,
"nonTaxableAmount": 0,
"taxAmount": 0,
"itemName": "LG Nanocell 55\" TV",
"savePaymentMethod": false,
"items": [
{
"seq": 1,
"sellerNo": "SELLER-001",
"itemType": "PHYSICAL",
"itemId": "TH_PROD_01",
"itemName": "LG Nanocell 55\" TV",
"quantity": 1,
"unitPrice": 25900,
"netAmount": 25900,
"grossAmount": 25900,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
},
{
"seq": 2,
"sellerNo": "SELLER-001",
"itemType": "DELIVERY",
"itemId": "TH_SHIP_01",
"itemName": "Standard Shipping",
"quantity": 1,
"unitPrice": 200,
"netAmount": 200,
"grossAmount": 200,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
}
],
"paymentMethod": "BANK_TRANSFER",
"useSavedPaymentMethod": false,
"bankTransferSource": "mobile_banking_bay",
"platformType": "IOS"
}
```
[tab:Installment (Thailand)]
```json : scrollable
{
"userNo": "TH1741850000100",
"userName": "Somchai Pak",
"email": "somchai.p@example.th",
"phone": "+66-81-234-1000",
"shippingAddress": null,
"billingAddress": null,
"purchaseChannel": "WEB",
"successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/success",
"failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/omise/failure",
"totalAmount": 26100,
"subtotalAmount": 26100,
"totalDiscountAmount": 0,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"nonCancelableAmount": 0,
"nonTaxableAmount": 0,
"taxAmount": 0,
"itemName": "LG Nanocell 55\" TV",
"savePaymentMethod": false,
"items": [
{
"seq": 1,
"sellerNo": "SELLER-001",
"itemType": "PHYSICAL",
"itemId": "TH_PROD_01",
"itemName": "LG Nanocell 55\" TV",
"quantity": 1,
"unitPrice": 25900,
"netAmount": 25900,
"grossAmount": 25900,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
},
{
"seq": 2,
"sellerNo": "SELLER-001",
"itemType": "DELIVERY",
"itemId": "TH_SHIP_01",
"itemName": "Standard Shipping",
"quantity": 1,
"unitPrice": 200,
"netAmount": 200,
"grossAmount": 200,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
}
],
"paymentMethod": "INSTALLMENT",
"useSavedPaymentMethod": false,
"installmentSource": "installment_kbank",
"installmentTerm": 3
}
```
[tab:Tamara (UAE)]
```json : scrollable
{
"userNo": "AE1741850000100",
"userName": "Zayed Ahmed",
"email": "zayed.a@example.ae",
"phone": "+971-50-123-4100",
"shippingAddress": {
"addressLine1": "Burj Khalifa, Floor 122",
"city": "Dubai",
"state": "Dubai",
"postalCode": "12210",
"countryCode": "AE"
},
"billingAddress": {
"addressLine1": "Burj Khalifa, Floor 122",
"city": "Dubai",
"countryCode": "AE"
},
"purchaseChannel": "WEB",
"successUrl": "http://localhost:8080/pgui/v2/hpp/checkoutcom/success",
"failureUrl": "http://localhost:8080/pgui/v2/hpp/checkoutcom/failure",
"totalAmount": 2825,
"subtotalAmount": 2825,
"totalDiscountAmount": 0,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"nonCancelableAmount": 0,
"nonTaxableAmount": 0,
"taxAmount": 0,
"itemName": "LG OLED G3 65\" TV",
"savePaymentMethod": false,
"items": [
{
"seq": 1,
"sellerNo": "SELLER-001",
"itemType": "PRODUCT",
"itemId": "AE_PROD_01",
"itemName": "LG OLED G3 65\" TV",
"quantity": 1,
"unitPrice": 2800,
"netAmount": 2800,
"grossAmount": 2800,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
},
{
"seq": 2,
"sellerNo": "SELLER-001",
"itemType": "SHIPPING",
"itemId": "AE_SHIP_01",
"itemName": "Premium Delivery",
"quantity": 1,
"unitPrice": 25,
"netAmount": 25,
"grossAmount": 25,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
}
],
"paymentMethod": "TAMARA",
"useSavedPaymentMethod": false
}
```
[tab:Tabby (UAE)]
```json : scrollable
{
"userNo": "AE1741850000100",
"userName": "Zayed Ahmed",
"email": "zayed.a@example.ae",
"phone": "+971-50-123-4100",
"shippingAddress": {
"addressLine1": "Burj Khalifa, Floor 122",
"city": "Dubai",
"state": "Dubai",
"postalCode": "12210",
"countryCode": "AE"
},
"purchaseChannel": "WEB",
"successUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/checkoutcom/success",
"failureUrl": "https://devkic-pgui.nebp.lge.com/pgui/v2/hpp/checkoutcom/failure",
"totalAmount": 1900,
"subtotalAmount": 1900,
"totalDiscountAmount": 0,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"nonCancelableAmount": 0,
"nonTaxableAmount": 0,
"taxAmount": 0,
"itemName": "LG Gram 17\" Laptop",
"savePaymentMethod": false,
"items": [
{
"seq": 1,
"sellerNo": "SELLER-001",
"itemType": "PHYSICAL",
"itemId": "AE_PROD_02",
"itemName": "LG Gram 17\" Laptop",
"quantity": 1,
"unitPrice": 1900,
"netAmount": 1900,
"grossAmount": 1900,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"orderDiscountAllocated": 0
}
],
"paymentMethod": "TABBY",
"useSavedPaymentMethod": false
}
```
[tab:Google Pay]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "GOOGLEPAY",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 20.0,
"subtotalAmount": 20.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "In-app Purchase",
"phone": "+15551234567",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "In-app Purchase",
"feeRate": 10,
"quantity": 1,
"unitPrice": 20,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Apple Pay]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "APPLEPAY",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 25.0,
"subtotalAmount": 25.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Subscription",
"phone": "+15559876543",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Subscription",
"feeRate": 10,
"quantity": 1,
"unitPrice": 25,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Klarna]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "KLARNA",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 120.0,
"subtotalAmount": 120.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Fashion Item",
"phone": "+46701234567",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Fashion Item",
"feeRate": 10,
"quantity": 1,
"unitPrice": 120,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:iDEAL]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "IDEAL",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 45.5,
"subtotalAmount": 45.5,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Home Decor",
"phone": "+31612345678",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Home Decor",
"feeRate": 10,
"quantity": 1,
"unitPrice": 45.5,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Bizum]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "BIZUM",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 30.0,
"subtotalAmount": 30.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Event Ticket",
"phone": "+34600123456",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Event Ticket",
"feeRate": 10,
"quantity": 1,
"unitPrice": 30,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:MB Way]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "MBWAY",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 15.0,
"subtotalAmount": 15.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Digital Content",
"phone": "+351912345678",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Digital Content",
"feeRate": 10,
"quantity": 1,
"unitPrice": 15,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Kredivo]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "KREDIVO",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 500000.0,
"subtotalAmount": 500000.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Electronics",
"phone": "+628123456789",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Electronics",
"feeRate": 10,
"quantity": 1,
"unitPrice": 500000,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Mybank]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "MYBANK",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 200.0,
"subtotalAmount": 200.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Online Course",
"phone": "+8613800138000",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Online Course",
"feeRate": 10,
"quantity": 1,
"unitPrice": 200,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Sepa DD]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "SEPA_DD",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 10.0,
"subtotalAmount": 10.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Monthly Subscription",
"phone": "+4915123456789",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Monthly Subscription",
"feeRate": 10,
"quantity": 1,
"unitPrice": 10,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Przelewy24]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "PRZELEWY24",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 100.0,
"subtotalAmount": 100.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Books",
"phone": "+48500123456",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Books",
"feeRate": 10,
"quantity": 1,
"unitPrice": 100,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Bilk]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "BILK",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 50.0,
"subtotalAmount": 50.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Game Credits",
"phone": "+905321234567",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Game Credits",
"feeRate": 10,
"quantity": 1,
"unitPrice": 50,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:PIX]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "PIX",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 100.0,
"subtotalAmount": 100.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Streaming Service",
"phone": "+5511912345678",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Streaming Service",
"feeRate": 10,
"quantity": 1,
"unitPrice": 100,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:SafetyPay]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "SAFETYPAY",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 75.0,
"subtotalAmount": 75.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Travel Booking",
"phone": "+51912345678",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Travel Booking",
"feeRate": 10,
"quantity": 1,
"unitPrice": 75,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Transferncia Bancaria]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "TRANS_BANC",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 200.0,
"subtotalAmount": 200.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Furniture",
"phone": "+5521912345678",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Furniture",
"feeRate": 10,
"quantity": 1,
"unitPrice": 200,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Afterpay]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "AFTERPAY",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 150.0,
"subtotalAmount": 150.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Clothing",
"phone": "+61412345678",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Clothing",
"feeRate": 10,
"quantity": 1,
"unitPrice": 150,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:BillEase]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "BILLEASE",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 2000.0,
"subtotalAmount": 2000.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Smartphone",
"phone": "+639171234567",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Smartphone",
"feeRate": 10,
"quantity": 1,
"unitPrice": 2000,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:FPX]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "FPX",
"purchaseChannel": "WEB",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 100.0,
"subtotalAmount": 100.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Gift Card",
"phone": "+60123456789",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Gift Card",
"feeRate": 10,
"quantity": 1,
"unitPrice": 100,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:BoostPay]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "BOOSTPAY",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 50.0,
"subtotalAmount": 50.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Mobile Top-up",
"phone": "+60123456789",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Mobile Top-up",
"feeRate": 10,
"quantity": 1,
"unitPrice": 50,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:GrabPay]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "GRABPAY",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 20.0,
"subtotalAmount": 20.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Food Delivery",
"phone": "+6581234567",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Food Delivery",
"feeRate": 10,
"quantity": 1,
"unitPrice": 20,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Maybank QR Pay]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "MAYBANK_QR",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 15.0,
"subtotalAmount": 15.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Coffee",
"phone": "+60123456789",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Coffee",
"feeRate": 10,
"quantity": 1,
"unitPrice": 15,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:TnGo]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "TNGO",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 10.0,
"subtotalAmount": 10.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Snacks",
"phone": "+60123456789",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Snacks",
"feeRate": 10,
"quantity": 1,
"unitPrice": 10,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[tab:Konbini]
```json : scrollable
{
"userNo": "GB2501108122805",
"paymentMethod": "CONBINI",
"purchaseChannel": "APP",
"successUrl": "https://example.com/success",
"failureUrl": "https://example.com/fail",
"totalAmount": 5000.0,
"subtotalAmount": 5000.0,
"totalDiscountAmount": 0.0,
"discountAmount": 0.0,
"lgeDiscountAmount": 0.0,
"nonCancelableAmount": 0.0,
"itemName": "Beverage",
"phone": "01012345678",
"items": [
{
"seq": 1,
"sellerNo": "TEST_SELLR",
"itemType": "PHYSICAL",
"itemId": "Item1",
"itemName": "Beverage",
"feeRate": 10,
"quantity": 1,
"unitPrice": 5000,
"discountAmount": 0,
"lgeDiscountAmount": 0,
"deliveryGroupNo": ""
}
]
}
```
[/tabs]
## 3. Response Specification
### 3.1 Response Data Schema
@@include:standard-response.md@@
| -1 | data | [type:object] [req:Yes] [desc:응답 데이터 (비즈니스 결과물)] |
| 0 | status | [type:string] [req:Yes] [desc:결제 프로세스의 현재 상태. 최종 목표인 '성공'에 도달하기 위한 진행 상황을 나타냅니다.] [eg:AUTHORIZED, ACTION_REQUIRED] |
| 0 | paymentUrl | [type:string] [req:Optional] [desc:추가 인증이 필요한 경우 사용자를 이동시킬 URL입니다. EBP에서 제공하는 브릿지 페이지이거나 PG사에서 직접 제공하는 인증 페이지일 수 있습니다. `requiresClientAction`이 `true`인 경우 필수적으로 참조합니다.] |
| 0 | orderNo | [type:string] [req:Yes] [desc:주문번호] |
| 0 | pgTransactionId | [type:string] [req:Yes] [desc:PG 거래번호] |
| 0 | paymentContext | [type:string] [req:Yes] [desc:EBP에서 발급한 암호화된 결제 컨텍스트 값입니다. '결제 생성 API' 호출 시 필수 값으로 사용됩니다.] |
| 0 | successUrl | [type:string] [req:Yes] [desc:결제 성공 시 리다이렉트될 최종 URL] |
| 0 | failureUrl | [type:string] [req:Yes] [desc:결제 실패 시 리다이렉트될 최종 URL] |
| 0 | pgResponse | [type:object] [req:Yes] [desc:PG사 응답 상세 정보] |
| 1 | resultCode | [type:string] [req:Yes] [desc:PG사 응답 결과 코드] |
| 1 | data | [type:object] [req:Yes] [desc:PG사 응답 상세 데이터. 상세 규격은 하단의 [**PG별 상세 응답 데이터**](#32-pg별-상세-응답-데이터-pgresponsedata) 섹션을 참조하세요.] |
| 0 | savedPaymentMethods | [type:array] [req:Optional] [desc:사용자가 이전에 저장한 결제 수단 목록입니다. 요청 시 `useSavedPaymentMethod` 필드값이 `true`인 경우에 한해 반환됩니다.] |
| 1 | paymentMethod | [type:string] [req:Yes] [desc:결제 수단 코드] [eg:CARD, DIRECT_DEBIT] |
| 1 | paymentMethodId | [type:string] [req:Yes] [desc:EBP 내부에서 관리하는 결제 수단 고유 식별자] |
| 1 | cardNumber | [type:string] [req:Conditional] [desc:마스킹 처리된 카드 번호 (카드 결제 수단인 경우)] |
| 1 | cardIssuer | [type:string] [req:Conditional] [desc:카드 발급사 또는 브랜드 명 (카드 결제 수단인 경우)] |
| 1 | isBlocked | [type:boolean] [req:Yes] [desc:해당 결제 수단의 사용 차단 여부 (true 시 사용 불가)] |
| 1 | pinErrorCount | [type:number] [req:Yes] [desc:결제 비밀번호(PIN) 입력 오류 횟수] |
| 1 | isPinRegistered | [type:boolean] [req:Yes] [desc:결제 비밀번호 등록 여부] |
| -1 | instructions | [type:object] [req:Yes] [desc:후속 처리를 위한 지시 사항 (프로세스 제어)] |
| 0 | nextStep | [type:string] [req:Yes] [desc:상태를 전환하기 위해 클라이언트가 즉시 수행해야 할 행동 지시입니다.] [eg:CLIENT_ACTION, CALL_API] |
| 0 | completionMethod | [type:string] [req:Yes] [desc:해당 결제가 최종적으로 완료되는 주체와 방식입니다.] [eg:WEBHOOK, API] |
| 0 | requiresClientAction | [type:boolean] [req:Yes] [desc:클라이언트 추가 액션이 필요한지 여부] |
| 0 | clientAction | [type:object] [req:Optional] [desc:클라이언트의 추가 액션 지시 정보 객체. `requiresClientAction`이 `true`인 경우 필수적으로 참조합니다.] |
| 1 | type | [type:string] [req:Optional] [desc:클라이언트 액션 유형] [eg:TOKENIZE_CARD, CREATE_SOURCE, 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(결제 생성 API 등) 호출이 필수인지 여부] |
| 0 | followUpApi | [type:object] [req:Optional] [desc:클라이언트 액션 완료 후 호출해야 할 후속 API 정보. `requiresFollowUpApi`가 `true`인 경우 필수적으로 참조합니다.] |
| 1 | method | [type:string] [req:Optional] [desc:후속 API의 HTTP Method] [eg:POST] |
| 1 | url | [type:string] [req:Optional] [desc:후속 API의 호출 경로] |
| 1 | description | [type:string] [req:Optional] [desc:후속 API에 대한 부연 설명] |
> **결제 흐름 및 필드 활용 가이드:**
>
> 1. **status**: 결제 리소스의 현재 상태입니다. 클라이언트는 이 값을 확인해 결제의 진행 단계와 최종 성공 여부를 판단합니다.
> 2. **instructions.nextStep**: `status`가 `ACTION_REQUIRED`일 때 결제를 진행하기 위한 제어권이 클라이언트에게 있음을 나타냅니다.
> 3. **instructions.requiresClientAction 및 clientAction**: 클라이언트가 추가로 수행해야 할 액션이 있는지 나타냅니다. `requiresClientAction`이 `true`인 경우, `clientAction.type`을 확인하여 제공된 `paymentUrl`로 **Redirect** 하거나, PG 응답 데이터를 활용해 **Direct**로 SDK를 호출하는 등 지정된 동작을 수행해야 합니다.
> 4. **data.paymentUrl**: EBP가 PG사의 결제 페이지를 래핑하여 제공하는 URL입니다. 복잡한 PG 연동 로직 없이 간편하게 리다이렉트만으로 결제를 처리하고자 할 때 활용합니다. (`clientAction.type`이 `REDIRECT_TO_HPP`인 경우 주로 사용)
> 5. **instructions.completionMethod**: 결제 프로세스가 최종적으로 마감되는 주체와 경로를 명시합니다.
> * `WEBHOOK`: 클라이언트 액션 완료 후 EBP가 PG 웹훅을 수신해 자동으로 결제를 완료 처리합니다. 이후 상점으로 결과 웹훅이 전송되므로, 클라이언트는 결과 페이지로 이동해 처리를 대기합니다.
> * `API`: 클라이언트가 인증 정보 등을 직접 확보한 뒤, EBP의 **결제 생성 API**를 호출해야 프로세스가 최종 종료됩니다.
> 6. **instructions.requiresFollowUpApi 및 followUpApi**: 클라이언트 액션 완료 후, 후속 API 호출이 필수적인지 나타냅니다. `requiresFollowUpApi`가 `true`라면, 클라이언트는 `followUpApi.method`와 `url`을 참고하여 최종 **결제 생성 API** 등을 직접 호출해야 합니다.
> 7. **data.paymentHeaderContext**: 주문 헤더 정보를 암호화하여 담고 있는 값입니다. `completionMethod`가 `API`(또는 후속 API 호출이 필요한 경우)인 경우, 후속 **결제 생성 API**를 호출할 때 Header(`X-EBP-Context`)에 이 값을 포함하여 요청해야 합니다.
> 8. **data.paymentContext**: 주문 및 세션 정보를 암호화하여 담고 있는 값입니다. `completionMethod`가 `API`(또는 후속 API 호출이 필요한 경우)인 경우, 후속 **결제 생성 API**를 호출할 때 Body(`paymentContext`)에 이 값을 포함하여 요청해야 합니다.
### 3.2 PG별 상세 응답 데이터 (pgResponse.data)
`pgResponse.data` 객체의 내부 필드는 연동된 PG사 규격에 따라 다르게 구성됩니다.
#### Worldpay
| depth | Field | Details & Description |
|:------|:-------------|:--------------------------------------------------------------------------------------|
| -1 | type | [type:string] [req:Yes] [desc:PG 응답 데이터 구조를 식별하기 위한 타입 값] [eg:WORLDPAY] |
| -1 | pgRefId | [type:string] [req:Yes] [desc:PG사 거래 참조 ID] |
| -1 | returnUrl | [type:string] [req:Yes] [desc:PG사 리턴 URL] |
| -1 | referenceUrl | [type:string] [req:Yes] [desc:PG사 참조 URL] |
##### Response Sample (pgResponse)
```json
{
"pgResponse": {
"resultCode": "PASS",
"pgProvider": "WORLDPAY",
"data": {
"type": "WORLDPAY",
"pgRefId": "3592845796",
"returnUrl": "https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=LGETEST3%5EPGI_7202603277730815&Ticket=00177500323082302hx43VA8CApQK6sui8pi4vA0GOz8s8T1zqoAcWX&source=https%3A%2F%2Fsecure-test.worldpay.com",
"referenceUrl": "https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=LGETEST3%5EPGI_7202603277730815&Ticket=00177500323082302hx43VA8CApQK6sui8pi4vA0GOz8s8T1zqoAcWX&source=https%3A%2F%2Fsecure-test.worldpay.com"
}
}
}
```
#### Checkout.com
| depth | Field | Details & Description |
|:------|:---------------|:----------------------------------------------------------------------------------------------------------------------------------------|
| 0 | type | [type:string] [req:Yes] [desc:PG 응답 데이터 구조를 식별하기 위한 타입 값] [eg:CHECKOUT] |
| 0 | publicKey | [type:string] [req: Yes] [desc: Checkout.com Flow를 초기화하기 위한 Public Key입니다. 클라이언트 환경에서 사용되며, 결제 UI(Flow) 마운트 시 필수적으로 전달됩니다.] |
| 0 | paymentSession | [type:object] [req:Yes] [desc:Checkout.com에서 생성된 결제 세션 정보로, 결제 세션의 인증 및 보안 검증에 사용됩니다. Flow 초기화 시 함께 전달되며, 해당 결제 요청을 식별하고 보호하는 역할을 합니다.] |
##### Response Sample (pgResponse)
```json
{
"pgResponse": {
"resultCode": "OK",
"pgProvider": "CHECKOUT_COM",
"data": {
"type": "CHECKOUT",
"publicKey": "pk_sbox_2ewvjanc7xpuduraa7tqqu...",
"paymentSession": {
"id": "ps_3BVPH1ROFbmWLF7NwzgppkRahGy",
"payment_session_secret": "pss_88520096-4af1-463e-a0fb-737d169e340a",
"payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzNCVlBIMVJPRmJtV0xGN053emdwcGtSYWhHeSIsImVudGl0eV9pZCI6ImVudF8za2ZoaHZ6NXVldXRmajVtNmpkYTRhYnB6YSIsImV4cGVyaW1lbnRzIjp7fSwicHJvY2Vzc2luZ19jaGFubmVsX2lkIjoicGNfa21teXVieWMyNnpldnBrcWx0eXZqdXBvbWUiLCJhbW91bnQiOjI4MjUwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkFFRCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiXSwic2NoZW1lX2Nob2ljZV9lbmFibGVkIjpmYWxzZSwic3RvcmVfcGF5bWVudF9kZXRhaWxzIjoiZGlzYWJsZWQiLCJiaWxsaW5nX2FkZHJlc3MiOnsiY291bnRyeSI6IkFFIn19LHsidHlwZSI6ImFwcGxlcGF5IiwiZGlzcGxheV9uYW1lIjoiTEcgVUFFIiwiY291bnRyeV9jb2RlIjoiQUUiLCJjdXJyZW5jeV9jb2RlIjoiQUVEIiwibWVyY2hhbnRfY2FwYWJpbGl0aWVzIjpbInN1cHBvcnRzM0RTIl0sInN1cHBvcnRlZF9uZXR3b3JrcyI6WyJ2aXNhIiwibWFzdGVyQ2FyZCJdLCJ0b3RhbCI6eyJsYWJlbCI6IkxHIFVBRSIsInR5cGUiOiJmaW5hbCIsImFtb3VudCI6IjI4MjUifX0seyJ0eXBlIjoiZ29vZ2xlcGF5IiwibWVyY2hhbnQiOnsiaWQiOiIwODExMzA4OTM4NjI2ODg0OTk4MiIsIm5hbWUiOiJMRyBVQUUiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjgwODAifSwidHJhbnNhY3Rpb25faW5mbyI6eyJ0b3RhbF9wcmljZV9zdGF0dXMiOiJGSU5BTCIsInRvdGFsX3ByaWNlIjoiMjgyNSIsImNvdW50cnlfY29kZSI6IkFFIiwiY3VycmVuY3lfY29kZSI6IkFFRCJ9LCJjYXJkX3BhcmFtZXRlcnMiOnsiYWxsb3dlZF9hdXRoX21ldGhvZHMiOlsiUEFOX09OTFkiLCJDUllQVE9HUkFNXzNEUyJdLCJhbGxvd2VkX2NhcmRfbmV0d29ya3MiOlsiVklTQSIsIk1BU1RFUkNBUkQiXX19LHsidHlwZSI6InRhYmJ5IiwiY291bnRyeV9jYWxsaW5nX2NvZGVzIjpbIjk3MSJdLCJlbWFpbCI6InpheWVkLmFAZXhhbXBsZS5hZSJ9XSwiZmVhdHVyZV9mbGFncyI6WyJhbmFseXRpY3Nfb2JzZXJ2YWJpbGl0eV9lbmFibGVkIiwiZ2V0X3dpdGhfcHVibGljX2tleV9lbmFibGVkIiwibG9nc19vYnNlcnZhYmlsaXR5X2VuYWJsZWQiLCJyaXNrX2pzX2VuYWJsZWQiLCJ1c2VfYmlsbGluZ19hZGRyZXNzX2Zyb21fY29uZmlnX2Zvcl90b2tlbml6YXRpb24iLCJ1c2VfZGV2aWNlX2FwaV9mb3Jfb2JzZXJ2YWJpbGl0eSIsInVzZV9yaXNranNfdjIiLCJ1c2VfdXJsX2hhc2hfZm9yX2lmcmFtZV9wcm9wcyJdLCJyaXNrIjp7ImVuYWJsZWQiOmZhbHNlfSwibWVyY2hhbnRfbmFtZSI6IkxHIFVBRSIsInBheW1lbnRfc2Vzc2lvbl9zZWNyZXQiOiJwc3NfODg1MjAwOTYtNGFmMS00NjNlLWEwZmItNzM3ZDE2OWUzNDBhIiwiaW50ZWdyYXRpb25fZG9tYWluIjoiYXBpLnNhbmRib3guY2hlY2tvdXQuY29tIn0=",
"_links": {
"self": {
"href": "https://api.sandbox.checkout.com/payment-sessions/ps_3BVPH1ROFbmWLF7NwzgppkRahGy"
}
}
}
}
}
}
```
#### Omise
| depth | Field | Details & Description |
|:------|:---------------|:-----------------------------------------------------------------------------|
| -1 | publicKey | [type:string] [req:Yes] [desc:Omise에서 발급받은 공개 키] |
| -1 | amount | [type:number] [req:Yes] [desc:결제 금액] |
| -1 | currencyCode | [type:string] [req:Yes] [desc:결제 통화 코드] |
| -1 | itemName | [type:string] [req:Yes] [desc:결제 대상 상품명] |
| -1 | authRequestId | [type:string] [req:Yes] [desc:인증 요청 식별자, 결제 생성 요청에 필수적으로 사용] |
| -1 | authSignature | [type:string] [req:Yes] [desc:요청 무결성 검증을 위한 보안 서명, 결제 생성 요청에 필수적으로 사용] |
| -1 | paymentContext | [type:string] [req:Yes] [desc:결제 컨텍스트 정보. 결제 생성 요청에 필수적으로 사용되는 암호화된 데이터 세트.] |
##### Response Sample (pgResponse)
```json : scrollable
{
"pgResponse": {
"resultCode": "OK",
"pgProvider": "CHECKOUT_COM",
"data": {
"type": "CHECKOUT",
"publicKey": "pkey_test_66lmsec8z06uh3jz...",
"amount": 2610000,
"currency": "THB",
"itemName": "LG Nanocell 55\" TV",
"authRequestId": "06EJSAKC9PX1P2VZW4YGS0X518",
"authSignature": "GpNbvxXs5QvWk3lN2PzfWgnVP7kf/HezW47gJ5nUd3I=",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcN98rAMDMKEHW6iUl/sK3ytDWhV/+sootHKD63BwkLf7nPyrkojvOWHLw7QMY1UzpKG8zKhUDgxW+Dh8UK+VDEgPXkHcF2xSraKOt4tevD48ozwawiXoKmzg9KOQehCDLK0YYhg8yiEtqXAWEcMqpPkqNlT7mnghfWOokCMFmJQGCVP2NIMHFos8AixkMgPadZUjSLdKeFpwIWGB5LnTKZm3wUXfwDzGljYiAX8ZPfo9XNmvkrFpy3RglYqy+l7JLzR84YswVMqP0hxSPC7EfeM1GrSxwcLgBd58S9qWZeYuSn2p0w7rUFgOTLNcZ7HAK9fDw27lzlPfbqPrhL8eNB+tY3Ic8YJG9H2698Jyv2AMxCpY8N+Uu5e3VWtD2Qm17Le0ARN9ntMmKQNsXqo6HU8o2erlwBX5xddWiEPk7YYr624Je34xoxoUkyIbNAu4BA7fP6+0JFUjQsTVsmZ2GdSXysQoXualLIdTtJlqgO1KenftjQx4XfPS3pl4hxP8BV0inoo4DXcgj65YFprd5QBqC0b20efGZQ3O6PykFzDFYXvnCfLmlo6lNKHg6CawAHBK+K7RqZeRuKpH4GfR5nq3A1FqfVYTVivk3ck7JwKESHFARo6O8NLvslQ3WqClXThOKIufTLNa1o9n0L9gjTC2FDRBgPwsxgaZXHtj3Wa3zWQoH46/sAA2z39szJ+I+IgEfsx++wyKigkaDoPlsb5dII/n2ywv6HAd6F6olpLcQvvllwLpXCkB4MmupokUw9TYI1U2gd2FdYGHgFaGGzXgm20FFTbJxu9idsiR7x2G56GegIjhgXgtLzEclt9x7ZRvsOMWXHXGvXrJpSw2RWwfQCGjtUM45wPvgqQp94qMXvd330C7tAmflDeS08G+AT2SI56mG1D1rZoCj3F3sTjcxjmbbYMOuKr7cWiba9F/YeL2ivETNCyVXdnxWcFGaKlEDxyvRd5aFZuYC1OeBNDysWL76ijfDcVTFJeDJLKoeMHJfOHcGP0rUTgQvXKYrUpnO6hA0IYUuajGxLCqHE9OB0re3LNEy2GBvcN5AZyJyLM6QBO8Op//V0DaDEmamO+aQzVfIveXbGpvlVlCTmaP9MYo3TvdxN1qCsGIl0QmKoGNiP/52Abey0QeOMfFq6lEDxyvRd5aFZuYC1OeBNDr93mSDShWnbfrf0iJVfLF20PpLGJtq1A59zxD3B7GeR2Uqr6WreqxoMpEBAAKbLAR2yaDW7unSwYs3IbslqTvwyeIOm8U+/WA+raJB4ewh3Wbp9Mrurq7GaPpHB2RhOrj/S8ej8XD9QYAHnAKKL/PQJVrCzOlGggOqtOyH9t0Ek1QjXEIe+fNuAPbCbXAjw6w+2WOzVencM2MrK0GS8DBiIzOsWkGUVPZnHVS1GT2SU7FmPseKXUAnWQap5wVsDy5F/Xw3B0hFMAZdrSQLN+t",
"savedPaymentMethods": null,
"successUrl": "http://localhost:8080/pgui/v2/hpp/worldpay/success",
"failureUrl": "http://localhost:8080/pgui/v2/hpp/worldpay/failure",
"pgResponse": {
"resultCode": "PASS",
"pgProvider": "WORLDPAY",
"data": {
"type": "WORLDPAY",
"pgRefId": "3592845796",
"returnUrl": "https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=LGETEST3%5EPGI_7202603277730815&Ticket=00177500323082302hx43VA8CApQK6sui8pi4vA0GOz8s8T1zqoAcWX&source=https%3A%2F%2Fsecure-test.worldpay.com",
"referenceUrl": "https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=LGETEST3%5EPGI_7202603277730815&Ticket=00177500323082302hx43VA8CApQK6sui8pi4vA0GOz8s8T1zqoAcWX&source=https%3A%2F%2Fsecure-test.worldpay.com"
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "WEBHOOK",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "WORLDPAY",
"method": "POST"
},
"requiresFollowUpApi": false,
"followUpApi": null
}
}
}
```
### 3.3 Response Samples
[tabs]
[tab:Card (WorldPay)]
```json : scrollable
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN1Q1E42FZPN6YT5PF8BZT88",
"timestamp": "2026-04-03T01:01:41.987427200Z",
"data": {
"status": "ACTION_REQUIRED",
"paymentUrl": "/pgui/v2/hpp/worldpay/paypal/wrapping?paymentContext=QfAy+og0Pc7OaUKV92YAcF6anMj8wv9uA0Srp+d+YmRDWhV/+sootHKD63BwkLf7nPyrko...",
"orderNo": "ORD_7202604037731552",
"pgTransactionId": "PGI_7202604037731554",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcF6anMj8wv9uA0Srp+d+YmRDWhV/+sootHKD63BwkLf7nPyrko...",
"savedPaymentMethods": null,
"successUrl": "https://devkic-payapi.nebp.lge.com/pgui/v2/hpp/worldpay/success",
"failureUrl": "https://devkic-payapi.nebp.lge.com/pgui/v2/hpp/worldpay/failure",
"pgResponse": {
"resultCode": "PASS",
"pgProvider": "WORLDPAY",
"data": {
"type": "WORLDPAY",
"pgRefId": "3594289311",
"returnUrl": "https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=LGETEST3%5EPGI_7202604037731554&Ticket=00177561010184602AR5AUHvlnns9OqZOj-c3bAP0hRdc2IKQRPpfRC&source=https%3A%2F%2Fsecure-test.worldpay.com",
"referenceUrl": "https://payments-test.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=LGETEST3%5EPGI_7202604037731554&Ticket=00177561010184602AR5AUHvlnns9OqZOj-c3bAP0hRdc2IKQRPpfRC&source=https%3A%2F%2Fsecure-test.worldpay.com"
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "WEBHOOK",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "WORLDPAY",
"method": "POST"
},
"requiresFollowUpApi": false,
"followUpApi": null
}
}
```
[tab:Card (Checkout.com)]
```json : scrollable
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN4BVGAT0TJTK2EJ8RM21ZE0",
"timestamp": "2026-04-03T07:12:16.131035200Z",
"data": {
"status": "ACTION_REQUIRED",
"paymentUrl": "/pgui/v2/hpp/checkoutcom/card/wrapping?paymentContext=QfAy+og0Pc7OaUKV92YAcJpgE/5feUx7nKM7nsA2oMRDWhV/+sootHKD63BwkLf7nPyrkojvOWHLw7QMY1UzpDeVUelxvMp...",
"orderNo": "ORD_7202604037731761",
"pgTransactionId": "PGI_7202604037731763",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcJpgE/5feUx7nKM7nsA2oMRDWhV/+sootHKD63BwkLf7nPyrkojvOWHLw7QMY1UzpDeVUelxvMp...",
"savedPaymentMethods": null,
"successUrl": "https://devkic-payapi.nebp.lge.com/pgui/v2/hpp/checkoutcom/success",
"failureUrl": "https://devkic-payapi.nebp.lge.com/pgui/v2/hpp/checkoutcom/failure",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "CHECKOUT_COM",
"data": {
"type": "CHECKOUT",
"publicKey": "pk_sbox_2ewvjanc7xpuduraa7tqquf5mmi",
"paymentSession": {
"id": "ps_3BpyWEErpjTiHWFQO6F5vYynqC5",
"payment_session_secret": "pss_06980ec7-3169-42ac-bd97-85f1b7cc14dd",
"payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzNCcHlXRUVycGpUaUhXRlFPNkY1dll5bnFDNSIsImVudGl0eV9pZCI6ImVudF8za2ZoaHZ6NXVld...",
"_links": {
"self": {
"href": "https://api.sandbox.checkout.com/payment-sessions/ps_3BpyWEErpjTiHWFQO6F5vYynqC5"
}
}
}
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "WEBHOOK",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "CHECKOUT_COM",
"method": "POST"
},
"requiresFollowUpApi": false,
"followUpApi": null
}
}
```
[tab:Card (Omise)]
```json : scrollable
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN41W5RTTKKDX4HRE5JV7NX4",
"timestamp": "2026-04-03T06:28:38.259142300Z",
"data": {
"status": "ACTION_REQUIRED",
"paymentUrl": "/pgui/v2/hpp/omise/card/wrapping?paymentContext=QfAy%2Bog0Pc7OaUKV92YAcOD%2FaZ2IDdOD9sJI9kzUoGtDWhV%2F%2B...",
"orderNo": "ORD_7202604037731725",
"pgTransactionId": "PGI_7202604037731727",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcOD/aZ2IDdOD9sJI9kzUoGtDWhV/...",
"savedPaymentMethods": null,
"successUrl": "https://devkic-payapi.nebp.lge.com/pgui/v2/hpp/omise/success",
"failureUrl": "https://devkic-payapi.nebp.lge.com/pgui/v2/hpp/omise/failure",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "OMISE",
"data": {
"type": "OMISE_CARD",
"publicKey": "pkey_test_66lmsec8z06uh3jzilx",
"amount": 2500,
"amountDecimal": 250000,
"currency": "THB",
"itemName": "Wireless Charger",
"orderNo": "ORD_7202604037731725",
"authRequestId": "06EN41W5RTTKKDX4HRE5JV7NX4",
"authSignature": "Ddr53aFJ/WBOkdFWcjVE6GqmHy4dciOpUbApXBUa+VU="
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "API",
"requiresClientAction": true,
"clientAction": {
"type": "TOKENIZE_CARD",
"pgProvider": "OMISE",
"method": "GET"
},
"requiresFollowUpApi": true,
"followUpApi": {
"method": "POST",
"url": "/api/v2/payments",
"description": "After card tokenization, call this Payment Creation API using the obtained token."
}
}
}
```
[tab:PayPal]
```json : scrollable
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EJSXACF3167DYF17DCKPV398",
"timestamp": "2026-03-27T01:42:48.101231400Z",
"data": {
"status": "ACTION_REQUIRED",
"paymentUrl": "/pgui/v2/hpp/worldpay/card/wrapping?paymentContext=QfAy%2Bog0Pc7OaUKV92YAcF8bIPJ1MnoOmpeUOWd9eYRDWhV%2F...",
"orderNo": "ORD_7202603277730925",
"pgTransactionId": "PGI_7202603277730929",
"paymentContext": "QfAy%2Bog0Pc7OaUKV92YAcF8bIPJ1MnoOmpeUOWd9eYRDWhV%2F...",
"savedPaymentMethods": null,
"successUrl": "https://devkic-payapi.nebp.lge.com/pgui/v2/hpp/worldpay/success",
"failureUrl": "https://devkic-payapi.nebp.lge.com/pgui/v2/hpp/worldpay/failure",
"pgResponse": {
"resultCode": "PASS",
"pgProvider": "WORLDPAY",
"data": {
"type": "WORLDPAY",
"pgRefId": "3592852189",
"returnUrl": "https://hpp-sandbox.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=LGETEST3%5EPGI_7202603277730929&Ticket=00177500776844702U-c7q9YvTrz7RVzEY-WJvQbS7JfWDoR3BcNo-0&source=https%3A%2F%2Fsecure-test.worldpay.com",
"referenceUrl": "https://hpp-sandbox.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey=LGETEST3%5EPGI_7202603277730929&Ticket=00177500776844702U-c7q9YvTrz7RVzEY-WJvQbS7JfWDoR3BcNo-0&source=https%3A%2F%2Fsecure-test.worldpay.com"
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "WEBHOOK",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "WORLDPAY",
"method": "POST"
},
"requiresFollowUpApi": false,
"followUpApi": null
}
}
```
[tab:Bank Transfer (태국)]
```json : scrollable
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EJSWXF1S9VSJVR3H832TWEY0",
"timestamp": "2026-03-27T01:41:01.060997300Z",
"data": {
"status": "ACTION_REQUIRED",
"paymentUrl": "/pgui/v2/hpp/omise/bank-transfer/wrapping",
"orderNo": "ORD_7202603277730917",
"pgTransactionId": "PGI_7202603277730920",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcJpgE/5feUx7nKM7nsA2oMRDWhV/+sootHKD63BwkLf7nPyrkojvOWHLw7QMY1UzpDeVUelxvMp...",
"savedPaymentMethods": null,
"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",
"pgName": "OMISE",
"data": {
"publicKey": "pkey_test_66lmsec8z06uh3jzilx",
"amount": 26100,
"amountDecimal": 2610000,
"currency": "THB",
"bankTransferSource": "mobile_banking_bay",
"platformType": "IOS",
"authRequestId": "06EJSWXF1S9VSJVR3H832TWEY0",
"authSignature": "552RtzZfrEkiZE/piQ9GQ62UWC8XqkckETlzzBUnxjg=",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcJpgE/5feUx7nKM7nsA2oMRDWhV/+sootHKD63BwkLf7nPyrkojvOWHLw7QMY1UzpDeVUelxvMp..."
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "API",
"requiresClientAction": true,
"clientAction": {
"type": "CREATE_SOURCE",
"provider": "OMISE"
},
"requiresFollowUpApi": true,
"followUpApi": {
"method": "POST",
"url": "/api/v2/payments",
"description": "After creating the payment intent, call this Payment Creation API using the obtained source ID."
}
}
}
```
[tab:Installment (태국)]
```json : scrollable
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN40N9V7N1PQXAH0GMBN91Z4",
"timestamp": "2026-04-03T06:23:19.800137100Z",
"data": {
"status": "ACTION_REQUIRED",
"paymentUrl": "/pgui/v2/hpp/omise/installment/wrapping?paymentContext=QfAy+og0Pc7OaUKV92YAcPQqpKNrGELf9Ty8UQO/rElDWhV/+...",
"orderNo": "ORD_7202604037731713",
"pgTransactionId": "PGI_7202604037731715",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcPQqpKNrGELf9Ty8UQO/rElDWhV/+...",
"savedPaymentMethods": null,
"successUrl": "http://localhost:8080/pgui/v2/hpp/omise/success",
"failureUrl": "http://localhost:8080/pgui/v2/hpp/omise/failure",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "OMISE",
"data": {
"type": "OMISE_INSTALLMENT",
"publicKey": "pkey_test_66lmsec8z06uh3jzilx",
"amount": 2500,
"amountDecimal": 250000,
"currencyCode": "THB",
"authRequestId": "06EN40N9V7N1PQXAH0GMBN91Z4",
"authSignature": "CRMmdgHJpcCiACWY6ZOGiUxOSjqTcv9zQsbVFXI3zD8=",
"installmentSource": "installment_kbank",
"installmentTerm": 3
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "API",
"requiresClientAction": true,
"clientAction": {
"type": "CREATE_SOURCE",
"provider": "OMISE"
},
"requiresFollowUpApi": true,
"followUpApi": {
"method": "POST",
"url": "/api/v2/payments",
"description": "After creating the payment intent, call this Payment Creation API using the obtained source ID."
}
}
}
```
[tab:Tabby (UAE)]
```json : scrollable
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN4HHZ63D5QPZD5FZV9H2ZX4",
"timestamp": "2026-04-03T07:37:09.299115500Z",
"data": {
"status": "ACTION_REQUIRED",
"paymentUrl": "/pgui/v2/hpp/checkoutcom/tabby/wrapping?paymentContext=QfAy%2Bog0Pc7OaUKV92YAcGpbC7at%2BRppP%2...",
"orderNo": "ORD_8202604037731809",
"pgTransactionId": "PGI_8202604037731811",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcGpbC7at+RppP/jsdoEbGb1DWhV/+...",
"savedPaymentMethods": null,
"successUrl": "http://localhost:8080/pgui/v2/hpp/checkoutcom/success",
"failureUrl": "http://localhost:8080/pgui/v2/hpp/checkoutcom/failure",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "CHECKOUT_COM",
"data": {
"type": "CHECKOUT",
"publicKey": "pk_sbox_2ewvjanc7xpuduraa7tqquf5mmi",
"paymentSession": {
"id": "ps_3Bq1XyvpnV2AwXjD0CepNgDfq6P",
"payment_session_secret": "pss_6d438e14-fecd-43d2-b23f-d038ccea89e0",
"payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzNCcTFYeXZwblYyQXdYakQwQ2VwTmdEZnE2UCIsImVudGl0eV9pZCI6ImVudF8za2ZoaHZ6NXVldXRmajVtNmpkYTRhYnB6YSIsImV4cGVyaW1lbnRzIjp7fSwicHJvY2Vzc2luZ19jaGFubmVsX2lkIjoicGNfa21teXVieWMyNnpldnBrcWx0eXZqdXBvbWUiLCJhbW91bnQiOjI4MjUwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkFFRCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiXSwic2NoZW1lX2Nob2ljZV9lbmFibGVkIjpmYWxzZSwic3RvcmVfcGF5bWVudF9kZXRhaWxzIjoiZGlzYWJsZWQiLCJiaWxsaW5nX2FkZHJlc3MiOnsiY291bnRyeSI6IkFFIn19LHsidHlwZSI6ImFwcGxlcGF5IiwiZGlzcGxheV9uYW1lIjoiTEcgVUFFIiwiY291bnRyeV9jb2RlIjoiQUUiLCJjdXJyZW5jeV9jb2RlIjoiQUVEIiwibWVyY2hhbnRfY2FwYWJpbGl0aWVzIjpbInN1cHBvcnRzM0RTIl0sInN1cHBvcnRlZF9uZXR3b3JrcyI6WyJ2aXNhIiwibWFzdGVyQ2FyZCJdLCJ0b3RhbCI6eyJsYWJlbCI6IkxHIFVBRSIsInR5cGUiOiJmaW5hbCIsImFtb3VudCI6IjI4MjUifX0seyJ0eXBlIjoiZ29vZ2xlcGF5IiwibWVyY2hhbnQiOnsiaWQiOiIwODExMzA4OTM4NjI2ODg0OTk4MiIsIm5hbWUiOiJMRyBVQUUiLCJvcmlnaW4iOiJodHRwOi8vbG9jYWxob3N0OjgwODAifSwidHJhbnNhY3Rpb25faW5mbyI6eyJ0b3RhbF9wcmljZV9zdGF0dXMiOiJGSU5BTCIsInRvdGFsX3ByaWNlIjoiMjgyNSIsImNvdW50cnlfY29kZSI6IkFFIiwiY3VycmVuY3lfY29kZSI6IkFFRCJ9LCJjYXJkX3BhcmFtZXRlcnMiOnsiYWxsb3dlZF9hdXRoX21ldGhvZHMiOlsiUEFOX09OTFkiLCJDUllQVE9HUkFNXzNEUyJdLCJhbGxvd2VkX2NhcmRfbmV0d29ya3MiOlsiVklTQSIsIk1BU1RFUkNBUkQiXX19LHsidHlwZSI6InRhYmJ5IiwiY291bnRyeV9jYWxsaW5nX2NvZGVzIjpbIjk3MSJdLCJlbWFpbCI6InpheWVkLmFAZXhhbXBsZS5hZSJ9XSwiZmVhdHVyZV9mbGFncyI6WyJhbmFseXRpY3Nfb2JzZXJ2YWJpbGl0eV9lbmFibGVkIiwiZ2V0X3dpdGhfcHVibGljX2tleV9lbmFibGVkIiwibG9nc19vYnNlcnZhYmlsaXR5X2VuYWJsZWQiLCJyaXNrX2pzX2VuYWJsZWQiLCJ1c2VfYmlsbGluZ19hZGRyZXNzX2Zyb21fY29uZmlnX2Zvcl90b2tlbml6YXRpb24iLCJ1c2VfZGV2aWNlX2FwaV9mb3Jfb2JzZXJ2YWJpbGl0eSIsInVzZV9yaXNranNfdjIiLCJ1c2VfdXJsX2hhc2hfZm9yX2lmcmFtZV9wcm9wcyJdLCJyaXNrIjp7ImVuYWJsZWQiOmZhbHNlfSwibWVyY2hhbnRfbmFtZSI6IkxHIFVBRSIsInBheW1lbnRfc2Vzc2lvbl9zZWNyZXQiOiJwc3NfNmQ0MzhlMTQtZmVjZC00M2QyLWIyM2YtZDAzOGNjZWE4OWUwIiwiaW50ZWdyYXRpb25fZG9tYWluIjoiYXBpLnNhbmRib3guY2hlY2tvdXQuY29tIn0=",
"_links": {
"self": {
"href": "https://api.sandbox.checkout.com/payment-sessions/ps_3Bq1XyvpnV2AwXjD0CepNgDfq6P"
}
}
}
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "WEBHOOK",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "CHECKOUT_COM",
"method": "POST"
},
"requiresFollowUpApi": false,
"followUpApi": null
}
}
```
[tab:Tamara (UAE)]
```json : scrollable
{
"resultCode": "0",
"message": "SUCCESS",
"requestId": "06EN4H3C9QMHEAZYS6YQZJC7GC",
"timestamp": "2026-04-03T07:35:09.863177500Z",
"data": {
"status": "ACTION_REQUIRED",
"paymentUrl": "/pgui/v2/hpp/checkoutcom/tamara/wrapping?paymentContext=QfAy%2Bog0Pc7OaUKV92YAcF5qAbtkl%2BEuYAbqu5aS5KFDWhV%2F%2...",
"orderNo": "ORD_8202604037731801",
"pgTransactionId": "PGI_8202604037731803",
"paymentContext": "QfAy+og0Pc7OaUKV92YAcF5qAbtkl+EuYAbqu5aS5KFDWhV/...",
"savedPaymentMethods": null,
"successUrl": "http://localhost:8080/pgui/v2/hpp/checkoutcom/success",
"failureUrl": "http://localhost:8080/pgui/v2/hpp/checkoutcom/failure",
"pgResponse": {
"resultCode": "OK",
"pgProvider": "CHECKOUT_COM",
"data": {
"type": "CHECKOUT",
"publicKey": "pk_sbox_2ewvjanc7xpuduraa7tqquf5mmi",
"paymentSession": {
"id": "ps_3Bq1IsElSF2ZoM1aZtuTBv4Mfg6",
"payment_session_secret": "pss_fc314af0-b0b1-49e7-b2be-469bd6c33d50",
"payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzNCcTFJc0VsU0YyWm9NMWFadHVUQnY0TWZnNiIsImVudGl0eV9pZCI6ImVudF8za2ZoaHZ6NX...",
"_links": {
"self": {
"href": "https://api.sandbox.checkout.com/payment-sessions/ps_3Bq1IsElSF2ZoM1aZtuTBv4Mfg6"
}
}
}
}
}
},
"instructions": {
"nextStep": "CLIENT_ACTION",
"completionMethod": "WEBHOOK",
"requiresClientAction": true,
"clientAction": {
"type": "REDIRECT_TO_HPP",
"pgProvider": "CHECKOUT_COM",
"method": "POST"
},
"requiresFollowUpApi": false,
"followUpApi": null
}
}
```
[/tabs]
## 4. 응답 후처리 가이드 (Next Steps)
결제 의사 생성 API 호출 후, 응답의 `status`가 `ACTION_REQUIRED`이고 `instructions.nextStep`이 `CLIENT_ACTION`인 경우, 클라이언트는 제공된 데이터를 기반으로 사용자가 결제를 진행할 수 있도록 화면을 전환하거나 PG SDK를 초기화해야 합니다.
상점의 환경과 요구사항에 따라 **리다이렉트 연동(HPP Wrapping)** 방식과 **직접 연동(Direct PG SDK/UI 렌더링)** 방식 중 선택하여 처리할 수 있습니다.
### 4.1 리다이렉트 연동 (간편 연동)
EBP가 제공하는 결제 페이지로 사용자를 이동시켜 결제를 처리하는 가장 간단한 방식입니다. 상점은 각 PG사별 복잡한 SDK 연동 로직을 직접 구현할 필요가 없습니다.
- **대상 필드**: `data.paymentUrl`
- **처리 방법**: 전달받은 `paymentUrl`에는 결제 인증에 필요한 암호화된 컨텍스트가 쿼리 파라미터로 포함되어 있습니다. 상점은 이 URL로 **GET 방식으로 직접 이동(redirect)** 하면 됩니다.
#### 연동 예시 (공통)
결제 의사 생성 API 응답으로 받은 `paymentUrl`을 다음과 같이 사용합니다.
**1. HTML 설정 (데이터 전송을 위한 가상 Form)**
```html
```
**2. Javascript 처리 예시**
```javascript
// 1. EBP 결제 의사 생성 API로부터 응답 데이터 수신
const { paymentUrl } = response.data;
// 2. form action에 paymentUrl 설정
const form = document.getElementById("ebp-redirect-form");
form.action = paymentUrl;
// 3. form submit (결제 페이지로 리다이렉트)
form.submit();
```
> **참고 사항:**
> - `paymentUrl` 자체에 결제 컨텍스트(`paymentContext`)가 포함되어 있으므로, Form 내부에 별도의 Input 필드를 생성하거나 데이터를 직접 조립할 필요가 없습니다. 브라우저가 POST 요청을 보내면서 URL의 Query String을 유지하며, EBP는 이를 수신하여 해당 PG사의 결제 화면을 안전하게 구성합니다.
> - **`paymentUrl`을 통한 리다이렉트 방식을 사용할 경우**, 응답 데이터에 후속 API 호출 여부(`requiresFollowUpApi`)나 상세 정보(`followUpApi`)가 있더라도 EBP가 모든 인증 및 승인 프로세스를 직접 마감합니다. 상점은 별도의 결제 생성 API를 호출할 필요 없이 웹훅이나 최종 리다이렉트 URL을 통해 결과만 확인하면 됩니다.
### 4.2 직접 연동 (커스텀 연동)
상점의 기존 결제 화면 내에 PG사가 제공하는 UI 컴포넌트(Drop-in)를 직접 렌더링하고자 할 때 사용하는 방식입니다.
- **대상 필드**: `data.pgResponse.data` 내의 PG사별 인증 정보
- **처리 방법**: 각 PG사별로 반환되는 Key, Token 값 등을 활용해 PG SDK를 초기화하고 프론트엔드 환경에서 결제를 진행합니다.
#### Worldpay 직접 연동 예시
Worldpay는 전달받은 `referenceUrl`을 사용하여 PG SDK를 초기화합니다.
**1. HTML 설정**
```html
```
**2. Javascript 처리 예시**
```javascript
const { referenceUrl } = response.data.pgResponse.data;
const customOptions = {
url: referenceUrl,
type: "iframe",
inject: "onload",
target: "worldpay-container",
accessibility: true,
language: "ko",
country: "KR",
successURL: response.data.successUrl,
cancelURL: response.data.failureUrl,
failureURL: response.data.failureUrl,
errorURL: response.data.failureUrl
};
if (customOptions.url) {
const libraryObject = new WPCL.Library();
libraryObject.setup(customOptions);
}
```
#### Checkout.com 직접 연동 예시
Checkout.com은 전달받은 `publicKey`와 `paymentSession` 객체를 사용하여 **Flow UI** 컴포넌트를 마운트합니다.
**1. HTML 설정 (SDK 로드 및 마운트 지점 정의)**
```html
```
**2. Javascript 처리 예시**
```javascript
const { publicKey, paymentSession } = response.data.pgResponse.data;
// 1. Checkout Web SDK 초기화
const checkout = await CheckoutWebComponents({
publicKey: publicKey,
environment: 'sandbox', // 또는 'production'
paymentSession: paymentSession, // 객체 전체를 전달
onPaymentCompleted: (component, paymentResponse) => {
window.location.href = response.data.successUrl;
},
onError: (component, error) => {
console.error("Checkout Error:", error);
}
});
// 2. Flow 컴포넌트 생성 및 마운트
const flowComponent = checkout.create('flow');
flowComponent.mount('#checkout-container');
```
#### Omise Card 직접 연동 예시
신용카드 결제는 `publicKey`를 사용하여 일회성 Token을 생성한 뒤, 해당 토큰 정보를 포함하여 EBP의 결제 생성 API를 호출합니다.
**1. HTML 설정**
```html
```
**2. Javascript 처리 예시**
```javascript
const { publicKey, authRequestId, authSignature, paymentHeaderContext, paymentContext, amount, currency } = response.data.pgResponse.data;
// Omise SDK 설정
OmiseCard.configure({ publicKey: publicKey });
document.getElementById('omise-card-btn').onclick = () => {
OmiseCard.open({
amount: amount,
currency: currency,
onCreateTokenSuccess: async (token) => {
const paymentBody = {
authRequestId,
authSignature,
paymentContext,
paymentMethod: "CARD",
paymentInstrumentId: token,
paymentInstrumentType: "ONE_TIME_TOKEN"
};
const host = 'https://devkic-payapi.nebp.lge.com/';
// EBP 결제 생성 API 호출
const chargeResponse = await fetch(`${host}/api/v2/payments`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-EBP-Context': paymentHeaderContext
},
body: JSON.stringify(paymentBody)
});
if (!chargeResponse.ok) throw new Error("Payment API 호출 실패");
const result = await chargeResponse.json();
// 3DS 인증이 필요한 경우 authorizeUri로 이동
const authorizeUri = result.data?.pgResponse?.data?.authorizeUri;
if (authorizeUri) {
window.location.href = authorizeUri;
} else if (result.resultCode === "0") {
window.location.href = response.data.successUrl;
}
}
});
};
```
#### Omise Installment (Source) 직접 연동 예시
할부 등 소스 기반 결제는 결제 요청 전 `createSource`를 통해 일회성 소스 ID를 생성합니다.
**1. HTML 설정**
```html
```
**2. Javascript 처리 예시**
```javascript
const { publicKey, authRequestId, authSignature, paymentHeaderContext, paymentContext, installmentSource, installmentTerm, amountDecimal, currency } = response.data.pgResponse.data;
Omise.setPublicKey(publicKey);
document.getElementById('omise-installment-btn').onclick = () => {
const sourceParams = {
type: installmentSource,
amount: Number(amountDecimal), // 소스 생성 시에는 소수점 포함 금액 사용
currency: currency,
installment_term: installmentTerm
};
Omise.createSource(sourceParams.type, sourceParams, async (statusCode, res) => {
if (statusCode === 200) {
const paymentBody = {
authRequestId,
authSignature,
paymentContext,
paymentMethod: "INSTALLMENT",
paymentInstrumentId: res.id,
paymentInstrumentType: "ONE_TIME_SOURCE"
};
const host = 'https://devkic-payapi.nebp.lge.com/';
// EBP 결제 생성 API 호출
const paymentResponse = await fetch(`${host}/api/v2/payments`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-EBP-Context': paymentHeaderContext
},
body: JSON.stringify(paymentBody)
});
const result = await paymentResponse.json();
// 3DS 인증이 필요한 경우 authorizeUri로 이동
const authorizeUri = result.data?.pgResponse?.data?.authorizeUri;
if (authorizeUri) {
window.location.href = authorizeUri;
} else if (result.resultCode === "0") {
window.location.href = response.data.successUrl;
}
}
});
};
```