> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# KakaoPay via Checkout.com

> Set up KakaoPay payments through Checkout.com in Payrails, with the device context and order fields Checkout.com uses.

<picture noZoom>
  ![KakaoPay logo](https://assets.payrails.io/img/logos/kakaopay/logo-full-bleed.svg)
</picture>

<picture noZoom>
  ![Checkout.com logo](https://assets.payrails.io/img/logos/checkout/logo-full-bleed.svg)
</picture>

Accept [KakaoPay](https://docs.payrails.com/docs/integrations/payment-methods/kakaopay) payments from customers in South Korea with Checkout.com as the payment service provider (PSP). The customer selects KakaoPay, confirms the payment in KakaoPay, and returns to your site.

## Supported workflows

<table>
  <thead>
    <tr><th>Workflow</th><th>Supported</th></tr>
  </thead>

  <tbody>
    <tr><td>Payrails SDK</td><td>✔</td></tr>
    <tr><td>Payrails API</td><td>✔</td></tr>
    <tr><td>[Delayed / Manual Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✖</td></tr>
    <tr><td>[Instant Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Cancel / Void](https://docs.payrails.com/docs/orchestration/payment-acceptance/cancel-a-payment.md)</td><td>✖</td></tr>
    <tr><td>[Refund / Reverse](https://docs.payrails.com/docs/orchestration/payment-acceptance/refund-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Save Instruments](https://docs.payrails.com/docs/resources/manage-instruments.md)</td><td>✖</td></tr>
    <tr><td>[Merchant Initiated Transaction (MIT)](https://docs.payrails.com/docs/resources/payments/authorization-flags.md)</td><td>✖</td></tr>
  </tbody>
</table>

## Before you begin

Complete these steps before you send your first KakaoPay payment through Checkout.com:

1. Set up a Checkout.com integration in your workspace. Follow the [Checkout.com integration setup guide](https://docs.payrails.com/docs/integrations/payment-providers/checkout-com.md) if you don't have one yet.
2. Ask Checkout.com to enable KakaoPay on your Checkout.com account.
3. In the Payrails Portal, go to **Settings → Integrations**, open your Checkout.com integration, select **KakaoPay** under **Payment methods**, and save.
4. Add KakaoPay as a [payment option](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md) in your workflow.

## Request fields for Checkout.com

Send these fields in the authorize request, in addition to the standard [authorize fields](https://docs.payrails.com/reference/authorizeaction.md). **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to the PSP when you include them.

| Field | Status | Description |
| - | - | - |
| `meta.order.lines[].unitPrice` | Required | Needed for each line when you send `meta.order.lines`. Payrails sends each line to Checkout.com as an item with its `id`, `name`, and unit price. |
| `meta.order.lines` | Optional | The items in the order. |
| `meta.order.description` | Optional | Sent to Checkout.com as the payment description. |
| `meta.clientContext.clientType` | Optional | Set to `app` when the customer pays from your mobile app. Payrails then tells Checkout.com to open KakaoPay for an app instead of a web page. |
| `meta.clientContext.osType` | Optional | `ios` or `android`. Sent with `clientType: app` so Checkout.com opens KakaoPay for the right operating system. |
| `meta.customer.email` | Optional | Sent to Checkout.com as the customer email. |
| `meta.customer.name`, `meta.customer.lastName` | Optional | Sent to Checkout.com as the customer name. |
| `meta.customer.phone` | Optional | Sent to Checkout.com as the customer phone number. |
| `meta.order.deliveryAddress` | Optional | Sent to Checkout.com as the shipping details. |
| `meta.order.softDescriptor`, `meta.order.softDescriptorCity` | Optional | Sent together as the billing descriptor. Checkout.com uses it only when you send both. |

## Authorize a KakaoPay payment

Call [authorize a payment](https://docs.payrails.com/reference/authorizeaction.md) with `kakaoPay` as the `paymentMethodCode`. The response includes the redirect to KakaoPay.

```json Authorize request theme={null}
{
  "amount": {
    "value": "10000",
    "currency": "KRW"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "kakaoPay",
      "amount": {
        "value": "10000",
        "currency": "KRW"
      }
    }
  ],
  "meta": {
    "customer": {
      "name": "Minji",
      "lastName": "Kim",
      "email": "minji.kim@example.com"
    },
    "order": {
      "description": "Order 1234",
      "lines": [
        {
          "id": "item-1",
          "name": "Online course",
          "quantity": 1,
          "unitPrice": {
            "value": "10000",
            "currency": "KRW"
          }
        }
      ]
    },
    "clientContext": {
      "clientType": "app",
      "osType": "ios"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}
```

After the customer confirms the payment, they return to your `success` or `error` URL. Confirm the result through [webhook notifications](https://docs.payrails.com/docs/orchestration/payment-acceptance/receive-notifications.md) or the execution status before you fulfill the order.

## How Checkout.com handles KakaoPay

* Checkout.com needs no payment token for KakaoPay. Payrails creates the KakaoPay source at Checkout.com from the authorize request.
* Payrails sends KakaoPay payments for a web page by default. When `meta.clientContext.clientType` is `app`, Payrails asks Checkout.com for the app flow on the operating system in `osType`.
* Checkout.com authorizes and captures KakaoPay payments in one step. Configure your workflow for instant capture.
* KakaoPay through Checkout.com supports customer-initiated transactions (CIT): the customer confirms every payment in KakaoPay.

## Merchant regions

Merchants based in these regions can accept KakaoPay through Checkout.com:

* European Economic Area
* Hong Kong
* Singapore
* United Kingdom


## Related topics

- [KakaoPay](https://docs.payrails.com/docs/integrations/payment-methods/kakaopay.md)
- [STC Pay via Checkout.com](https://docs.payrails.com/docs/integrations/payment-methods/stc-pay/checkout-com.md)
- [QPay via Checkout.com](https://docs.payrails.com/docs/integrations/payment-methods/qpay/checkout-com.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.