Alipay SDK

A flexible and lightweight SDK for building Alipay integrations with dynamic endpoints, caching, and response transformations.

Introduction

Alipay SDK for Node.js provides the ability to call Alipay Open Platform APIs from a Node.js server. It includes making OpenAPI requests to Alipay servers, generating order information, and supporting certificate, signing, and verification capabilities.

Based on the Alipay API v3 specification.

Requirements

• Node.js >= 18.0.0

Features

• Pre-configured API endpoints for Alipay's platform
• Support for Redis and in-memory caching
• Easy extensibility

Table of Contents

• Alipay SDK
  • Introduction
  • Requirements
  • Features
  • Table of Contents
  • Installation
  • Quick Start
    • 1. Import and Initialize the SDK
    • 2. Register API Endpoints
    • 3. Make API Calls
    • More
  • Usage Examples
    • Registering Endpoints
    • Making API Calls
    • Demo Examples
      • Using exec
      • Using curl
      • Using pageExecute for GET
      • Using pageExecute for POST
  • Differences from Official SDK
    • Feature Comparison
    • API Comparison
    • Configuration Comparison
  • Contributing
  • License

Installation

Install the SDK using pnpm or yarn:

pnpm add @nuecms/alipay-sdk
# or
yarn add @nuecms/alipay-sdk

Quick Start

1. Import and Initialize the SDK

import { alipaySdk } from '@nuecms/alipay-sdk';

const sdk = alipaySdk({
  appId: 'your-app-id',
  privateKey: 'your-private-key',
  alipayPublicKey: 'your-alipay-public-key',
  encryptKey: 'your-encrypt-key'
});

2. Register API Endpoints

sdk.r('getUser', '/users/{id}', 'GET');
sdk.r('createUser', '/users', 'POST');

3. Make API Calls

const user = await sdk.getUser({ id: '12345' });
console.log(user);

More

See the testing code in the tests folder.

Example:

• tests/server/alipay.ts

Usage Examples

Registering Endpoints

Register endpoints with their HTTP method, path, and dynamic placeholders (e.g., {id}):

sdk.r('getUser', '/users/{id}', 'GET');
sdk.r('deleteUser', '/users/{id}', 'DELETE');
sdk.r('createUser', '/users', 'POST');

Making API Calls

Call the registered endpoints dynamically with placeholders and additional options:

const userDetails = await sdk.getUser({ id: '12345' });

console.log(userDetails);

Demo Examples

Using exec

const response = await sdk.exec("alipay.trade.pay", {
  bizContent: {
    out_trade_no: "20150320010101001",
    total_amount: "88.88",
    subject: "Iphone6 16G",
    auth_code: "287500643347427217",
    scene: "bar_code",
  },
  needEncrypt: true
});
console.log(response);

Using curl

const response = await sdk.curl('POST', '/v3/alipay/trade/pay', {
  body: {
    "out_trade_no": "20250320221010101001",
    "total_amount": "88.88",
    "subject": "Iphone6 16G",
    // 二维码
    "auth_code": "287960314702463767",
    "scene": "bar_code"
  }
});
console.log(response);

Using pageExecute for GET

const paymentUrl = await sdk.pageExecute('alipay.trade.page.pay', 'GET', {
  bizContent: {
    out_trade_no: "202503121220010101001",
    total_amount: "88.88",
    subject: "Iphone6+16G",
    product_code: "FAST_INSTANT_TRADE_PAY",
  }
});
console.log(paymentUrl);

Using pageExecute for POST

const formHtml = await sdk.pageExecute('alipay.trade.page.pay', 'POST', {
  bizContent: {
    out_trade_no: "202503111120010101001",
    total_amount: "88.88",
    subject: "Iphone6+16G PostTest",
    product_code: "FAST_INSTANT_TRADE PAY",
  },
});
console.log(formHtml);

Differences from Official SDK

Feature Comparison

| Feature | Official SDK | This SDK | |------------------------------|--------------|----------| | Dynamic Endpoints | No | Yes | | Caching | No | Yes | | Response Transformations | No | Yes | | Server-Sent Events (SSE) | Yes | No | | Form Data Submissions | Yes | No |

API Comparison

| API Method | Official SDK | This SDK | |------------------------------|--------------|----------| | exec | Yes | Yes | | curl | Yes | Yes | | pageExecute | Yes | Yes | | checkNotifySign | Yes | Yes | | aesEncrypt | No | Yes | | aesDecrypt | No | Yes | | signature | Yes | Yes | | signatureV3 | No | Yes | | getSignStr | No | Yes |

Configuration Comparison

| Configuration Option | Official SDK | This SDK | |------------------------------|--------------|----------| | appId | Yes | Yes | | privateKey | Yes | Yes | | alipayPublicKey | Yes | Yes | | signType | Yes | Yes | | endpoint | Yes | Yes | | timeout | Yes | Yes | | camelcase | Yes | No | | keyType | Yes | Yes | | appCertPath | Yes | No | | appCertContent | Yes | No | | appCertSn | Yes | No | | alipayRootCertPath | Yes | No | | alipayRootCertContent | Yes | No | | alipayRootCertSn | Yes | No | | alipayPublicCertPath | Yes | No | | alipayPublicCertContent | Yes | No | | alipayCertSn | Yes | No | | encryptKey | No | Yes | | maxRetries | No | Yes | | cacheProvider | No | Yes | | customResponseTransformer | No | Yes | | authCheckStatus | No | Yes | | wsServiceUrl | Yes | No |

Contributing

We welcome contributions to improve this SDK! To get started:

1. Fork the repository.
2. Create a new branch (git checkout -b feature-name).
3. Commit your changes (git commit -m "Add feature X").
4. Push to the branch (git push origin feature-name).
5. Open a pull request.

License

This SDK is released under the MIT License. You’re free to use, modify, and distribute this project. See the LICENSE file for more details.