South Korea P2P Gate

Accept bank-transfer pay-ins on a hosted page and send bank-account payouts in South Korean Won (KRW).

When to use it

The South Korea P2P Gate accepts bank-transfer pay-ins on a MagicPayments-hosted page — the payer is shown the account details to transfer to — and sends bank-account payouts. Amounts are in KRW (South Korean Won), which has zero decimal places: 50000 means ₩50,000.

Pay-in — hosted bank-transfer page

1. Create the invoice Call the gate endpoint with your gate_id and the amount in KRW.
2. Redirect the payer Send the browser to invoice_url. Our page shows the payer the destination bank account and the reference to use for their transfer.
3. Receive the result We confirm the transfer and call your callback_url; the invoice moves to paid.

{
  "gate_id": "kr-bank-transfer-gate",
  "invoice": {
    "invoice_id": "order-kr-2026-000123",
    "currency": "KRW",
    "amount": 50000,
    "description": "Premium plan",
    "ttl_minutes": 30
  },
  "customer": {
    "id": "cust-55021",
    "full_name": "Kim Min-jun",
    "phone_number": "+821000000000"
  },
  "workflow_hooks": {
    "callback_url": "https://merchant.example.com/mp/callbacks",
    "return_success_url": "https://merchant.example.com/orders/123/done",
    "return_decline_url": "https://merchant.example.com/orders/123/retry"
  }
}

resp = signed_post("/api/invoice", {
    "gate_id": "kr-bank-transfer-gate",
    "invoice": {
        "invoice_id": "order-kr-2026-000123",
        "currency": "KRW",
        "amount": 50_000,            # ₩50,000 (KRW has 0 decimals)
        "description": "Premium plan",
        "ttl_minutes": 30,
    },
    "customer": {
        "id": "cust-55021",
        "full_name": "Kim Min-jun",
        "phone_number": "+821000000000",
    },
    "workflow_hooks": {
        "callback_url": "https://merchant.example.com/mp/callbacks",
        "return_success_url": "https://merchant.example.com/orders/123/done",
        "return_decline_url": "https://merchant.example.com/orders/123/retry",
    },
})
redirect_url = resp.json()["invoice_url"]

{
  "request_status": "success",
  "invoice_id": "9d1f2a7c-4b88-4c0e-9f2a-2d6e1c4b7e10",
  "merchant_invoice_id": "order-kr-2026-000123",
  "invoice_status": "unpaid",
  "invoice_url": "https://stage.example-mp.com/public/invoice/9d1f2a7c-.../gate",
  "message": "Invoice (Gate PayIn) with internal uid=9d1f2a7c-... has been created."
}

Tracking the pay-in

resp = signed_post("/api/invoice/status", {
    "merchant_invoice_id": "order-kr-2026-000123"
})
invoice = resp.json()
# invoice["status"] -> "paid" once the transfer is confirmed
# "expired" if the payer doesn't transfer before ttl_minutes elapses

Pay-out — to a bank account

Korean payouts go to a bank account. Identify the destination bank with a neutral bank_title slug (the routed provider maps it to the bank's own code), plus the account number and holder name.

{
  "cascade_id": "kr-bank-payout",
  "payment": {
    "payment_id": "payout-kr-2026-000045",
    "currency": "KRW",
    "amount": 120000,
    "description": "Seller settlement"
  },
  "bank_account": {
    "bank_title": "shinhan_bank",
    "account_number": "11012345678901",
    "full_name": "Kim Min-jun"
  },
  "customer": {
    "id": "seller-9182",
    "full_name": "Kim Min-jun"
  },
  "workflow_hooks": {
    "callback_url": "https://merchant.example.com/mp/callbacks"
  }
}

resp = signed_post("/api/payment/payout/bank_account", {
    "cascade_id": "kr-bank-payout",
    "payment": {
        "payment_id": "payout-kr-2026-000045",
        "currency": "KRW",
        "amount": 120_000,
        "description": "Seller settlement",
    },
    "bank_account": {
        "bank_title": "shinhan_bank",        # neutral bank slug from the list below
        "account_number": "11012345678901",
        "full_name": "Kim Min-jun",
    },
    "customer": {"id": "seller-9182", "full_name": "Kim Min-jun"},
    "workflow_hooks": {"callback_url": "https://merchant.example.com/mp/callbacks"},
})
payout_uid = resp.json()["payment_id"]

Supported banks

Pass one of these slugs as the recipient bank_title. The list is generated from the platform's live Korea catalogue, so it always matches what the API accepts; it also includes wallet apps (KakaoPay, Toss, NaverPay, …). If a bank you need is missing, ask your account manager.

Tracking the pay-out

resp = signed_post("/api/payment/status", {
    "merchant_payment_id": "payout-kr-2026-000045"
})
# resp.json()["status"] -> "success" | "processing" | "decline" | "error"

Testing & go-live

• On stage, drive a pay-in to paid and a payout to success using the test IDs.
• Double-check KRW amounts: 0 decimal places — the integer is the won amount as-is.
• Send a bank_title slug from the supported-banks list (not the display name, not a numeric code); validate account_number too — a wrong account is a hard decline.
• Confirm your callback handler verifies the X-MP-Signature and tolerates retries.