# UnionPay Open Platform MCP

> UnionPay Open Platform handles global payments by integrating UnionPay's card network directly into your AI workflow. Use it to verify user identities, securely tokenize bank cards for recurring billing, and generate functional QR payment codes instantly. It manages everything from initial KYC checks to final online checkout sessions.

## Overview
- **Category:** industry-titans
- **Price:** Free
- **Tags:** qr-code, tokenization, card-verification, checkout, financial-api, global-payments

## Description

You gotta run global payments through UnionPay, right? This platform lets your AI client handle everything from verifying who a user is to processing recurring charges and generating payment codes. It's basically running a full financial pipeline straight out of your agent.

**Verifying Identity and Risk Checks**
When you need to validate a cardholder, start with the Know Your Customer (KYC) check. You use `verify_card_kyc` by feeding it the user’s Card Number, ID, and Phone Number; that runs a cross-reference against UnionPay records to confirm legitimacy. Before processing anything, you should always check if the card is flagged for trouble; run `check_card_risk_status` on any number to see if the network has flagged potential fraud or high risk.

**Handling Payments: QR Codes and Online Checkout**
For immediate payments, you’ll generate a payment QR code payload and URL using `generate_qr_code`. This creates that unique Customer-to-Business (C2B) code for quick transactions. Once the time comes to see if that code actually went through, check the final status with `get_qr_transaction_status`; this tells you if funds cleared or if the transaction failed.

If you're doing a full checkout over the internet—the kind of thing where you need to process everything securely—you use `init_secure_payment`. This starts the whole online session, gathering all necessary data so your agent can complete the card transaction safely.

**Tokenizing and Managing Card Data**
If you gotta save a customer's card details for later billing cycles or subscriptions, you don't want to store raw numbers. You run `request_card_token` on the sensitive card data; it converts those raw digits into a secure Token ID that you can use again without risk. If you ever need to pull back a saved token—maybe the customer changed their bank—you gotta invalidate it by calling `cancel_card_token`. That action unlinks or invalidates the previously saved UnionPay card token ID, making sure nobody uses it anymore.

## Tools

### cancel_card_token
Unlinks or invalidates a previously saved UnionPay card token ID, preventing future use of that token.

### check_card_risk_status
Queries the network to determine if a specific card number is flagged for potential fraud or high risk.

### generate_qr_code
Creates a new UnionPay QR Code payload and URL needed for customers to complete a payment.

### get_qr_transaction_status
Checks the final status of a specific QR code transaction, confirming if funds were received or failed.

### init_secure_payment
Starts an online payment checkout session, collecting necessary data to process a full card transaction securely.

### request_card_token
Takes raw card details and converts them into a secure Token ID suitable for saving for later billing cycles.

### verify_card_kyc
Runs a Know Your Customer (KYC) verification by cross-referencing the provided Card Number, ID, and Phone Number against UnionPay records.

## Prompt Examples

**Prompt:** 
```
Generate a payment QR code for an order of 500 CNY.
```

**Response:** 
```
I've successfully requested the C2B QR Code. Here is the QR Code payload and URL which you can display to your customer.
```

**Prompt:** 
```
Check if this UnionPay card is flagged as high-risk: 6222021XXXXXXX.
```

**Response:** 
```
I checked the UnionPay risk registry. This card has not been flagged for fraud and is operating normally.
```

**Prompt:** 
```
Cancel the recurring billing Token ID TK-82739.
```

**Response:** 
```
The card binding associated with Token 'TK-82739' has been safely unlinked. Future charges against this token will fail.
```

## Capabilities

### Validate user identity (KYC)
Verifies if a cardholder is legitimate by checking their ID, phone number, and card against the bank's records.

### Generate payment QR codes
Creates unique Customer-to-Business (C2B) QR codes for immediate payment transactions.

### Initiate secure online checkout
Starts the necessary session to process a full, verifiable card transaction over the internet.

### Securely save card details (Tokenization)
Converts sensitive raw card numbers into non-sensitive Token IDs for later use in subscriptions or billing cycles.

### Check transaction status
Queries the network to determine if a generated QR code payment actually went through and cleared successfully.

## Use Cases

### Onboarding a new subscription user
A user signs up for premium access. The agent runs `verify_card_kyc` first to validate the identity. Then, it calls `request_card_token` using the card details provided. This secures the Token ID needed later when the monthly billing cycle hits, without ever having to store the raw card number.

### Processing a physical point-of-sale payment
A store manager needs to take money from a customer in person. The agent calls `generate_qr_code` with the order total (say, 500 CNY). It returns the QR code payload, which the manager can immediately display on screen for the customer to scan.

### Handling an online checkout flow
A user is checking out on a website. The agent initiates the process by calling `init_secure_payment`. This single call handles the full session setup, making sure all necessary security checks are in place before the card details are even processed.

### Cleaning up old billing data
A customer cancels a service and needs to stop recurring charges. The agent uses `cancel_card_token` with the associated Token ID, making sure all future automatic payments fail gracefully.

## Benefits

- Full KYC Validation: Use `verify_card_kyc` to validate user identity upfront. This stops fraud attempts before they even reach the payment gateway, saving you time and money.
- Reliable Recurring Billing: Instead of storing raw data (which is a huge liability), use `request_card_token` to get a secure Token ID for billing cycles that happen months later.
- Instant Payment Generation: Need to send an invoice? Running `generate_qr_code` creates the necessary C2B QR code payload immediately, which you can drop into any chat message or email.
- Payment Status Tracking: Don't wait and wonder. Call `get_qr_transaction_status` after generating a code to confirm if the customer actually scanned it and paid.
- Risk Mitigation: Before processing anything, run `check_card_risk_status`. This simple check helps flag potentially high-risk cards, letting you decline transactions proactively.

## How It Works

The bottom line is: it lets your AI client handle the full lifecycle of global payments without needing dedicated, hard-coded SDKs in your application.

1. First, subscribe to the UnionPay Open Platform server on Vinkius.
2. Next, input your required App ID and App Secret credentials from the developer portal into the agent's environment variables.
3. Finally, you can start calling tools—like `verify_card_kyc` or `generate_qr_code`—directly within your LLM prompt to execute complex payment flows.

## Frequently Asked Questions

**How do I use UnionPay Open Platform to check card risk?**
Call `check_card_risk_status`. This tool queries the network and returns whether the provided card number is flagged for fraud or if it's operating normally. It’s a simple, proactive step you should take early in any payment flow.

**What tools does UnionPay Open Platform use for recurring payments?**
The `request_card_token` tool is what you need. It takes raw card details and converts them into a safe Token ID. You then save this Token ID and pass it back to the agent when running future charges.

**Can I generate QR codes using UnionPay Open Platform?**
Yes, use `generate_qr_code`. This tool creates a C2B (Customer-to-Business) unified QR code payload and URL. You can then immediately display this to the customer for payment.

**How do I validate user identity with UnionPay Open Platform?**
You run `verify_card_kyc`. This tool takes three pieces of information—the Card Number, ID, and Phone Number—and checks them together against the bank's system for a full KYC validation.

**What is the purpose of the `init_secure_payment` function in the UnionPay Open Platform?**
It initializes a secure checkout session for online payments. You use this tool to generate a temporary payment gateway ID or link, which you must pass before collecting card details and completing the transaction.

**After generating a code, how does UnionPay Open Platform track the success status using `get_qr_transaction_status`?**
This tool allows you to query the real-time outcome of any QR transaction. You get immediate feedback on whether the payment succeeded, failed, or if it's still pending confirmation.

**When I use UnionPay Open Platform for card tokenization via `request_card_token`, what happens to my sensitive data?**
The tool converts raw card numbers into a safe Token ID. You can store this reusable token instead of the actual card details, allowing you to bill the customer later without handling sensitive information.

**If I need to revoke payment access, how does the UnionPay Open Platform's `cancel_card_token` tool work?**
The function safely unlinks an existing card token from your system. Once you run this, any future attempt to process a charge using that specific token will fail immediately.

**How do I get an App ID?**
You must register a developer account on the UnionPay International Developer portal. Once your business is verified, you can create an app to obtain credentials.

**Does KYC card checking cost money?**
Yes, depending on your contract with UnionPay, calls to identity verification and risk assessment endpoints may incur minor micro-transaction fees per successful hit.

**Can I use RSA Certificates instead of App Secret?**
This MCP wrapper abstracts away the complex RSA `.pfx` certificate signing by requiring standard API Key interaction, which is securely transformed in the agent execution runtime.