Integration Guides

Hosted Checkout

Seamlessly manage your checkout with PayOS

Overview

PayOS offers a Hosted Checkout, a fully managed front-end payment interface designed to handle the entire payment flow on behalf of merchants. It renders all available payment methods dynamically, manages necessary redirects and MFA challenges, and ensures PCI-compliant handling of sensitive data.

The Hosted Checkout with a choice of available payment methods alongside the merchant's checkout page
Optional Payment Initiation Flow

The Hosted Checkout is an optional payment initiation flow that manages all user engagement and interactions required by the relevant payment method. This approach is ideal for merchants seeking a streamlined, low-compliance solution.

However, PayOS also offers alternative integration methods:

  • Secure Fields: Merchants can use PayOS Secure Fields to embed input SDKs directly into their site, avoiding PCI burden while maintaining control over the user experience.
  • Direct Integration: Best suited for enterprise customers who are fully PCI compliant, this method allows for direct API integration, offering maximum flexibility and control over the payment process.

Key Features

  1. Dynamic Payment Method Rendering:

    • Payment methods are rendered based on dynamic rules configured by the merchant. This process considers a broad set of variables, including those established during merchant configuration and those provided in the payment initiation call.

  2. 3D Secure and MFA Support:

    • Automatically handles multi-factor authentication (MFA) flows like 3D Secure, providing a secure checkout experience with minimal friction.

  3. PCI Compliance:

    • Merchants avoid direct exposure to sensitive payment data, reducing the burden of PCI-DSS compliance.

  4. Customizable Checkout Experience:

    • Merchants can customize the checkout to reflect their brand identity and align with their user experience (UX) preferences by adjusting colors and uploading their logo.

How It Works

  1. Initiate Checkout Session:

    • Start by creating a checkout session using the PayOS API. This session provides a unique token that initializes the checkout flow.

  2. Redirect to Hosted Checkout:

    • Direct your customer to the Hosted Checkout URL returned by PayOS, where they complete their payment.

  3. Receive Payment Status Updates:

    • PayOS notifies the merchant via webhooks about the status of the payment (e.g., successful, failed, pending).

Example Checkout Session Request:

$curl --request POST 'https://api.payos.money/api/v1/checkout-session' --header 'Authorization: Bearer YOUR_API_KEY' --header 'Content-Type: application/json' --data-raw '{
>  "amount": 5000,
>  "currency": "USD",
>  "customer": {
>    "email": "customer@example.com",
>    "name": "John Doe"
>  },
>  "return_url": "https://merchant-site.com/success",
>  "cancel_url": "https://merchant-site.com/cancel"
>}'

Example Response:

1{
2  "checkout_url": "https://checkout.payos.money/session/abc123",
3  "session_id": "abc123",
4  "expires_at": "2024-10-18T14:00:00Z"
5}

Handling Webhooks

PayOS sends webhooks for key events, such as payment success or failure, so merchants can update order statuses in real time.

  • Payment Success: Update order status to ‘Paid’ and proceed with fulfillment.
  • Payment Failed: Notify the customer and allow them to retry.

Example Webhook Payload:

1{
2  "event": "payment.success",
3  "data": {
4    "transaction_id": "txn_12345",
5    "amount": 5000,
6    "currency": "USD",
7    "status": "successful"
8  }
9}

Customizing the Checkout Experience

Merchants can configure the following elements:

  • Logo: Upload your logo to personalize the checkout page.
  • Theme: Adjust colors to match your brand identity.
  • Payment Method Order: Control the order in which payment methods appear.

Benefits of Using Hosted Checkout

  • Reduced Compliance Burden: PayOS handles sensitive data securely, reducing PCI compliance requirements for merchants.
  • Seamless Customer Experience: A smooth payment journey with automatic handling of redirects and authentication.
  • Rapid Integration: The Hosted Checkout can be integrated with minimal development effort.

Example Integration Flow

Conclusion

The PayOS Hosted Checkout offers a comprehensive solution for managing payments with minimal effort. It provides dynamic payment method support, automatic handling of MFA flows, and reduces compliance burden. Merchants can focus on their core business while PayOS ensures a smooth and secure payment process.