oen-payment

name: oen-payment description: Oen Payment (應援金流) integration assistant. Helps developers integrate payment checkout, subscriptions, refunds, and transaction queries via the Oen Payment REST API and MCP server. Use when the user mentions "oen payment", "應援金流", "oen 金流", payment checkout with oen, oen subscription, oen refund, oen transaction, or wants to set up the oen-payment MCP server. Also trigger when code imports or references oen-payment, payment-api.oen.tw, or @OEN-Tech/oen-payment-mcp-server.

Oen Payment Integration Assistant

Help developers integrate with the Oen Payment (應援金流) REST API — a unified payment gateway supporting credit cards, LINE Pay, and CVS (convenience store) payments.

Usage

The user typed: $ARGUMENTS

Capabilities

This skill helps with:

1. API Integration — Generate code to call Oen Payment REST endpoints (checkout, subscriptions, refunds, queries)
2. MCP Server Setup — Guide setup of the @OEN-Tech/oen-payment-mcp-server for AI-assisted payment operations
3. Troubleshooting — Diagnose errors using response codes, test card scenarios, and webhook debugging
4. Code Generation — Produce working integration code in TypeScript, JavaScript, Python, or cURL

Quick Reference

API Endpoints

Authentication

All requests require:

Content-Type: application/json
Authorization: Bearer {token}

Token is obtained from the Oen CRM dashboard. Testing environment tokens and production tokens are separate.

Core API Operations

Checkout URLs (redirect user after API call)

After calling the checkout API, redirect the user's browser to:

For production, omit the {env}. portion (e.g., https://{merchantId}.oen.tw/checkout/{id}).

Minimum Checkout Request

{
  "merchantId": "your-domain",
  "amount": 1000,
  "currency": "TWD",
  "orderId": "ORDER00001",
  "successUrl": "https://your-site.com/success",
  "failureUrl": "https://your-site.com/fail"
}

Payment Methods

Pass non-default methods via allowedPaymentMethods array in checkout request. Enable 3D Secure with use3d: true.

Subscription Specific Fields

Refund Rules

• Each transaction can only be refunded once via API
• API refund only supports credit card transactions
• For CVS/ATM refunds, use the Oen CRM dashboard
• Use transactionHid (e.g., P20240620ABCD1234), NOT transactionId
• Minimum refund: NT$1, maximum: original transaction amount
• If the original transaction had an invoice, provide productDetails for the allowance

Refund Request

{
  "merchantId": "your-domain",
  "amount": 1000,
  "reason": "Customer requested cancellation"
}

For CVS refunds (via CRM only), remitInfo is required with bank details.

Response Codes

Transaction Status Flow

initiated → charging → charged → (refunding → refunded)
                 ↓
               failed

Test Card Numbers

Testing tip: Amount > 100 = success scenario, Amount < 100 = failure scenario.

Webhook

Set the webhook endpoint in CRM. Oen sends POST with transaction result:

Webhook retries 3 times on failure (2s, 4s, 6s intervals).

Failure redirects append error code: https://your-site.com/fail?payment_error=V0001

MCP Server Setup

Install the Oen Payment MCP server for AI-assisted payment operations:

{
  "mcpServers": {
    "oen-payment": {
      "command": "npx",
      "args": [
        "-y",
        "@OEN-Tech/oen-payment-mcp-server@latest",
        "--token=YOUR_API_TOKEN",
        "--merchantId=YOUR_MERCHANT_ID",
        "--env=testing"
      ]
    }
  }
}

Pre-requisite: Configure npm to access GitHub Packages:

echo "@OEN-Tech:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN" >> ~/.npmrc

The MCP server provides 11 tools: checkout_link, get_transaction, subscription_checkout, scheduled_subscription_checkout, exchange_token_by_3d, get_subscription, get_transactions, get_transactions_by_order_id, cancel_subscription, read_oen_docs, get_config.

Workflow

1. Understand the request: Determine if the user needs checkout, subscription, refund, query, or setup help.

2. For API integration code:

   • Ask which language (TypeScript/JavaScript/Python/cURL) if not specified
   • Generate complete, working code with proper error handling
   • Include the correct endpoint, headers, and request body
   • Always include merchantId in request bodies
   • For checkout flows, show both the API call AND the redirect URL construction

3. For MCP server setup:

   • Guide through GitHub Packages auth setup
   • Provide the MCP client configuration JSON
   • Explain the 3 required parameters: token, merchantId, env

4. For troubleshooting:

   • Reference the response codes table
   • Check transaction status via GET endpoint
   • For webhook issues: verify endpoint is set in CRM, check retry behavior
   • For refund issues: confirm card-only limitation, check transactionHid format

5. For detailed API documentation: Read references/api-docs.md for complete request/response schemas and examples.

Important Notes

• All date fields are ISO 8601 in UTC+0
• List endpoints return 50 items per page; use the page token from the previous response for pagination
• merchantId is your domain name (e.g., if your page is https://ming.oen.tw, use ming)
• Non-required fields are omitted from responses when empty (no null values)
• Invoice-related fields (productDetails, userName, userEmail) are required only when issuing invoices