KakaoPay for Payment Setup API

Last updated: April 30, 2026

To accept KakaoPay payments, you must:

Create a payment setup.
Confirm the payment.
Redirect the customer to KakaoPay.

Call the Create a payment setup endpoint.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "amount": 11000,
3  "currency": "KRW",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "name": "Jia Tsang"
7  },
8  "order": {
9    "items": [
10      {
11        "name": "Wireless headphones",
12        "quantity": 1,
13        "unit_price": 11000
14      }
15    ]
16  },
17  "payment_methods": {
18    "kakaopay": {
19      "terminal_type": "app",
20      "os_type": "ios"
21    }
22  },
23  "settings": {
24    "success_url": "https://example.com/payments/success",
25    "failure_url": "https://example.com/payments/failure"
26  }
27}

In the request body, provide the following:

Field Description

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Supported value: `KRW` Required
`customer` object	The customer's details. Required
`customer.name` string	The customer's name. Max length: 255 Required
`order` object	The order details. Required
`order.items` array	The list of items in the order. Minimum items: 1 Required
`order.items[].name` string	The name of the item. Required
`order.items[].quantity` number	The quantity of the item. Minimum: 1 Required
`order.items[].unit_price` number	The unit price of the item, in the minor currency unit. Minimum: 0 Required
`payment_methods.kakaopay` object	The KakaoPay payment method details. Required
`payment_methods.kakaopay.os_type` string	The operating system of the customer's device. Required if `terminal_type` is `wap` or `app`. Supported values: `android` `ios`
`payment_methods.kakaopay.terminal_type` string	Supported values: `web` `wap` `app` Required
`reference` string	A unique reference for the payment. Max length: 80 Required
`settings` object	The payment settings. Required
`settings.failure_url` string	The URL to redirect the customer to if the payment fails. Format: URI Max length: 1024 Required
`settings.success_url` string	The URL to redirect the customer to if the payment is successful. Format: URI Max length: 1024 Required
`billing` object	The customer's billing details.
`billing.address` object	The customer's billing address. Required if `billing` is provided.
`billing.address.address_line1` string	The first line of the billing address. Required if `billing` is provided.
`billing.address.city` string	The city of the billing address. Required if `billing` is provided.
`billing.address.country` string	The country of the billing address. Required if `billing` is provided.
`description` string	A description of the payment. Max length: 100
`order.items[].reference` string	A reference for the item.
`order.shipping` object	The shipping details for the order.
`order.shipping.address` object	The shipping address.
`order.shipping.address.country` string	The country of the shipping address.

amount

number

The payment amount, in the minor currency unit.
Minimum: 1
Required

currency

string

Three-letter ISO 4217 currency code.
Supported value: KRW
Required

customer

object

The customer's details.
Required

customer.name

string

The customer's name.
Max length: 255
Required

order

object

The order details.
Required

order.items

array

The list of items in the order.
Minimum items: 1
Required

order.items[].name

string

The name of the item.
Required

order.items[].quantity

number

The quantity of the item.
Minimum: 1
Required

order.items[].unit_price

number

The unit price of the item, in the minor currency unit.
Minimum: 0
Required

payment_methods.kakaopay

object

The KakaoPay payment method details.
Required

payment_methods.kakaopay.os_type

string

The operating system of the customer's device.
Required if terminal_type is wap or app.
Supported values:

android
ios

payment_methods.kakaopay.terminal_type

string

Supported values:

web
wap
app
Required

reference

string

A unique reference for the payment.
Max length: 80
Required

settings

object

The payment settings.
Required

settings.failure_url

string

The URL to redirect the customer to if the payment fails.
Format: URI
Max length: 1024
Required

settings.success_url

string

The URL to redirect the customer to if the payment is successful.
Format: URI
Max length: 1024
Required

billing

object

The customer's billing details.

billing.address

object

The customer's billing address.
Required if billing is provided.

billing.address.address_line1

string

The first line of the billing address.
Required if billing is provided.

billing.address.city

string

The city of the billing address.
Required if billing is provided.

billing.address.country

string

The country of the billing address.
Required if billing is provided.

description

string

A description of the payment.
Max length: 100

order.items[].reference

string

A reference for the item.

order.shipping

object

The shipping details for the order.

order.shipping.address

object

The shipping address.

order.shipping.address.country

string

The country of the shipping address.


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 11000,
5  "currency": "KRW",
6  "payment_type": "Regular",
7  "reference": "ORD-5023-4E89",
8  "description": "KakaoPay payment",
9  "payment_methods": {
10    "kakaopay": {
11      "status": "ready",
12      "flags": []
13    }
14  },
15  "available_payment_methods": [
16    "kakaopay"
17  ],
18  "settings": {
19    "success_url": "https://example.com/payments/success",
20    "failure_url": "https://example.com/payments/failure"
21  }
22}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

When all required fields are present, the payment_methods.kakaopay object shows a ready status.

Checkout.com processes the payment when you call the Confirm a payment setup endpoint. Provide:

The payment setup id as the {id} path parameter.
kakaopay as the payment method name.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/kakaopay

If you receive a 202 Success response with a payment id and a status field set to Pending, your request was successful.


1{
2  "id": "pay_sxzrgliy2w3e5gpnby3chlswwq",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_2g4ehcpm6phexgkzahlwxvbgne"
7  },
8  "_links": {
9    "self": {
10      "href": "https://{prefix}.api.checkout.com/payments/pay_sxzrgliy2w3e5gpnby3chlswwq"
11    },
12    "redirect": {
13      "href": "https://psp.ac.alipay.com/page/simulation-wallet/acwallet/alipayconnectcode.html?code=281666040095AHvh5AIKT0a3kv8X6Zzv3kiv&pspName=KAKAOPAY&loadMode=2"
14    }
15  }
16}

Redirect the customer to the redirect.href URL from the response. The customer completes the payment on the KakaoPay page and is then redirected back to your settings.success_url or settings.failure_url.

KakaoPay for Payment Setup API

Create a payment setup

Information

Request example

Response example

Confirm the payment

Request example

Response example

Redirect the customer