Payment processing flow

This page outlines the interaction principles and overall lifecycle between Genstore and Payment Apps in five key stages: account authorization, payment processing, refund, capture, and void. It also provides detailed guidance for each sub-process.

Roles and responsibilities

• Merchant: Initiates authorization, payment, refund, capture, and void operations in the Genstore Merchant Admin.
• Genstore: Forwards requests, maintains payment/refund statuses, and presents the final results in the Merchant Admin.
• Payment App: Validates merchant or user input, performs payment/refund logic, and asynchronously informs Genstore of the final result via callback APIs.

General interaction principles

• Asynchronous callbacks: All payment operations must return the final result to Genstore through the Payment App's Update * result API.
• Idempotency and retries: Each request must support an idempotency key and a secure retry mechanism to ensure consistent results during network issues.
• Immutable final status: Once the result is updated to true or false, it cannot be changed.
• Test mode: The Payment App must support a test mode, where all non-query requests include test: true in the parameters when enabled.

Payment lifecycle overview

The payment lifecycle typically includes the following stages:

1. Authorization: Binding of the merchant account to the payment account.
2. Payment processing: Initiating the payment request, including card-on-file, 3DS verification, offsite payments, etc.
3. Capture: Performing fund capture in the "authorize and capture later" model.
4. Refund: Initiating partial or full refunds for successfully processed payments.
5. Void: Voiding an authorized payment that has not been captured.

Development and integration points

• Mandatory callback APIs:
  • Update account authorization result
  • Update payment result
  • Update refund result
  • Update capture result (if authorization is supported)
  • Update cancel result (if void is supported)
• Security requirements: Card information must use the ECIES encryption/decryption scheme specified by Genstore and bind the context AAD to prevent misuse attacks.
• Launch checklist:
  • Provide test accounts and failure case validation
  • Cover key scenarios such as card payments, 3DS, offsite payments
  • Validate error handling, idempotency, and retry mechanisms
  • Ensure the permission scope is limited to payment-related operations only

Development tips

1. Error handling: Implement a comprehensive error handling mechanism to ensure clear status codes and error messages are returned under all circumstances.
2. Logging: Log all critical operations and status changes to facilitate troubleshooting and transaction audits.
3. Performance optimization: Optimize response times to reduce user waiting and ensure a smooth payment experience.
4. State management: Implement a robust state management system to ensure accurate transitions through the payment lifecycle stages.