### Application Registration and Setup

Source: https://developers.kakaopay.com/docs/payment/online/common

Details on how to register your application, obtain credentials like Client ID and Secret Key, and set up your service domain for using the KakaoPay Online Payment API.

```APIDOC
## Application Registration and Setup

### Description
To utilize the KakaoPay Online Payment API, you must first register your application. This process involves obtaining a Client ID and Secret Key, and configuring your service domain. A Merchant ID (CID) is issued after merchant verification, which is then used in conjunction with the Secret Key to make API calls.

### Steps:
1.  **Register Application**: Create or register your application within the KakaoPay developer console.
2.  **Obtain Credentials**: Secure your Client ID and Secret Key. Treat the Secret Key with utmost care to prevent security breaches.
3.  **Register Service Domain**: Add your website domain to the 'Platform' settings within your application's configuration. Wildcard domains are supported, with a maximum of 10 domains allowed.
4.  **BizApp Conversion**: Ensure your application is converted to a BizApp and that you have been granted permission to use the Online Payment API. Refer to the 'Getting Started > Basic Guide > API and Application Types' for detailed instructions.
5.  **Verify Credentials**: After application registration, your issued credentials will be visible in the 'My Applications' list. Consult the 'Getting Started > API Common Guide > Prerequisites' for more information on authentication credentials.
```

--------------------------------

### Request Subscription Payment (cURL)

Source: https://developers.kakaopay.com/docs/payment/online/subscription

Example cURL request to initiate a subscription payment. It includes the endpoint, authorization header, content type, and a JSON payload with subscription details like CID, SID, partner IDs, item name, quantity, and amounts.

```curl
curl --location 'https://open-api.kakaopay.com/online/v1/payment/subscription' \
--header 'Authorization: SECRET_KEY ${SECRET_KEY}' \
--header 'Content-Type: application/json' \
--data '{ \
		"cid": "TCSUBSCRIP", \
		"sid" : "S1234567890987654321", \
		"partner_order_id": "subscription_order_id_1", \
		"partner_user_id": "subscription_user_id_1", \
        "item_name": "음악정기결제", \
        "quantity": 1, \
        "total_amount": 9900, \
        "vat_amount": 900, \
        "tax_free_amount": 0 \
	}'
```

--------------------------------

### Kakao Pay Online Payment - Reference Guides

Source: https://developers.kakaopay.com/docs/payment/online/reference

Provides links to supplementary guides for using the Kakao Pay Online Payment API, including file services for payment/settlement data and transaction slips.

```APIDOC
## 참고 자료

온라인 결제 API를 보다 유용하게 사용할 수 있는 여러 가이드 문서를 제공하고 있습니다.

* 파일서비스 가이드 : 결제/정산/입금내역 대사파일 제공을 위한 API 가이드입니다.   
카카오페이 파일서비스 가이드 v2.5
* 전표가이드 : 카카오페이 머니/카드결제 시 발생되는 거래확인증, 카드매출전표, 현금영수증을 확인할 수 있는 API 가이드입니다.  
카카오페이 전표 가이드 v1.2

* 온라인 결제 서비스 소개
* 온라인 결제 가맹점 신청 안내
* 운영 가이드
```

--------------------------------

### Response: Subscription Payment Successful (CARD)

Source: https://developers.kakaopay.com/docs/payment/online/subscription

Example JSON response for a successful subscription payment where the payment method is CARD. It includes payment details, card-specific information (BIN, type, approval ID, issuer, etc.), and timestamps.

```json
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
  "cid": "TCSUBSCRIP",
  "aid": "A5678901234567890123",
  "tid": "T2468013579246801357",
  "sid": "S1234567890987654321",
  "partner_user_id": "subscription_user_id_1",
  "partner_order_id": "subscription_order_id_1",
  "payment_method_type": "CARD",
  "item_name": "카페아메리카노",
  "quantity": 1,
  "amount": {
    "total": 3200,
    "tax_free": 0,
    "vat": 0,
    "discount": 0,
    "point": 0,
    "green_deposit": 0
  },
  "card_info": {
    "bin": "621640",
    "card_type": "체크",
    "card_mid": "123456789",
    "approved_id": "12345678",
    "install_month": "00",
    "installment_type": "CARD_INSTALLMENT",
    "kakaopay_purchase_corp": "비씨카드",
    "kakaopay_purchase_corp_code": "104",
    "kakaopay_issuer_corp": "수협은행",
    "kakaopay_issuer_corp_code": "212"
  },
  "created_at": "2019-05-21T11:18:24",
  "approved_at": "2019-05-21T11:18:32"
}
```

--------------------------------

### Response: Subscription Payment Failed

Source: https://developers.kakaopay.com/docs/payment/online/subscription

Example JSON response for a failed subscription payment. It indicates a 'Bad Request' with an error code and message, providing details about the failure reason.

```json
HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8
{
  "error_code": -782,
  "error_message": "subscription failure!",
  "extras": {
    "method_result_code": "8008",
    "method_result_message": "거래거절 거래금액미달"
  }
}
```

--------------------------------

### Response: Subscription Payment Successful (MONEY)

Source: https://developers.kakaopay.com/docs/payment/online/subscription

Example JSON response for a successful subscription payment where the payment method is MONEY. It includes payment details like AID, TID, partner IDs, payment method type, item name, quantity, amounts, and timestamps.

```json
HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
{
  "aid": "A5678901234567890123",
  "cid": "TCSUBSCRIP",
  "sid": "S1234567890987654321",
  "tid": "T2468013579246801357",
  "partner_order_id": "subscription_order_id_1",
  "partner_user_id": "subscription_user_id_1",
  "payment_method_type": "MONEY",
  "item_name": "음악정기결제",
  "quantity": 1,
  "amount": {
    "total": 9900,
    "tax_free": 0,
    "vat": 900,
    "green_deposit": 0
  },
  "created_at": "2023-07-15T21:18:22",
  "approved_at": "2023-07-15T21:18:22"
}
```

--------------------------------

### POST /online/v1/payment/subscription

Source: https://developers.kakaopay.com/docs/payment/online/subscription

Request a recurring payment using a Subscription ID (SID). This API is used for subsequent payments after the initial subscription setup, allowing for automated payments without further user authentication.

```APIDOC
## POST /online/v1/payment/subscription

### Description
Request a recurring payment using a Subscription ID (SID). This API is used for subsequent payments after the initial subscription setup, allowing for automated payments without further user authentication. The response includes detailed payment information upon successful recurring payment. In case of failure, the response may include failure reasons specific to the payment method (money/card).

### Method
POST

### Endpoint
https://open-api.kakaopay.com/online/v1/payment/subscription

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cid** (String) - Required - Merchant ID, 10 characters.
- **cid_secret** (String) - Optional - Merchant ID authentication key, 24 characters, combination of digits and lowercase letters.
- **sid** (String) - Required - Subscription ID, 20 characters.
- **partner_order_id** (String) - Required - Partner's order ID, up to 100 characters.
- **partner_user_id** (String) - Required - Partner's user ID, up to 100 characters. Must match the value passed in the initial payment request that issued the SID.
- **item_name** (String) - Required - Product name, up to 100 characters.
- **item_code** (String) - Optional - Product code, up to 100 characters.
- **quantity** (Integer) - Required - Product quantity.
- **total_amount** (Integer) - Required - Total product amount.
- **tax_free_amount** (Integer) - Required - Tax-free product amount.
- **vat_amount** (Integer) - Optional - VAT amount for the product. If not provided, VAT is calculated automatically as (Total Product Amount - Tax-Free Product Amount) / 11, rounded down.
- **green_deposit** (Integer) - Optional - Cup deposit amount.
- **payload** (String) - Optional - Value to store for the payment approval request, up to 200 characters.

### Request Example
```json
{
		"cid": "TCSEQUENCE",
		"cid_secret": "cid_secret_key",
		"sid": "S3053525180116443448",
		"partner_order_id": "subscription_order_id_2",
		"partner_user_id": "subscription_user_id_1",
		"item_name": "정기결제 테스트",
		"quantity": 1,
		"total_amount": 5000,
		"tax_free_amount": 0,
		"vat_amount": 454,
		"payload": "user_defined_payload"
	}
```

### Response
#### Success Response (200)
- **cid** (String) - Merchant ID.
- **aid** (String) - Approval ID.
- **tid** (String) - Transaction ID.
- **sid** (String) - Subscription ID.
- **partner_order_id** (String) - Partner's order ID.
- **partner_user_id** (String) - Partner's user ID.
- **payment_method_type** (String) - Type of payment method.
- **item_name** (String) - Name of the item.
- **quantity** (Integer) - Quantity of the item.
- **amount** (Object) - Details about the transaction amount.
  - **total** (Integer) - Total amount.
  - **tax_free** (Integer) - Tax-free amount.
  - **vat** (Integer) - VAT amount.
  - **discount** (Integer) - Discount amount.
  - **point** (Integer) - Point used.
  - **green_deposit** (Integer) - Green deposit amount.
- **card_info** (Object) - Details about the card used for payment.
  - **interest_free_install** (String) - Indicates if interest-free installments are applied.
  - **bin** (String) - Bank Identification Number (BIN) of the card.
  - **card_type** (String) - Type of the card.
  - **card_mid** (String) - Merchant ID of the card acquirer.
  - **approved_id** (String) - Approved transaction ID from the card network.
  - **install_month** (String) - Number of installments.
  - **installment_type** (String) - Type of installment plan.
  - **kakaopay_purchase_corp** (String) - Issuing card company name.
  - **kakaopay_purchase_corp_code** (String) - Issuing card company code.
  - **kakaopay_issuer_corp** (String) - Acquiring card company name.
  - **kakaopay_issuer_corp_code** (String) - Acquiring card company code.
- **sequential_payment_methods** (Array) - List of sequential payment methods used.
  - **payment_priority** (Integer) - Priority of the payment method.
  - **sid** (String) - Subscription ID for the payment method.
  - **payment_method_type** (String) - Type of payment method.
  - **card_info** (Object) - Details about the card used.
- **created_at** (String) - Timestamp when the transaction was created.
- **approved_at** (String) - Timestamp when the transaction was approved.

#### Response Example
```json
{
  "cid": "TCSEQUENCE",
  "aid": "A1234567890123456789",
  "tid": "T9876543210987654321",
  "sid": "S3053525180116443448",
  "partner_order_id": "subscription_order_id_2",
  "partner_user_id": "subscription_user_id_1",
  "payment_method_type": "CARD",
  "item_name": "정기결제 테스트",
  "quantity": 1,
  "amount": {
    "total": 5000,
    "tax_free": 0,
    "vat": 454,
    "discount": 0,
    "point": 0,
    "green_deposit": 0
  },
  "card_info": {
    "interest_free_install": "N",
    "bin": "411111",
    "card_type": "신용",
    "card_mid": "1234567890",
    "approved_id": "9876543210",
    "install_month": "00",
    "installment_type": "CARD_INSTALLMENT",
    "kakaopay_purchase_corp": "신한카드",
    "kakaopay_purchase_corp_code": "701",
    "kakaopay_issuer_corp": "신한카드",
    "kakaopay_issuer_corp_code": "701"
  },
  "sequential_payment_methods": [
    {
      "payment_priority": 1,
      "sid": "S3053525180116443448",
      "payment_method_type": "CARD",
      "card_info": {
         "bin": "411111",
         "card_type": "신용",
         "kakaopay_purchase_corp": "신한카드",
         "kakaopay_purchase_corp_code": "701",
         "kakaopay_issuer_corp": "신한카드",
         "kakaopay_issuer_corp_code": "701"
      }
    }
  ],
  "created_at": "2023-07-16T10:00:00",
  "approved_at": "2023-07-16T10:00:00"
}
```
```

--------------------------------

### Partnership and Test Environment

Source: https://developers.kakaopay.com/docs/payment/online/common

Information on the partnership process and how to test the Online Payment API using the mockup (test) environment before formal integration.

```APIDOC
## Partnership and Test Environment

### Description
This section details the process for establishing a partnership with KakaoPay to utilize the Online Payment API in a live environment, and how to leverage the mockup environment for testing.

### Partnership:
- To use the Online Payment API in a live service, a partnership agreement with KakaoPay is required. Partnership proposals can be submitted through the online merchant application page.
- Testing of the Online Payment API is possible even before finalizing a partnership agreement.

### Mockup (Test) Environment:
- KakaoPay provides a mockup (test) environment that allows you to test the Online Payment API functionalities according to each environment's specifications without needing a formal partnership.

### Merchant Application Process:
To use the Online Payment API, you must complete the 'Online Payment Merchant Application' process. The application path varies depending on your hosting environment:

| Category                           | Application Path                                                                              |
|------------------------------------|-----------------------------------------------------------------------------------------------|
| Hosting Shopping Mall Merchant App | Partner Center > Merchant Application > Online Payment > Merchant Application Guide > Hosting Shopping Mall |
| Independent Shopping Mall Merchant App | Partner Center > Merchant Application > Online Payment > Merchant Application Guide > Independent Shopping Mall |
```

--------------------------------

### Payment Process: User Payment Method Transition

Source: https://developers.kakaopay.com/docs/payment/online/common

Explains how users transition to the KakaoPay payment method on different platforms (PC, Mobile) and potential outcomes during this transition.

```APIDOC
## Payment Process: 2. User Payment Method Transition

### Description
This step details how users are directed to the KakaoPay payment interface after initiating a payment, covering different platform experiences and potential redirection scenarios.

### Transition Methods:
- **PC**: Users transition to their KakaoPay payment method via QR code or TMS (Telemarketing Service). TMS involves sending a payment request message to the user's KakaoTalk via phone number and date of birth, allowing them to proceed to the payment screen.
- **Mobile/APP**: Users are automatically transitioned to the KakaoPay payment method.

### Bridge Page Behavior:
During the transition via the bridge page, the following events may occur:
- **Request Cancellation**: If the user cancels the request, they will be redirected to the `cancel_url`.
- **Request Timeout**: If the request's validity period (15 minutes) expires, the user will be redirected to the `fail_url`.
```

--------------------------------

### POST /online/v1/payment/ready

Source: https://developers.kakaopay.com/docs/payment/online/subscription

Prepare for a payment transaction, typically the first step in a payment flow. This API is used to request payment details from the partner and to create a payment transaction.

```APIDOC
## POST /online/v1/payment/ready

### Description
Prepare for a payment transaction, typically the first step in a payment flow. This API is used to request payment details from the partner and to create a payment transaction.

### Method
POST

### Endpoint
https://open-api.kakaopay.com/online/v1/payment/ready

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cid** (String) - Required - Partner's merchant ID.
- **partner_order_id** (String) - Required - Partner's unique order ID.
- **partner_user_id** (String) - Required - Partner's unique user ID.
- **item_name** (String) - Required - Name of the item being purchased.
- **quantity** (String) - Required - Quantity of the item.
- **total_amount** (String) - Required - Total amount of the transaction.
- **vat_amount** (String) - Required - Amount of VAT.
- **tax_free_amount** (String) - Required - Tax-free amount.
- **approval_url** (String) - Required - URL to redirect upon successful approval.
- **fail_url** (String) - Required - URL to redirect upon failure.
- **cancel_url** (String) - Required - URL to redirect upon cancellation.

### Request Example
```json
{
	"cid": "TCSEQUENCE",
	"partner_order_id": "subscription_order_id_1",
	"partner_user_id": "subscription_user_id_1",
	"item_name": "음악정기결제",
	"quantity": "1",
	"total_amount": "9900",
	"vat_amount": "900",
	"tax_free_amount": "0",
	"approval_url": "https://developers.kakao.com/success",
	"fail_url": "https://developers.kakao.com/fail",
	"cancel_url": "https://developers.kakao.com/cancel"
}
```

### Response
#### Success Response (200)
- **tid** (String) - Transaction ID.
- **next_redirect_app_url** (String) - URL to redirect to the KakaoPay app.
- **next_redirect_mobile_url** (String) - URL to redirect to the mobile web page.
- **next_redirect_pc_url** (String) - URL to redirect to the PC web page.
- **android_app_scheme** (String) - Android app scheme for deep linking.
- **ios_app_scheme** (String) - iOS app scheme for deep linking.
- **created_at** (String) - Timestamp when the transaction was created.

#### Response Example
```json
{
  "tid":"T1234567890123456789",
  "next_redirect_app_url":"https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/aInfo",
  "next_redirect_mobile_url":"https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/mInfo",
  "next_redirect_pc_url":"https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/info",
  "android_app_scheme":"kakaotalk://kakaopay/pg?url=https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/order",
  "ios_app_scheme":"kakaotalk://kakaopay/pg?url=https://mockup-pg-web.kakao.com/v1/xxxxxxxxxx/order",
  "created_at":"2023-07-15T21:18:22"
}
```
```

--------------------------------

### Request to Inactivate Subscription (cURL)

Source: https://developers.kakaopay.com/docs/payment/online/subscription

Example cURL request to deactivate a subscription. It specifies the API endpoint for managing subscriptions, authorization, content type, and a JSON payload containing the CID and SID to be deactivated.

```curl
curl --location 'https://open-api.kakaopay.com/online/v1/payment/manage/subscription/inactive' \
--header 'Authorization: SECRET_KEY ${SECRET_KEY}' \
--header 'Content-Type: application/json' \
--data '{ \
		"cid": "TCSUBSCRIP", \
		"sid" : "S1234567890987654321" \
	}'
```

--------------------------------

### Payment Process: Payment Preparation

Source: https://developers.kakaopay.com/docs/payment/online/common

Details on the initial step of the payment process, which involves calling the 'ready' API with transaction details and mapping the returned TID.

```APIDOC
## Payment Process: 1. Payment Preparation

### Description
The first step in the payment process involves calling the 'ready' API with essential transaction details. This API call returns a Transaction ID (TID) which must be mapped and stored for subsequent operations.

### Procedure:
1.  **Call Ready API**: Initiate the payment process by calling the 'ready' API. Include necessary information such as Merchant Code (CID), the merchant's unique order number (partner_order_id), and the total amount (total_amount).
2.  **Map TID**: Upon receiving a successful response, map the provided Transaction ID (TID) to your order. This TID will be used for payment approval API calls, transaction status inquiries, and reconciliation processes.

### Redirection URLs:
- **`approval_url`, `cancel_url`, `fail_url`**: These URLs are used to handle the responses from the KakaoPay API calls. The domains for these URLs must match the web platform domains registered in your application information.

### Redirecting for Payment:
- **PC**: The payment waiting screen is displayed via a popup or layer using the `next_redirect_pc_url` provided in the response.
- **MobileWeb/APP**: The payment waiting screen is displayed using the `next_redirect_mobile_url` or `next_redirect_app_url` from the response. This transitions to the payment method through a bridge page.

*Note*: Using iframe to display the payment window is not recommended due to security concerns. Refer to the notice regarding CSP (Content Security Policy) for iframe payment window handling.
```

--------------------------------

### 코드송금 링크 발급 API 샘플 요청 (curl)

Source: https://developers.kakaopay.com/docs/moneytransfer/sendmoney.code/api-qrlink-create

curl 명령어를 사용하여 코드송금 링크 발급 API를 호출하는 예제입니다. 인증을 위한 액세스 토큰을 포함합니다.

```curl
curl --location --request POST 'https://open-api.kakaopay.com/connect/api/v1/money-transaction/link' \
--header 'Authorization: Bearer 0bb95a88c9724f5a52ddece574f5bdc96141aeaf5adccb3bf3a77983b42161d237f0f4c5'

```

--------------------------------

### Kakao Pay API Error Handling

Source: https://developers.kakaopay.com/docs/payment/online/reference

This section details how Kakao Pay handles API responses, including success and error scenarios. It outlines the structure of error responses and provides examples for common failure cases.

```APIDOC
## API 응답

카카오페이 플랫폼은 API 요청에 대해 11초의 Timeout을 가지고 있습니다. API 요청에 대해 응답 코드와 응답 필드로 구성된 응답을 제공합니다.

### 응답코드

응답 코드는 요청에 대한 상태를 나타내는 `HTTP 상태 코드(Status code)`, 에러에 대한 정보를 담은 `에러 코드(Error code)`로 나뉩니다.

요청 성공 시 `HTTP 상태 코드 200`과 함께 요청에 대한 `응답 본문(response body)`이 반환되고, 요청이 실패한 경우 `error_code`와 `error_message`로 이루어진 에러 코드를 반환합니다.

카카오페이에서 제공하는 공통 에러형태는 [시작하기 > API 공통가이드 > 에러 코드]를 참고하시기 바랍니다.

### 에러코드

결제 오류코드 다운로드 (v1.7) 카카오페이 발급사/매입사 코드정보 다운로드(v2.4)

### 요청 실패 응답

```
HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8 
{
  "error_code": -731,
  "error_message": "invalid cid!"
}
```

### 원천사(머니/카드) 실패 응답

```
HTTP/1.1 400 Bad Request
Content-type: application/json;charset=UTF-8     
{
  "error_code": -780,
  "error_message": "approval failure!",
  "extras": {
    "method_result_code": "USER_LOCKED",
    "method_result_message": "진행중인 거래가 있습니다. 잠시 후 다시 시도해 주세요."
  }
}
```
```

--------------------------------

### 코드송금 링크 발급 API 성공 응답

Source: https://developers.kakaopay.com/docs/moneytransfer/sendmoney.code/api-qrlink-create

API 요청이 정상적으로 성공했을 때 반환되는 응답 예시입니다. 생성된 코드송금 링크와 생성 일시 정보를 포함합니다.

```json
HTTP/1.1 200 OK
Content-type: application/json; charset=UTF-8
{
    "link_type": "TO",
    "link": "https://link.kakaopay.com/_/Ez9j94i",
    "created_at": "2024-07-03T14:17:08.77586"
}

```

--------------------------------

### Prepare Subscription Payment with Test CID

Source: https://developers.kakaopay.com/docs/payment/online/subscription

Initiates a payment preparation for a subscription using a test CID. This API call requires a SECRET_KEY for authorization and includes details about the subscription such as order ID, user ID, item name, amounts, and redirect URLs.

```curl
curl --location 'https://open-api.kakaopay.com/online/v1/payment/ready' \
--header 'Authorization: SECRET_KEY ${SECRET_KEY}' \
--header 'Content-Type: application/json' \
--data '{ \
		"cid": "TCSEQUENCE", \
		"partner_order_id": "subscription_order_id_1", \
		"partner_user_id": "subscription_user_id_1", \
		"item_name": "음악정기결제", \
		"quantity": "1", \
		"total_amount": "9900", \
		"vat_amount": "900", \
		"tax_free_amount": "0", \
		"approval_url": "https://developers.kakao.com/success", \
		"fail_url": "https://developers.kakao.com/fail", \
		"cancel_url": "https://developers.kakao.com/cancel" \
	}'
```

--------------------------------

### 코드송금 링크 발급 API 실패 응답 (가입 미비)

Source: https://developers.kakaopay.com/docs/moneytransfer/sendmoney.code/api-qrlink-create

사용자가 카카오페이 머니 서비스에 가입되어 있지 않아 코드송금 링크 발급에 실패했을 때 반환되는 오류 응답 예시입니다.

```json
HTTP/1.1 409 Conflict
Content-type: application/json; charset=UTF-8
{
  "error_code": -409,
  "error_message": "송금링크 발급 불가합니다"
}

```

--------------------------------

### 코드송금 링크 발급 API 실패 응답 (이미 발급됨)

Source: https://developers.kakaopay.com/docs/moneytransfer/sendmoney.code/api-qrlink-create

이미 코드송금 링크가 발급되어 재발급이 불가능할 때 반환되는 오류 응답 예시입니다. 오류 코드와 메시지를 포함합니다.

```json
HTTP/1.1 409 Conflict
Content-type: application/json; charset=UTF-8
{
    "error_code": -409,
    "error_message": "최대 1개 까지만 발급 가능합니다."
}

```

--------------------------------

### Payment Process: Payment Method Selection and Authentication

Source: https://developers.kakaopay.com/docs/payment/online/common

Describes the user's experience in selecting a payment method and completing authentication within KakaoPay, including how mock testing handles authentication.

```APIDOC
## Payment Process: 3. Payment Method Selection and Authentication

### Description
This final step in the payment process involves the user selecting their preferred payment method and completing the necessary authentication within the KakaoPay interface.

### User Interaction:
- Users select their desired payment method within KakaoPay.
- Users complete the authentication process (e.g., password, biometric authentication).

### Mock Testing:
- In the mockup (test) environment, the authentication step is skipped to streamline the testing process.
```

--------------------------------

### FAQ

Source: https://developers.kakaopay.com/docs/payment/online/change

카카오페이 온라인 결제 API 전환과 관련된 자주 묻는 질문과 답변을 제공합니다.

```APIDOC
## FAQ

### 신규 API로 전환하지 않으면 온라인 결제 서비스 이용이 불가한가요?
신규 API로 전환을 권장드리지만, 가맹점 결제 서비스에 영향이 없도록 (구)온라인 결제 API는 당분간 동일하게 운영될 예정입니다.

### (구)온라인 결제 API의 서비스 종료 일자가 있나요?
현재 정해진 서비스 종료 일정은 없습니다.

### 카카오페이 온라인 결제 모든 서비스가 전환 대상인가요?
카카오페이 온라인 단건결제, 정기결제, 주문조회, 결제취소 서비스만 전환 대상입니다. 카카오를 통한 원클릭결제, 연속결제는 이번 전환 대상이 아니며, 연속결제의 경우 추후 전환 진행 시 별도 공지될 예정입니다.

### 기존 CID를 그대로 사용할 수 있나요?
네. 기존 CID 그대로 신규 API로 승인/조회/취소가 가능하며, 파트너어드민, 파일서비스 또한 변경 없이 사용하실 수 있습니다.

### 기존 API와 신규 API 모두 사용 가능한가요?
네. 모두 사용 가능합니다. 다만 관리를 위해 전환 완료된 경우 (구)온라인 결제 API에 대해 종료하는 것을 원칙으로 합니다.
```

--------------------------------

### 코드송금 링크 발급 API 요청

Source: https://developers.kakaopay.com/docs/moneytransfer/sendmoney.code/api-qrlink-create

코드송금 링크를 발급하는 API의 요청 구문입니다. 액세스 토큰을 포함한 헤더와 JSON 형식의 요청 본문을 사용합니다.

```http
POST /connect/api/v1/money-transaction/link HTTP/1.1
Host: open-api.kakaopay.com
Authorization: Bearer {ACCESS TOKEN}
Content-type: application/json;charset=UTF-8


```

--------------------------------

### Subscription Payment API

Source: https://developers.kakaopay.com/docs/payment/online/subscription

This section details the process of initiating and managing subscription payments using KakaoPay.

```APIDOC
## POST /subscription/start

### Description
Initiates the first payment for a subscription. This is a single payment request that also serves to obtain a Subscription ID (SID) for future recurring payments.

### Method
POST

### Endpoint
/subscription/start

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cid** (String) - Required - The merchant's subscription-specific CID.
- **partner_order_id** (String) - Required - Merchant's unique order ID.
- **partner_user_id** (String) - Required - Merchant's unique user ID.
- **item_name** (String) - Required - Name of the item.
- **total_amount** (Integer) - Required - Total amount for the first payment. Use 0 if only issuing the SID.
- **payment_method_type** (String) - Required - Payment method (e.g., 'CARD').

### Request Example
```json
{
  "cid": "YOUR_SUBSCRIPTION_CID",
  "partner_order_id": "partner_12345",
  "partner_user_id": "partner_user_123",
  "item_name": "Monthly Subscription",
  "total_amount": 10000,
  "payment_method_type": "CARD"
}
```

### Response
#### Success Response (200)
- **sid** (String) - The Subscription ID (SID) required for subsequent recurring payments.
- **tid** (String) - The transaction ID for this initial payment.
- **aid** (String) - The approval ID for this initial payment.
- **cid** (String) - The merchant's CID.
- **partner_order_id** (String) - Merchant's order ID.
- **partner_user_id** (String) - Merchant's user ID.
- **payment_method_type** (String) - Type of payment method used.
- **amount** (Object) - Details of the payment amount.
- **card_info** (Object) - Details about the card payment, if applicable.
- **created_at** (Datetime) - Timestamp when the payment request was made.
- **approved_at** (Datetime) - Timestamp when the payment was approved.

#### Response Example
```json
{
  "aid": "A202301011234567890",
  "tid": "T202301011234567890",
  "cid": "YOUR_SUBSCRIPTION_CID",
  "sid": "YOUR_SUBSCRIPTION_SID",
  "partner_order_id": "partner_12345",
  "partner_user_id": "partner_user_123",
  "payment_method_type": "CARD",
  "amount": {
    "total": 10000,
    "tax_free": 0,
    "vat": 909,
    "point": 0,
    "discount": 0,
    "green_deposit": 0
  },
  "card_info": {
    "kakaopay_purchase_corp": "Visa",
    "kakaopay_purchase_corp_code": "400000",
    "kakaopay_issuer_corp": "KB Kookmin Card",
    "kakaopay_issuer_corp_code": "371",
    "bin": "477681",
    "card_type": "CREDIT",
    "install_month": "00",
    "approved_id": "12345678",
    "card_mid": "YOUR_CARD_MID",
    "interest_free_install": "N",
    "card_item_code": ""
  },
  "item_name": "Monthly Subscription",
  "item_code": "ITEM001",
  "quantity": 1,
  "created_at": "2023-01-01T10:00:00+09:00",
  "approved_at": "2023-01-01T10:05:00+09:00",
  "payload": ""
}
```

## POST /subscription/recurring

### Description
Processes a recurring payment for a subscription using the previously obtained Subscription ID (SID).

### Method
POST

### Endpoint
/subscription/recurring

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cid** (String) - Required - The merchant's subscription-specific CID.
- **sid** (String) - Required - The Subscription ID obtained from the initial payment.
- **partner_order_id** (String) - Required - Merchant's unique order ID for this recurring payment.
- **partner_user_id** (String) - Required - Merchant's unique user ID.
- **item_name** (String) - Required - Name of the item for this recurring payment.
- **total_amount** (Integer) - Required - The amount for this recurring payment.

### Request Example
```json
{
  "cid": "YOUR_SUBSCRIPTION_CID",
  "sid": "YOUR_SUBSCRIPTION_SID",
  "partner_order_id": "partner_12345_recurring",
  "partner_user_id": "partner_user_123",
  "item_name": "Monthly Subscription Renewal",
  "total_amount": 10000
}
```

### Response
#### Success Response (200)
- **aid** (String) - The approval ID for this recurring payment.
- **tid** (String) - The transaction ID for this recurring payment.
- **cid** (String) - The merchant's CID.
- **sid** (String) - The Subscription ID.
- **partner_order_id** (String) - Merchant's order ID.
- **partner_user_id** (String) - Merchant's user ID.
- **payment_method_type** (String) - Type of payment method used.
- **amount** (Object) - Details of the payment amount.
- **card_info** (Object) - Details about the card payment, if applicable.
- **created_at** (Datetime) - Timestamp when the payment request was made.
- **approved_at** (Datetime) - Timestamp when the payment was approved.
- **sequential_payment_methods** (Object) - Information about sequential payment methods, if applicable.

#### Response Example
```json
{
  "aid": "A202301021234567890",
  "tid": "T202301021234567890",
  "cid": "YOUR_SUBSCRIPTION_CID",
  "sid": "YOUR_SUBSCRIPTION_SID",
  "partner_order_id": "partner_12345_recurring",
  "partner_user_id": "partner_user_123",
  "payment_method_type": "CARD",
  "amount": {
    "total": 10000,
    "tax_free": 0,
    "vat": 909,
    "point": 0,
    "discount": 0,
    "green_deposit": 0
  },
  "card_info": {
    "kakaopay_purchase_corp": "Visa",
    "kakaopay_purchase_corp_code": "400000",
    "kakaopay_issuer_corp": "KB Kookmin Card",
    "kakaopay_issuer_corp_code": "371",
    "bin": "477681",
    "card_type": "CREDIT",
    "install_month": "00",
    "approved_id": "12345678",
    "card_mid": "YOUR_CARD_MID",
    "interest_free_install": "N",
    "card_item_code": ""
  },
  "item_name": "Monthly Subscription Renewal",
  "item_code": "ITEM001",
  "quantity": 1,
  "created_at": "2023-01-02T10:00:00+09:00",
  "approved_at": "2023-01-02T10:05:00+09:00",
  "sequential_payment_methods": null
}
```

## GET /subscription/status

### Description
Retrieves the status of a subscription payment using the Subscription ID (SID).

### Method
GET

### Endpoint
/subscription/status

### Parameters
#### Path Parameters
None

#### Query Parameters
- **cid** (String) - Required - The merchant's subscription-specific CID.
- **sid** (String) - Required - The Subscription ID.

### Request Example
```
GET /subscription/status?cid=YOUR_SUBSCRIPTION_CID&sid=YOUR_SUBSCRIPTION_SID
```

### Response
#### Success Response (200)
- **status** (String) - The current status of the subscription (e.g., ACTIVE, INACTIVE, CANCELED).
- **last_payment_date** (Datetime) - The date of the last successful payment.
- **next_payment_date** (Datetime) - The scheduled date for the next payment.

#### Response Example
```json
{
  "status": "ACTIVE",
  "last_payment_date": "2023-01-02T10:05:00+09:00",
  "next_payment_date": "2023-02-02T10:00:00+09:00"
}
```
```

--------------------------------

### 카카오페이 온라인 결제 API 구현 예제 (Java)

Source: https://developers.kakaopay.com/docs/payment/online/reference

카카오페이 온라인 결제 API 구현을 위한 Java 예제 코드입니다. 현재 개발 중이며, 추후 SDK 제공 예정입니다. 개발 참고용으로만 사용해야 합니다.

```java
/*
 * 카카오페이 온라인 결제 API 구현 예제 (Java)
 * 이 코드는 개발 시 참고용으로만 사용 부탁드립니다.
 * 추후 SDK 제공 예정
 */

// 실제 구현 코드는 여기에 포함되지 않았습니다.
// 예시: 결제 요청, 결과 확인 등의 메소드 호출
System.out.println("카카오페이 온라인 결제 API 구현 예제 (Java)");
```

--------------------------------

### 포럼 운영 정책

Source: https://developers.kakaopay.com/docs/payment/online/change

온라인 결제 API 관련 Q&A가 제공되는 포럼 운영 정책을 설명합니다.

```APIDOC
## 포럼 운영 정책

### 설명
모든 온라인 결제 API에 대한 질문과 답변은 카카오페이 개발자센터의 포럼을 통해 제공되며, 카테고리별로 구분됩니다.

### 문의 경로

| API 구분 | 사용 서비스 | 제공 기능 | 사용 경로 |
|---|---|---|---|
| 온라인 결제 API | 카카오페이 포럼 | 등록/조회 | 카카오페이 개발자센터 > 포럼 > 온라인 결제 API |
| (구)온라인 결제 API | 카카오페이 포럼 | 등록/조회 | 카카오페이 개발자센터 > 포럼 > 구)온라인 결제 API |
| (구)온라인 결제 API(24.2.1 이전) | 카카오 포럼 | 조회만 가능 | 카카오 개발자센터 > 포럼 > 카카오페이API |

**참고:** 2024년 2월 1일 이전의 문의 내용은 카카오 개발자센터에서 확인할 수 있습니다.
```