mitol-django-payment-gateway 2023.12.19

mitol-django-payment_gateway

这是一个开源的Django支付网关应用程序。其目的是以合理通用的方式封装支付和退款处理，以便在特定应用程序中相对直接地实现支付和退款处理。

支付网关支持以下支付处理器

• CyberSource

如有必要，可以添加其他支付处理器。

设置

添加payment_gateway应用程序

INSTALLED_APPS = [
    ...
    "mitol.payment_gateway.apps.PaymentGatewayApp",
]

添加/追加此内容到您的设置文件中

# Imports the default cybersource settings defined in mitol-django-payment-gateway for CyberSource (There might be other gateways in future)
from mitol.common.envs import import_settings_modules
import_settings_modules(globals(), "mitol.payment_gateway.settings.cybersource")

对于CyberSource，您需要设置几个密钥（详情见下文）

• ECOMMERCE_DEFAULT_PAYMENT_GATEWAY - 此项的当前默认值是 CyberSource。未来当有更多网关时，它将是使用的网关的值。

安全接受密钥

以下设置来自CyberSource业务中心，在支付配置中的安全接受设置下。

• MITOL_PAYMENT_GATEWAY_CYBERSOURCE_ACCESS_KEY - CyberSource安全接受的访问密钥
• MITOL_PAYMENT_GATEWAY_CYBERSOURCE_PROFILE_ID - CyberSource安全接受的配置文件ID
• MITOL_PAYMENT_GATEWAY_CYBERSOURCE_SECURITY_KEY - CyberSource安全接受的安全密钥
• MITOL_PAYMENT_GATEWAY_CYBERSOURCE_SECURE_ACCEPTANCE_URL - 您Cybersource账户的安全接受URL

CyberSource REST API密钥

以下设置来自CyberSource业务中心，在支付配置->密钥管理->REST API下。

• MITOL_PAYMENT_GATEWAY_CYBERSOURCE_MERCHANT_ID - 与在CyberSource中处理支付相同的商家ID（例如SecureAcceptance）
• MITOL_PAYMENT_GATEWAY_CYBERSOURCE_MERCHANT_SECRET - CyberSource REST API的商家密钥
• MITOL_PAYMENT_GATEWAY_CYBERSOURCE_MERCHANT_SECRET_KEY_ID - 用于CyberSource REST API的商家密钥ID

不直接来自CyberSource账户的值

• MITOL_PAYMENT_GATEWAY_CYBERSOURCE_REST_API_ENVIRONMENT - 当前默认值为 apitest.cybersource.com。可能的值有（apitest.cybersource.com - 用于测试CyberSource REST API，api.cybersource.com - 用于生产CyberSource REST API）。

支付网关应用无需进一步配置。

用法

具体信息请参阅api中的PaymentGateway类。

处理支付（安全接受）

1. 导入PaymentGateway类和常量。
2. 组装您即将处理的交易的详细信息。应有一组表示要购买的项目和某些订单元数据的行项目。如果您的应用需要，您可以可选地传递自定义数据。您还需要提供两个URL - 一个用于显示收据，一个用于处理交易取消 - 交易处理器将重定向客户到这些URL，一旦他们达到支付处理器工作流程的最终状态。
3. 使用步骤2中组装的数据和要使用的支付处理器（每个支持的平台都有一个定义的常量）调用start_payment。您应该会收到一个字典，其中包含您需要重定向客户以完成购买流程的数据。
4. 在您的应用的其他部分，提供收据显示和取消端点的处理器。具体如何操作将取决于所使用的处理器。

自定义数据（merchant_fields）应是一个要随交易数据一起传递的项目列表。每个处理器将以不同的方式处理这些数据（如果处理器支持的话）。对于CyberSource，传递到merchant_fields中的数据将被枚举到其API中可用的“merchant_defined_dataX”字段。

处理退款（CyberSource REST API）

1. 导入PaymentGateway、Refund类和常量。
2. 组装您即将处理的退款的详细信息（即transaction_id、refund_amount、refund_currency）。您可能会从现有的已完成支付中获取这些数据。
3. 使用步骤2中组装的数据和要使用的支付处理器（例如CyberSource）调用start_refund（每个支持的平台都有一个定义的常量）。

退款代码示例

from mitol.payment_gateway.api import PaymentGateway
      # Create a Refund request object to perform operations on
      refund_gateway_request = PaymentGateway.create_refund_request(
          ECOMMERCE_DEFAULT_PAYMENT_GATEWAY,
          transaction_dict  # Ideally this dict should have transaction_id, req_amount, req_currency
      )

      # Call start_refund from PaymentGateway with the Refund object you just created above 
      response = PaymentGateway.start_refund(
          ECOMMERCE_DEFAULT_PAYMENT_GATEWAY,    # Default Gateway to be used for processing e.g. CyberSource
          refund_gateway_request,
      )

添加网关

添加新网关包括添加网关类本身、添加必要的配置设置以及添加一个新的常量来命名网关。

类本身需要实现方法

• prepare_checkout，它应该接受所有相关的订单信息，执行任何使其适合支付处理器的处理，并返回数据以供客户开始实际购买流程。
• perform_refund，它应该接受一个mitol.payment_gateway.api.Refund对象，其中已设置所需数据。

从成功的prepare_checkout调用返回的数据应包含以下内容

• method - 客户浏览器应使用的HTTP方法（通常是POST，但某些支付处理器可能需要其他东西）
• url - 应将客户发送到的URL
• payload - 发送到上述URL的数据通常需要在前端构建一个表单来将有效载荷数据POST到客户浏览器中指定的URL，然后客户在支付处理器网站上完成流程。

从perform_refund调用返回的数据可能是

• 对于成功的退款，您应该会收到一个包含退款详情的ProcessorResponse对象（即状态、消息、响应日期等）。
• 失败情况
  • 如果请求失败是因为重复，您将收到一个包含详细信息的RefundDuplicateException，这样您就可以决定如何处理它（例如，对于MITxOnline，重复请求被视为成功，但可能对其他应用程序不同）。
  • 对于所有其他故障，您将收到一个通用异常（例如 CyberSource.rest.ApiException），其中包含详细信息，以便您可以在应用程序中适当地处理此故障。

CyberSource网关可以用作未来网关的模板。其中大部分内部方法包含CyberSource特定的实现细节，但它应说明如何添加新的处理器。