Headless Checkout API Documentation

# 1. Download plugin from your dashboard
# 2. Upload to WordPress via Plugins > Add New > Upload
# 3. Configure in WooCommerce > Korea Checkout

// Required Configuration
API URL: https://api.koreacheckout.com
API Key: sk_live_your_key_here  
Order Status Mapping: Automatic

// Filter checkout fields
add_filter('korea_checkout_fields', function($fields) {
    // Add custom fields or modify existing ones
    $fields['custom_field'] = array(
        'type' => 'text',
        'label' => 'Custom Field',
        'required' => false
    );
    return $fields;
});

// Hook into payment completion  
add_action('korea_checkout_payment_complete', function($order_id, $payment_data) {
    // Custom logic after successful payment
    $order = wc_get_order($order_id);
    
    // Send custom emails, update inventory, etc.
    do_action('custom_order_processing', $order, $payment_data);
}, 10, 2);

// Customize checkout appearance
add_filter('korea_checkout_css_vars', function($vars) {
    $vars['--primary-color'] = '#your-brand-color';
    $vars['--button-radius'] = '8px';
    return $vars;
});

curl -X GET https://api.koreacheckout.com/api/checkout/session/cs_123 \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json"

POST /api/checkout/create-session

curl -X POST https://api.koreacheckout.com/api/checkout/create-session \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "custom",
    "platformOrderId": "order_123",
    "items": [
      {
        "name": "Sample Product",
        "price": 29000,
        "quantity": 1,
        "description": "Product description"
      }
    ],
    "customer": {
      "name": "홍길동",
      "email": "customer@example.com",
      "phone": "+82-10-1234-5678"
    },
    "totalAmount": 29000,
    "currency": "KRW",
    "returnUrl": "https://yourstore.com/success",
    "cancelUrl": "https://yourstore.com/cancel",
    "metadata": {
      "internal_order_id": "12345"
    }
  }'

GET /api/checkout/session/{{sessionId}}

curl -X GET https://api.koreacheckout.com/api/checkout/session/cs_1234567890abcdef \
  -H "x-api-key: sk_live_your_key_here"
  
// Response
{{
  "success": true,
  "data": {{
    "sessionId": "cs_1234567890abcdef",
    "status": "completed", 
    "platformOrderId": "order_123",
    "totalAmount": 29000,
    "currency": "KRW",
    "customer": {{
      "name": "홍길동",
      "email": "customer@example.com"
    }},
    "createdAt": "2024-01-01T10:00:00Z",
    "expiresAt": "2024-01-02T10:00:00Z",
    "completedAt": "2024-01-01T10:30:00Z"
  }}
}}

PATCH /api/checkout/session/{{sessionId}}

{{
  "customer": {{
    "name": "김철수",
    "email": "updated@example.com"
  }},
  "metadata": {{
    "updated_reason": "customer_info_change"
  }}
}}

// Check if payment completed via session status
GET /api/checkout/session/{{sessionId}}

// Response when payment completed
{{
  "success": true,
  "data": {{
    "sessionId": "cs_1234567890abcdef",
    "status": "completed",
    "totalAmount": 29000,
    "currency": "KRW",
    "paymentMethod": "card",
    "gateway": "toss",
    "gatewayTransactionId": "toss_tx_123456",
    "completedAt": "2024-01-01T10:05:00Z"
  }}
}}

POST /api/checkout/session/{{sessionId}}/refund

{{
  "amount": 10000,  // Partial refund (optional, defaults to full)
  "reason": "고객 요청 환불",
  "notify_customer": true
}}

// Response
{{
  "refundId": "ref_1234567890abcdef",
  "status": "processing",
  "amount": 10000,
  "reason": "고객 요청 환불",
  "processedAt": "2024-01-01T11:00:00Z"
}}

// Monitor payment status after creating session
const monitorPayment = async (sessionId) => {{
  try {{
    const response = await fetch(`/api/checkout/session/${sessionId}`, {{
      headers: {{
        'x-api-key': process.env.API_KEY
      }}
    }});
    
    const session = await response.json();
    
    if (!response.ok) {{
      throw new Error(session.error.message);
    }}
    
    // Handle different payment statuses
    switch (session.status) {{
      case 'completed':
        handlePaymentSuccess(session);
        break;
      case 'failed':
        handlePaymentFailure(session);
        break;
      case 'cancelled':
        handlePaymentCancellation(session);
        break;
      case 'expired':
        handleSessionExpiry(session);
        break;
      case 'processing':
        // Continue polling
        setTimeout(() => monitorPayment(sessionId), 2000);
        break;
    }}
    
    return session;
  }} catch (error) {{
    console.error('Payment monitoring error:', error);
    throw error;
  }}
}};

// Webhook handler for real-time updates
app.post('/webhooks/payment', (req, res) => {{
  const event = req.body;
  
  switch (event.event) {{
    case 'payment.completed':
      handlePaymentSuccess(event.data);
      break;
    case 'payment.failed':
      handlePaymentFailure(event.data);
      break;
  }}
  
  res.status(200).send('OK');
}});

POST /api/shops

{{
  "name": "My Korean Store",
  "description": "Premium Korean products",
  "website": "https://mystore.com",
  "business_info": {{
    "business_number": "123-45-67890",
    "business_name": "My Store Co., Ltd.",
    "ceo_name": "김철수",
    "address": "Seoul, Gangnam-gu, Teheran-ro 123"
  }},
  "contact": {{
    "email": "contact@mystore.com",
    "phone": "+82-2-1234-5678"
  }},
  "settings": {{
    "currency": "KRW",
    "timezone": "Asia/Seoul",
    "language": "ko"
  }}
}}

GET /api/shops/{{shopId}}

// Response
{{
  "id": "shop_1234567890abcdef",
  "name": "My Korean Store",
  "status": "active",
  "business_info": {{
    "business_number": "123-45-67890",
    "verified": true
  }},
  "payment_methods": [
    "card",
    "virtual_account",
    "kakao_pay",
    "naver_pay"
  ],
  "created_at": "2024-01-01T00:00:00Z"
}}

PATCH /api/shops/{{shopId}}

{{
  "settings": {{
    "webhook_url": "https://mystore.com/webhooks",
    "notification_email": "admin@mystore.com",
    "auto_refund_enabled": true,
    "payment_timeout": 1800
  }}
}}

<!-- Include Daum Postcode API -->
<script src="//t1.daumcdn.net/mapjsapi/bundle/postcode/prod/postcode.v2.js"></script>

// JavaScript integration
function openAddressSearch() {
  new daum.Postcode({
    oncomplete: function(data) {
      // data.address - 주소
      // data.zonecode - 우편번호
      // data.roadAddress - 도로명주소
      // data.jibunAddress - 지번주소
      
      document.getElementById('address').value = data.address;
      document.getElementById('postalCode').value = data.zonecode;
      
      // Send to your backend if needed
      updateCheckoutAddress({
        address: data.address,
        postalCode: data.zonecode,
        roadAddress: data.roadAddress
      });
    }
  }).open();
}

// Update checkout session with address
const updateCheckoutAddress = async (addressData) => {
  await fetch(`/api/checkout/session/${sessionId}/address`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(addressData)
  });
};

import React, { useEffect } from 'react';

const KoreanAddressInput = ({ onAddressSelect }) => {
  useEffect(() => {
    // Load Daum Postcode script
    const script = document.createElement('script');
    script.src = '//t1.daumcdn.net/mapjsapi/bundle/postcode/prod/postcode.v2.js';
    document.head.appendChild(script);
  }, []);

  const handleAddressSearch = () => {
    new window.daum.Postcode({
      oncomplete: function(data) {
        onAddressSelect({
          address: data.address,
          postalCode: data.zonecode,
          roadAddress: data.roadAddress
        });
      }
    }).open();
  };

  return (
    <div>
      <input 
        type="text" 
        placeholder="주소를 검색하세요"
        readOnly
        onClick={handleAddressSearch}
      />
      <button onClick={handleAddressSearch}>
        주소 검색
      </button>
    </div>
  );
};

POST /api/coupons/create

curl -X POST https://api.koreacheckout.com/api/coupons/create \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME10",
    "name_ko": "신규 고객 할인",
    "name_en": "New Customer Discount",
    "type": "percentage",
    "discount_value": 10,
    "valid_from": "2024-01-01T00:00:00Z",
    "valid_until": "2024-12-31T23:59:59Z",
    "usage_limit": 1000,
    "usage_limit_per_customer": 1,
    "minimum_order_amount": 50000,
    "applies_to": "cart_total"
  }'

POST /api/coupons/apply

{
  "sessionId": "cs_1234567890abcdef",
  "couponCode": "WELCOME10"
}

// Response
{
  "success": true,
  "discount": {
    "type": "percentage",
    "value": 10,
    "amount": 2900
  },
  "newTotal": 26100
}

// Create a welcome coupon for new customers
const welcomeCoupon = await fetch('https://api.koreacheckout.com/api/coupons/create', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.KOREA_CHECKOUT_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    code: 'WELCOME15',
    name_ko: '신규 가입 할인',
    type: 'percentage',
    discount_value: 15,
    valid_from: new Date().toISOString(),
    valid_until: new Date(Date.now() + 30*24*60*60*1000).toISOString(), // 30 days
    usage_limit_per_customer: 1,
    minimum_order_amount: 30000
  })
});

// Apply coupon during checkout
const applyCoupon = async (sessionId, couponCode) => {
  const response = await fetch('https://api.koreacheckout.com/api/coupons/apply', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      sessionId,
      couponCode
    })
  });
  
  return response.json();
};

{
  "event": "payment.completed",
  "data": {
    "sessionId": "cs_1234567890abcdef",
    "platformOrderId": "order_123",
    "totalAmount": 29000,
    "currency": "KRW",
    "paymentMethod": "card",
    "customer": {
      "name": "홍길동",
      "email": "customer@example.com"
    },
    "completedAt": "2024-01-01T12:00:00Z"
  }
}

app.post('/webhooks/checkout', express.raw({type: 'application/json'}), (req, res) => {
  const payload = req.body;
  const signature = req.headers['x-korea-checkout-signature'];
  
  // Verify webhook signature (recommended)
  if (!verifySignature(payload, signature)) {
    return res.status(400).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  switch (event.event) {
    case 'payment.completed':
      handlePaymentCompleted(event.data);
      break;
    case 'payment.failed':
      handlePaymentFailed(event.data);
      break;
    default:
      console.log('Unknown event type:', event.event);
  }
  
  res.status(200).send('OK');
});

{
  "error": {
    "code": "invalid_session",
    "message": "The specified session ID is invalid or has expired",
    "details": {
      "sessionId": "cs_invalid123",
      "field": "sessionId"
    }
  }
}