Antom Node.js SDK

Language: Node.js  
Node.js version: 16.0+  
TypeScript: Supported  
Release: 1.4.10  
Copyright: Ant financial services group  

Installation

npm install @yakies/antom-nodejs-sdk

Quick Start

1. Basic Payment Example

import {
  DefaultAntomClient,
  AntomPayRequest,
  Amount,
  Order,
  PaymentMethod,
  SettlementStrategy,
  Env,
  ProductCodeType,
  TerminalType,
  ResultStatusType
} from '@yakies/antom-nodejs-sdk';

// Configuration
const GATEWAY_HOST = 'https://open-na.alipay.com';
const CLIENT_ID = 'your_client_id';
const MERCHANT_PRIVATE_KEY = 'your_private_key';
const ALIPAY_PUBLIC_KEY = 'alipay_public_key';

async function pay() {
  const client = new DefaultAntomClient(
    GATEWAY_HOST,
    CLIENT_ID,
    MERCHANT_PRIVATE_KEY,
    ALIPAY_PUBLIC_KEY
  );

  const request = new AntomPayRequest();

  // Set basic payment parameters
  request.setProductCode(ProductCodeType.CASHIER_PAYMENT);
  request.setPaymentRequestId('pay_test_' + Date.now());
  request.setPaymentRedirectUrl('https://www.yourRedirectUrl.com');
  request.setPaymentNotifyUrl('https://www.yourNotifyUrl.com');

  // Set payment method
  const paymentMethod = {
    paymentMethodType: 'ALIPAY_CN',
    paymentMethodId: 'payment_method_id'
  };
  request.setPaymentMethod(paymentMethod);

  // Set amount
  const amount: Amount = {
    currency: 'CNY',
    value: '10000'
  };
  request.setPaymentAmount(amount);

  // Set order
  const order: Order = {
    referenceOrderId: 'order_' + Date.now(),
    orderDescription: 'Test Product',
    orderAmount: amount,
    buyer: {
      buyerEmail: '[email protected]',
      referenceBuyerId: '12345679'
    },
    goods: [{
      goodsBrand: 'Test Brand',
      goodsName: 'Test Product'
    }],
    merchant: {
      merchantMcc: 'merchantMcc',
      referenceMerchantId: 'merchant_' + Date.now()
    }
  };
  request.setOrder(order);

  // Set settlement strategy
  const settlementStrategy: SettlementStrategy = {
    settlementCurrency: 'USD'
  };
  request.setSettlementStrategy(settlementStrategy);

  // Set environment
  const env: Env = {
    terminalType: TerminalType.WEB
  };
  request.setEnv(env);

  try {
    const response = await client.execute(request);
    const responseData = JSON.parse(response);
    
    if (responseData.result?.resultStatus !== ResultStatusType.F) {
      console.log('Payment created successfully:');
      console.log('Payment ID:', responseData.paymentId);
      console.log('Payment Create Time:', responseData.paymentCreateTime);
      console.log('Payment URL:', responseData.normalUrl);
    } else {
      console.log('Payment failed:', responseData.result?.resultMessage);
    }
  } catch (error) {
    console.error('Payment error:', error);
  }
}

pay();

2. Payment Consultation Example

import {
  DefaultAntomClient,
  AntomPayConsultRequest,
  Amount,
  Env,
  SettlementStrategy,
  ProductCodeType,
  TerminalType,
  OsType
} from 'antom-nodejs-sdk';

async function payConsult() {
  const client = new DefaultAntomClient(
    GATEWAY_HOST,
    CLIENT_ID,
    MERCHANT_PRIVATE_KEY,
    ALIPAY_PUBLIC_KEY
  );

  const request = new AntomPayConsultRequest();
  request.setProductCode(ProductCodeType.CASHIER_PAYMENT);
  request.setUserRegion('SG');

  const paymentAmount: Amount = {
    currency: 'USD',
    value: '1000'
  };
  request.setPaymentAmount(paymentAmount);

  const env: Env = {
    terminalType: TerminalType.APP,
    osType: OsType.IOS
  };
  request.setEnv(env);

  const settlementStrategy: SettlementStrategy = {
    settlementCurrency: 'USD'
  };
  request.setSettlementStrategy(settlementStrategy);

  request.setAllowedPaymentMethodRegions(['HK', 'US', 'CN']);

  try {
    const response = await client.execute(request);
    const responseData = JSON.parse(response);
    
    if (responseData.result?.resultStatus !== ResultStatusType.F) {
      console.log('Available payment options:', responseData.paymentOptions);
    } else {
      console.log('Consult failed:', responseData.result?.resultMessage);
    }
  } catch (error) {
    console.error('Consult error:', error);
  }
}

3. Payment Query Example

import {
  DefaultAntomClient,
  AntomPayQueryRequest
} from 'antom-nodejs-sdk';

async function payQuery(paymentId: string) {
  const client = new DefaultAntomClient(
    GATEWAY_HOST,
    CLIENT_ID,
    MERCHANT_PRIVATE_KEY,
    ALIPAY_PUBLIC_KEY
  );

  const request = new AntomPayQueryRequest();
  request.setPaymentId(paymentId);

  try {
    const response = await client.execute(request);
    const responseData = JSON.parse(response);
    
    if (responseData.result?.resultStatus !== ResultStatusType.F) {
      console.log('Payment ID:', responseData.paymentId);
      console.log('Payment Status:', responseData.paymentStatus);
    } else {
      console.log('Query failed:', responseData.result?.resultMessage);
    }
  } catch (error) {
    console.error('Query error:', error);
  }
}

4. Using Signature and Verification Utilities Directly

import { sign, verify } from 'antom-nodejs-sdk';

// Sign a request
const signature = sign(
  'POST',
  '/ams/api/v1/payments/pay',
  'your_client_id',
  '2023-10-25T02:06:10Z',
  '{"amount":{"currency":"USD","value":"100"}}',
  MERCHANT_PRIVATE_KEY
);

// Verify a response
const isValid = verify(
  'POST',
  '/ams/api/v1/payments/pay',
  'your_client_id',
  '2023-10-25T02:06:11Z',
  '{"result":{"resultCode":"SUCCESS"}}',
  'signature_string',
  ALIPAY_PUBLIC_KEY
);

API Reference

Core Classes

DefaultAntomClient

The main client for making API requests.

Constructor:

new DefaultAntomClient(
  gatewayUrl: string,
  clientId: string,
  merchantPrivateKey: string,
  alipayPublicKey: string,
  agentToken?: string
)

Methods:

• execute(request: AntomRequest): Promise<string> - Execute an API request

AntomRequest

Base class for all API requests.

Properties:

• path: string - API endpoint path
• httpMethod: HttpMethod - HTTP method (GET, POST, etc.)
• keyVersion?: string - Key version for signature

Methods:

• toAmsJson(): string - Convert request to JSON string

Available Request Types

• AntomPayRequest - Payment request
• AntomPayConsultRequest - Payment consultation request
• AntomPayQueryRequest - Payment query request
• AntomPayCancelRequest - Payment cancellation request
• AntomCaptureRequest - Capture request
• AntomRefundRequest - Refund request
• AntomRefundQueryRequest - Refund query request
• AntomCreateSessionRequest - Create payment session request

Enums

• ProductCodeType - Product code types
• TerminalType - Terminal types
• OsType - Operating system types
• ResultStatusType - Result status types
• HttpMethod - HTTP methods

Error Handling

The SDK throws AntomApiException for API-related errors:

try {
  const response = await client.execute(request);
  // Process response
} catch (error) {
  if (error instanceof AntomApiException) {
    console.error('API Error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Sandbox Mode

The SDK automatically detects sandbox mode when the client ID starts with "SANDBOX_". In sandbox mode, API paths are automatically adjusted from /ams/api to /ams/sandbox/api.

License

MIT License