allinpay_cnp 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d6a122d0fc477863ecbad367004a05ecae0b0f1876fe04ba82d3c1e24a6bad69
+  data.tar.gz: 88c28a107d766171b93f35bd0e78ff33324503f85401191e904899dd72a45d0b
+SHA512:
+  metadata.gz: 6cf074a1b6b0de55d3beb38c9624fc3a784bd5896af05b6f82838fc24b4e0914f769815e5bf6e5345c1752cedc5688a4c1490d423ee6c47b2452ad08dcd33c79
+  data.tar.gz: adfa675fc31a869b101527c8e54aa3b021ff468f8c33254051fb197a22581f3da027cf6af346353041610e6bc7c2669f6c2532e008df3e71d0c6c4b088021870

data/README.md

@@ -0,0 +1,219 @@
+# AllinpayCnp
+
+通联支付 CNP 跨境信用卡收单 Ruby SDK。
+
+## 安装
+
+### Gemfile
+
+```ruby
+gem 'allinpay_cnp', git: 'https://github.com/your-org/allinpay_cnp'
+```
+
+### 本地安装
+
+```bash
+cd allinpay_cnp
+gem build allinpay_cnp.gemspec
+gem install allinpay_cnp-0.1.0.gem
+```
+
+## 配置
+
+### Rails 项目
+
+创建 `config/initializers/allinpay_cnp.rb`:
+
+```ruby
+AllinpayCnp.configure do |config|
+  config.merchant_id = Rails.application.credentials.dig(:allinpay, :merchant_id)
+  config.private_key = Rails.application.credentials.dig(:allinpay, :private_key)
+  config.public_key  = Rails.application.credentials.dig(:allinpay, :public_key)
+  config.environment = Rails.env.production? ? :production : :test
+  config.timeout     = 30
+  config.logger      = Rails.logger
+end
+```
+
+### 普通 Ruby 项目
+
+```ruby
+require 'allinpay_cnp'
+
+AllinpayCnp.configure do |config|
+  config.merchant_id = '086310030670001'
+  config.private_key = File.read('private_key.pem')
+  config.public_key  = File.read('public_key.pem')
+  config.environment = :test  # :test 或 :production
+  config.timeout     = 30
+  config.logger      = Logger.new($stdout)
+end
+```
+
+### 配置项
+
+| 配置项 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| `merchant_id` | String | 是 | 商户号 |
+| `private_key` | String | 是 | 商户私钥 (PEM 格式) |
+| `public_key` | String | 否 | CNP 公钥，用于验证回调签名 |
+| `environment` | Symbol | 否 | `:test` (默认) 或 `:production` |
+| `timeout` | Integer | 否 | 请求超时时间，默认 30 秒 |
+| `logger` | Logger | 否 | 日志对象 |
+
+## 使用方法
+
+### 获取客户端
+
+```ruby
+client = AllinpayCnp.client
+```
+
+### 统一收银台支付 (Unified Pay)
+
+跳转到通联支付页面完成支付：
+
+```ruby
+response = client.unified_pay(
+  access_order_id: "ORDER_#{Time.now.to_i}",
+  amount: '100.00',
+  currency: 'HKD',
+  urls: {
+    notify_url: 'https://your-domain.com/webhooks/allinpay',
+    return_url: 'https://your-domain.com/payments/complete'
+  },
+  email: 'customer@example.com',
+  language: 'zh-hant',  # 可选: zh-hant, zh-hans, en
+  shipping: {
+    first_name: 'Peter',
+    last_name: 'Zhang',
+    address1: '123 Test Street',
+    city: 'Hong Kong',
+    country: 'HK',
+    zip_code: '000000',
+    phone: '12345678'
+  },
+  billing: {
+    first_name: 'Peter',
+    last_name: 'Zhang',
+    address1: '123 Test Street',
+    city: 'Hong Kong',
+    country: 'HK',
+    zip_code: '000000',
+    phone: '12345678'
+  }
+)
+
+if response.success?
+  redirect_to response.payment_url
+else
+  puts "Error: #{response.result_desc}"
+end
+```
+
+### 查询订单 (Query)
+
+```ruby
+response = client.query('ORIGINAL_ORDER_123')
+
+if response.success?
+  puts "状态: #{response.status}"          # SUCCESS, FAIL, PROCESSING
+  puts "金额: #{response.amount}"
+  puts "币种: #{response.currency}"
+  puts "卡号: #{response.card_no}"         # 脱敏卡号
+  puts "卡组织: #{response.card_orgn}"     # VISA, MASTERCARD 等
+end
+```
+
+### 退款 (Refund)
+
+```ruby
+response = client.refund(
+  ori_access_order_id: 'ORIGINAL_ORDER_123',
+  refund_amount: '50.00'
+)
+
+if response.success?
+  puts '退款成功'
+else
+  puts "退款失败: #{response.result_desc}"
+end
+```
+
+### 验证回调签名
+
+```ruby
+# Rails Controller
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token, only: [:allinpay]
+
+  def allinpay
+    client = AllinpayCnp.client
+
+    unless client.verify_callback(params.to_unsafe_h)
+      render plain: 'FAIL' and return
+    end
+
+    if params[:resultCode] == '0000'
+      payment = Payment.find_by(gateway_order_id: params[:accessOrderId])
+      payment&.mark_as_paid!(
+        transaction_ref: params[:orderId],
+        card_no: params[:cardNo],
+        card_orgn: params[:cardOrgn]
+      )
+    end
+
+    render plain: 'SUCCESS'  # 必须返回 SUCCESS
+  end
+end
+```
+
+## Response 对象
+
+所有 API 方法都返回 `Response` 对象：
+
+```ruby
+response.success?        # 是否成功 (resultCode == '0000')
+response.failure?        # 是否失败
+response.result_code     # 返回码
+response.result_desc     # 返回描述
+response.payment_url     # 支付页面 URL (unified_pay)
+response.access_order_id # 商户订单号
+response.order_id        # CNP 系统订单号
+response.status          # 订单状态 (query)
+response.amount          # 金额
+response.currency        # 币种
+response.card_no         # 脱敏卡号
+response.card_orgn       # 卡组织
+response.body            # 原始响应 Hash
+response['customField']  # 获取任意字段
+```
+
+## API 地址
+
+| 环境 | Unified Pay | QuickPay |
+|------|-------------|----------|
+| 测试 | https://cnp-test.allinpay.com/gateway/cnp/unifiedPay | https://cnp-test.allinpay.com/gateway/cnp/quickpay |
+| 生产 | https://cnp.allinpay.com/gateway/cnp/unifiedPay | https://cnp.allinpay.com/gateway/cnp/quickpay |
+
+## 运行测试
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## 目录结构
+
+```
+lib/
+├── allinpay_cnp.rb           # 主入口
+└── allinpay_cnp/
+    ├── version.rb            # 版本号
+    ├── config.rb             # 配置类
+    ├── signature.rb          # RSA2 签名
+    ├── request.rb            # HTTP 请求
+    ├── response.rb           # 响应封装
+    └── client.rb             # API 客户端
+```
+

data/lib/allinpay_cnp/client.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module AllinpayCnp
+  class Client
+    VERSION = 'V2.0.0'
+
+    def unified_pay(access_order_id:, amount:, currency:, urls:, **options)
+      params = build_unified_pay_params(
+        access_order_id: access_order_id,
+        amount: amount,
+        currency: currency,
+        urls: urls,
+        **options
+      )
+      request.post(:unified_pay, params)
+    end
+
+    def query(ori_access_order_id)
+      params = {
+        version: VERSION,
+        mchtId: config.merchant_id,
+        transType: 'Query',
+        oriAccessOrderId: ori_access_order_id
+      }
+      request.post(:quickpay, params)
+    end
+
+    def refund(ori_access_order_id:, refund_amount:, access_order_id: nil)
+      params = {
+        version: VERSION,
+        mchtId: config.merchant_id,
+        transType: 'Refund',
+        accessOrderId: access_order_id,
+        oriAccessOrderId: ori_access_order_id,
+        refundAmount: refund_amount.to_s
+      }
+      request.post(:quickpay, params)
+    end
+
+    def verify_callback(params)
+      return false unless config.public_key
+
+      Signature.verify(params, config.public_key)
+    end
+
+    private
+
+    def config
+      AllinpayCnp.config
+    end
+
+    def request
+      @request ||= Request.new
+    end
+
+    def build_unified_pay_params(access_order_id:, amount:, currency:, urls:, **options)
+      build_base_params(access_order_id, amount, currency, urls, options)
+        .merge(build_shipping_params(options))
+        .merge(build_billing_params(options))
+        .compact
+    end
+
+    def build_base_params(access_order_id, amount, currency, urls, options)
+      build_order_core_params(access_order_id, amount, currency)
+        .merge(notify_return_urls(urls))
+        .merge(build_base_option_params(options))
+    end
+
+    def build_order_core_params(access_order_id, amount, currency)
+      {
+        version: VERSION,
+        mchtId: config.merchant_id,
+        accessOrderId: access_order_id,
+        amount: amount.to_s,
+        currency: currency
+      }
+    end
+
+    def notify_return_urls(urls)
+      { notifyUrl: urls[:notify_url], returnUrl: urls[:return_url] }
+    end
+
+    def build_base_option_params(options)
+      {
+        language: options[:language] || 'zh-hant',
+        email: options[:email],
+        productInfo: options[:product_info]&.to_json
+      }
+    end
+
+    def build_shipping_params(options)
+      {
+        shippingFirstName: options.dig(:shipping, :first_name),
+        shippingLastName: options.dig(:shipping, :last_name),
+        shippingAddress1: options.dig(:shipping, :address1),
+        shippingAddress2: options.dig(:shipping, :address2),
+        shippingCity: options.dig(:shipping, :city),
+        shippingState: options.dig(:shipping, :state),
+        shippingCountry: options.dig(:shipping, :country),
+        shippingZipCode: options.dig(:shipping, :zip_code),
+        shippingPhone: options.dig(:shipping, :phone)
+      }
+    end
+
+    def build_billing_params(options)
+      {
+        billingFirstName: options.dig(:billing, :first_name),
+        billingLastName: options.dig(:billing, :last_name),
+        billingAddress1: options.dig(:billing, :address1),
+        billingAddress2: options.dig(:billing, :address2),
+        billingCity: options.dig(:billing, :city),
+        billingState: options.dig(:billing, :state),
+        billingCountry: options.dig(:billing, :country),
+        billingZipCode: options.dig(:billing, :zip_code),
+        billingPhone: options.dig(:billing, :phone)
+      }
+    end
+  end
+end

data/lib/allinpay_cnp/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module AllinpayCnp
+  class Config
+    ENVIRONMENTS = %i[test production].freeze
+
+    attr_accessor :merchant_id, :private_key, :public_key, :logger, :timeout
+    attr_reader :environment
+
+    def initialize
+      @environment = :test
+      @timeout = 30
+    end
+
+    def environment=(value)
+      value = value.to_sym
+      raise ArgumentError, "Invalid environment: #{value}" unless ENVIRONMENTS.include?(value)
+
+      @environment = value
+    end
+
+    def test?
+      @environment == :test
+    end
+
+    def production?
+      @environment == :production
+    end
+  end
+end

data/lib/allinpay_cnp/request.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'uri'
+
+module AllinpayCnp
+  class Request
+    ENDPOINTS = {
+      test: {
+        quickpay: 'https://cnp-test.allinpay.com/gateway/cnp/quickpay',
+        unified_pay: 'https://cnp-test.allinpay.com/gateway/cnp/unifiedPay'
+      },
+      production: {
+        quickpay: 'https://cnp.allinpay.com/gateway/cnp/quickpay',
+        unified_pay: 'https://cnp.allinpay.com/gateway/cnp/unifiedPay'
+      }
+    }.freeze
+
+    def post(endpoint_type, params)
+      sign_params(params)
+      url = build_url(endpoint_type)
+      log_request(url, params)
+      response = send_post(url, params)
+      log_response(response)
+      Response.new(response, public_key: config.public_key)
+    rescue Faraday::Error => e
+      log_error(e.message)
+      Response.new(nil, error: e)
+    end
+
+    private
+
+    def config
+      AllinpayCnp.config
+    end
+
+    def sign_params(params)
+      params[:signType] = 'RSA2'
+      params[:sign] = Signature.sign(params, config.private_key)
+    end
+
+    def build_url(endpoint_type)
+      ENDPOINTS[config.environment][endpoint_type]
+    end
+
+    def send_post(url, params)
+      connection.post(url) do |req|
+        req.headers['Content-Type'] = 'application/x-www-form-urlencoded; charset=UTF-8'
+        req.body = encode_params(params)
+      end
+    end
+
+    def encode_params(params)
+      params
+        .reject { |_, v| v.nil? || v.to_s.empty? }
+        .map { |k, v| "#{k}=#{URI.encode_www_form_component(v.to_s)}" }
+        .join('&')
+    end
+
+    def connection
+      @connection ||= Faraday.new do |conn|
+        conn.options.timeout = config.timeout
+        conn.options.open_timeout = config.timeout
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def log_request(url, params)
+      return unless config.logger
+
+      config.logger.info("[AllinpayCnp] POST #{url}")
+      config.logger.debug("[AllinpayCnp] Params: #{params.reject { |k, _| k == :sign }}")
+    end
+
+    def log_response(response)
+      return unless config.logger
+
+      config.logger.info("[AllinpayCnp] Response: #{response.status}")
+      config.logger.debug("[AllinpayCnp] Body: #{response.body}")
+    end
+
+    def log_error(message)
+      return unless config.logger
+
+      config.logger.error("[AllinpayCnp] Error: #{message}")
+    end
+  end
+end

data/lib/allinpay_cnp/response.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module AllinpayCnp
+  class Response
+    SUCCESS_CODE = '0000'
+
+    def initialize(http_response, error: nil, public_key: nil)
+      @http_response = http_response
+      @error = error
+      @public_key = public_key
+      @body = nil
+    end
+
+    def http_success?
+      return false if @error
+
+      @http_response&.success?
+    end
+
+    def success?
+      http_success? && result_code == SUCCESS_CODE
+    end
+
+    def failure?
+      !success?
+    end
+
+    def body
+      @body ||= parse_body
+    end
+
+    def raw_body
+      @http_response&.body
+    end
+
+    def result_code
+      body['resultCode']
+    end
+
+    def result_desc
+      body['resultDesc']
+    end
+
+    def access_order_id
+      body['accessOrderId']
+    end
+
+    def order_id
+      body['orderId']
+    end
+
+    def payment_url
+      body['paymentUrl'] || body['counterUrl'] || body['url']
+    end
+
+    def status
+      body['status']
+    end
+
+    def status_desc
+      body['statusDesc']
+    end
+
+    def amount
+      body['amount']
+    end
+
+    def currency
+      body['currency']
+    end
+
+    def refund_amount
+      body['refundAmount']
+    end
+
+    def trans_time
+      time_str = body['transTime']
+      return nil unless time_str
+
+      Time.strptime(time_str, '%Y%m%d%H%M%S')
+    rescue ArgumentError
+      nil
+    end
+
+    def card_no
+      body['cardNo']
+    end
+
+    def card_orgn
+      body['cardOrgn']
+    end
+
+    def sign
+      body['sign']
+    end
+
+    def valid_signature?
+      return false unless @public_key && sign
+
+      Signature.verify(body, @public_key)
+    end
+
+    def [](key)
+      body[key.to_s]
+    end
+
+    def to_h
+      {
+        success: success?,
+        result_code: result_code,
+        result_desc: result_desc,
+        access_order_id: access_order_id,
+        order_id: order_id,
+        payment_url: payment_url,
+        status: status,
+        amount: amount,
+        currency: currency,
+        raw: body
+      }
+    end
+
+    private
+
+    attr_reader :http_response, :error, :public_key
+
+    def parse_body
+      return { 'resultCode' => 'NETWORK_ERROR', 'resultDesc' => @error.message } if @error
+      return {} if @http_response.nil?
+
+      JSON.parse(@http_response.body)
+    rescue JSON::ParserError
+      { 'resultCode' => 'PARSE_ERROR', 'resultDesc' => 'Invalid JSON', 'raw' => @http_response.body }
+    end
+  end
+end

data/lib/allinpay_cnp/signature.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module AllinpayCnp
+  module Signature
+    class << self
+      def sign(params, private_key)
+        sign_string = build_sign_string(params)
+        rsa_sign(sign_string, private_key)
+      end
+
+      def verify(params, public_key)
+        params = params.transform_keys(&:to_s)
+        signature = params.delete('sign')
+        return false if signature.nil? || signature.empty?
+
+        sign_string = build_sign_string(params)
+        rsa_verify(sign_string, signature, public_key)
+      rescue StandardError
+        false
+      end
+
+      def build_sign_string(params)
+        params
+          .transform_keys(&:to_s)
+          .reject { |k, v| k == 'sign' || v.nil? || v.to_s.strip.empty? }
+          .sort_by { |k, _| k }
+          .map { |k, v| "#{k}=#{v.to_s.strip}" }
+          .join('&')
+      end
+
+      private
+
+      def rsa_sign(content, private_key_pem)
+        pkey = load_private_key(private_key_pem)
+        signature = pkey.sign(OpenSSL::Digest.new('SHA256'), content)
+        Base64.strict_encode64(signature)
+      end
+
+      def rsa_verify(content, signature, public_key_pem)
+        pkey = load_public_key(public_key_pem)
+        pkey.verify(
+          OpenSSL::Digest.new('SHA256'),
+          Base64.decode64(signature),
+          content
+        )
+      end
+
+      def load_private_key(key_content)
+        if key_content.include?('-----BEGIN')
+          OpenSSL::PKey::RSA.new(key_content)
+        else
+          pem = '-----BEGIN PRIVATE KEY-----\n#{key_content}\n-----END PRIVATE KEY-----'
+          OpenSSL::PKey::RSA.new(pem)
+        end
+      end
+
+      def load_public_key(key_content)
+        if key_content.include?('-----BEGIN')
+          OpenSSL::PKey::RSA.new(key_content)
+        else
+          pem = "-----BEGIN PUBLIC KEY-----\n#{key_content}\n-----END PUBLIC KEY-----"
+          OpenSSL::PKey::RSA.new(pem)
+        end
+      end
+    end
+  end
+end

data/lib/allinpay_cnp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AllinpayCnp
+  VERSION = '0.1.1'
+end

data/lib/allinpay_cnp.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'allinpay_cnp/version'
+require_relative 'allinpay_cnp/config'
+require_relative 'allinpay_cnp/signature'
+require_relative 'allinpay_cnp/response'
+require_relative 'allinpay_cnp/request'
+require_relative 'allinpay_cnp/client'
+
+module AllinpayCnp
+  class Error < StandardError; end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      if block_given?
+        yield(config)
+      end
+      config
+    end
+
+    def client
+      Client.new
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: allinpay_cnp
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- DrinE
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 通联支付 CNP 跨境信用卡收单 Ruby SDK
+email:
+- drine.liu@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/allinpay_cnp.rb
+- lib/allinpay_cnp/client.rb
+- lib/allinpay_cnp/config.rb
+- lib/allinpay_cnp/request.rb
+- lib/allinpay_cnp/response.rb
+- lib/allinpay_cnp/signature.rb
+- lib/allinpay_cnp/version.rb
+homepage: https://github.com/CoolDrinELiu/allinpay
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Ruby SDK for Allinpay CNP cross-border payment gateway
+test_files: []