Alipay+ Payment Integration Skill

🤖 An AgentSkill that helps Acquirers and Mobile Payment Service Providers quickly integrate Alipay+ payments.

📖 Overview

This skill provides comprehensive Alipay+ payment integration support, including:

• Configuration Generation - Automatically generate configuration file templates
• Signature Verification - Test signature generation and verification
• Webhook Debugging (for ACQP only) - Asynchronous notification configuration and troubleshooting
• Reconciliation Processing - Download and parse reconciliation files

Supports two roles:

• ACQP (Acquirer Service Provider) - Payment service providers integrating with merchants
• MPP (Mobile Payment Service Provider) - E-wallet providers integrating with Alipay+

🚀 Quick Start

Installation

# Install via ClawHub
openclaw skills install alipayplus-integration

# Or manually clone to skills directory
git clone <repo-url> ~/.openclaw/skills/alipayplus-integration

Usage

Trigger directly in conversation:

"How to integrate with Alipay+?"
"Help me generate Alipay+ configuration file"
"Signature verification failed, help me check"
"How to download reconciliation files?"

⚠️ Role Clarification

Please confirm your role before use:

| Role | Description | Typical Scenarios | |------|------|----------| | ACQP | Acquirer Service Provider | Integrating payment collection for merchants | | MPP | Mobile Payment Service Provider | Wallet apps integrating Alipay+ payments |

📦 Features

1. Configuration Generation

Automatically generate alipayplus-config.json configuration file:

bash "$(dirname "$SKILL_DIR")/scripts/generate-config.sh"

Supported Configuration:

• Environment (sandbox/production)
• Role (ACQP/MPP)
• Keys and certificates
• Webhook URL (for ACQP only)
• Business parameters (currency, timeout, etc.)

2. Signature Verification

Test signature generation and verification:

bash "$(dirname "$SKILL_DIR")/scripts/test-signature.sh"

Features:

• Generate test signatures
• Verify Webhook signatures (for ACQP only)
• Common signature issue troubleshooting

3. Webhook Debugging (for ACQP only)

Assist with asynchronous notification setup:

• Webhook endpoint requirements
• Signature verification implementation
• Retry logic and idempotency handling

4. Reconciliation File Processing

Download and parse daily reconciliation files:

bash "$(dirname "$SKILL_DIR")/scripts/download-reconciliation.sh"

Supported File Types:

• settlement_*.csv - Settlement files
• transactionItems_*.csv - Transaction details
• summary_*.csv - Summary files
• feeItems_*.csv - Fee details

📁 File Structure

alipayplus-integration/
├── README.md                      # This file
├── SKILL.md                       # Skill definition (AgentSkill spec)
├── references/                    # Reference documentation
│   ├── api-reference.md           # API parameter reference
│   ├── flows.md                   # Payment flow diagrams
│   ├── signature-guide.md         # Signature guide
│   ├── webhook-guide.md           # Webhook configuration (for ACQP only)
│   ├── reconciliation-guide.md    # Reconciliation guide
│   └── config-template.json       # Configuration template
└── scripts/                       # Utility scripts
    ├── generate-config.sh         # Configuration generation
    ├── test-signature.sh          # Signature testing
    └── download-reconciliation.sh # Reconciliation download

🔧 Prerequisites

1. Generate Keys

# Generate RSA2048 key pair
openssl genrsa -out alipayplus_private_key.pem 2048
openssl rsa -in alipayplus_private_key.pem -pubout -out alipayplus_public_key.pem

2. Obtain Certificates

From Alipay+ Developer Center:

• ACQP certificate
• Alipay+ public key

3. Configure Webhook (for ACQP only)

Ensure you have:

• Publicly accessible HTTPS endpoint
• Valid SSL certificate
• POST request support

📖 Usage Examples

Example 1: ACQP CPM Payment (Customer-Presented Mode)

User: I'm an acquirer, want to integrate customer-presented payment code scenario
Assistant: Great, this is ACQP CPM (Customer-presented Mode) integration...
  1. Call /aps/api/v1/payments/pay endpoint
  2. Pass user's paymentCode
  3. Handle asynchronous webhook notification
  4. Download reconciliation files for verification

Example 2: MPP Get Payment Code

User: We're a wallet app, how to get payment code to display to users?
Assistant: This is MPP scenario, need to call getPaymentCode endpoint...
  1. Call /aps/api/v1/codes/getPaymentCode
  2. Display returned paymentCode to user
  3. Process payment request
  4. Call `/aps/api/v1/payments/notifyPayment` to notify Alipay+ of final result
  5. Alipay+ may poll your inquiryPayment API if notification not received

Example 3: Signature Verification Failed

User: Webhook signature verification keeps failing
Assistant: Let me help you troubleshoot...
  1. Check if public key is correct
  2. Verify signature format (Base64Url)
  3. Confirm content-to-sign string concatenation order
  4. Run test-signature.sh for testing

🔗 Reference Documentation

| Document | Description | |------|------| | API Reference | Complete API parameter reference | | Integration Flows | Payment flow diagrams | | Signature Guide | Signature algorithm details | | Webhook Guide | Webhook configuration guide(for ACQP only) | | Reconciliation Guide | Reconciliation file processing |

Official Documentation

• ACQP API Overview Documentation
• MPP API Overview Documentation

❓ FAQ

Q: What's the difference between sandbox and production environments?

A: Sandbox uses different baseURL and test keys, no real transactions. Recommend testing in sandbox first before switching to production.

Q: Not receiving Webhook notifications?

A: Check the following:

1. Is Webhook URL publicly accessible
2. Did you return SUCCESS response
3. Is response time < 5 seconds
4. Check retry records in Alipay+ Developer Center

Q: Common causes of signature verification failure?

A:

• Public/private key mismatch
• Content-to-sign string concatenation error
• Encoding issues (ensure UTF-8)
• Signature format error (should be Base64Url)

Q: When can reconciliation files be downloaded?

A: Usually available after 10:00 AM on T+1 day for the previous day's transactions.

Last updated: 2026-04-06