Skip to main content

Payment Service

Overview​

The Payment Service provides comprehensive payment lifecycle management for digital businesses using the Java SDK. It enables you to process payments across 100+ connectors through a unified SDK.

Business Use Cases:

  • E-commerce checkout - Authorize funds at purchase, capture when items ship
  • SaaS subscriptions - Set up recurring payments with mandate management
  • Marketplace platforms - Hold funds from buyers, release to sellers on fulfillment
  • Hotel/travel bookings - Pre-authorize for incidentals, capture adjusted amounts
  • Digital goods delivery - Immediate capture for instant-access products

Operations​

OperationDescriptionUse When
authorizeAuthorize a payment amount on a payment method. This reserves funds without capturing them, essential for verifying availability before finalizing.Two-step payment flow, verify funds before shipping
captureFinalize an authorized payment transaction. Transfers reserved funds from customer to merchant account, completing the payment lifecycle.Order shipped/service delivered, ready to charge
getRetrieve current payment status from the payment processor. Enables synchronization between your system and payment processors for accurate state tracking.Check payment status, webhook recovery, pre-fulfillment verification
voidCancel an authorized payment before capture. Releases held funds back to customer, typically used when orders are cancelled or abandoned.Order cancelled before shipping, customer request
reverseReverse a captured payment before settlement. Recovers funds after capture but before bank settlement, used for corrections or cancellations.Same-day cancellation, processing error correction
refundInitiate a refund to customer's payment method. Returns funds for returns, cancellations, or service adjustments after original payment.Product returns, post-settlement cancellations
incrementalAuthorizationIncrease authorized amount if still in authorized state. Allows adding charges to existing authorization for hospitality, tips, or incremental services.Hotel incidentals, restaurant tips, add-on services
createOrderInitialize an order in the payment processor system. Sets up payment context before customer enters card details for improved authorization rates.Pre-checkout setup, session initialization
verifyRedirectResponseValidate redirect-based payment responses. Confirms authenticity of redirect-based payment completions to prevent fraud and tampering.3DS completion, bank redirect verification
setupRecurringSetup a recurring payment instruction for future payments/debits. This could be for SaaS subscriptions, monthly bill payments, insurance payments and similar use cases.Subscription setup, recurring billing

SDK Setup​

import com.hyperswitch.prism.PaymentClient;

PaymentClient paymentClient = PaymentClient.builder()
    .connector("stripe")
    .apiKey("YOUR_API_KEY")
    .environment("SANDBOX")
    .build();

Common Patterns​

E-commerce Checkout Flow​

sequenceDiagram
    participant App as Your App
    participant CS as Prism
    participant PP as Payment Provider

    App->>CS: 1. createOrder
    CS->>PP: Create order with provider
    PP-->>CS: Return provider order
    CS-->>App: Return order_context
    App->>CS: 2. authorize (with order_context)
    CS->>PP: Reserve funds
    PP-->>CS: Return authorization
    CS-->>App: Return connector_transaction_id (AUTHORIZED)
    Note over App: Order ships to customer
    App->>CS: 3. capture (when order ships)
    CS->>PP: Transfer funds
    PP-->>CS: Return capture confirmation
    CS-->>App: Return status: CAPTURED

Flow Explanation:

  1. createOrder - Initialize a payment order at the processor before collecting payment details.

  2. authorize - After the customer enters their payment details, call the authorize method with the order_context from step 1.

  3. capture - Once the order is shipped, call the capture method with the connector_transaction_id from step 2.

Next Steps​