Payment Processing Flow

Standard Payment Request Pattern

from payments.utils import get_payment_gateway_controller

# 1. Prepare payment details
payment_details = {
    "amount": 100.00,
    "currency": "USD",
    "title": "Payment for Invoice INV-001",
    "description": "Invoice payment",
    "reference_doctype": "Sales Invoice",
    "reference_docname": "INV-001",
    "payer_email": "customer@example.com",
    "payer_name": "John Doe",
    "payment_gateway": "Stripe"
}

# 2. Get gateway controller
controller = get_payment_gateway_controller("Stripe")

# 3. Validate currency
controller.validate_transaction_currency(payment_details["currency"])

# 4. Get payment URL (redirect user)
payment_url = controller.get_payment_url(**payment_details)

# 5. Redirect user to payment_url

Payment Authorization Callback

Reference doctypes implement on_payment_authorized method:

class SalesInvoice(Document):
    def on_payment_authorized(payment_status):
        """Called when payment is completed."""
        if payment_status == "Completed":
            # Update invoice status, create payment entry
            self.status = "Paid"
            self.save()

Payment Status Values:

• "Completed": Payment successful
• "Authorized": Payment authorized (awaiting capture)
• "Failed": Payment failed
• "Cancelled": Payment cancelled