> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unibee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Supported Payment Gateways and Payment Types

> A comprehensive guide to all payment gateways and payment types supported by UniBee

UniBee supports multiple payment gateways, each of which may support various payment types. This document provides a comprehensive overview of all payment gateways and their supported payment types.

## Concepts

Before diving into the details, it's important to understand the key concepts:

* **Payment Gateway (Gateway)**: A payment service provider that processes payments (e.g., Stripe, PayPal, Payssion, Xendit, Yuno, Hyperswitch, Alipay, Alipay+, Changelly, Unitpay, FireKassa, MulenPay, Blockonomics, Wire Transfer)
* **Gateway Type (Payment Type Category)**: The category of payment method - Bank Card (1), Cryptocurrency (2), or Wire Transfer (3)
* **Gateway Payment Types**: Specific payment methods supported by each gateway (e.g., Visa, Mastercard, Alipay, WeChat Pay)

## Gateway Types

UniBee categorizes payment methods into three main gateway types:

| Gateway Type       | Type Code | Description                                                     |
| ------------------ | --------- | --------------------------------------------------------------- |
| **Bank Card**      | 1         | Credit cards, debit cards, and other card-based payment methods |
| **Cryptocurrency** | 2         | Digital currencies like Bitcoin, Ethereum, etc.                 |
| **Wire Transfer**  | 3         | Bank wire transfer payments                                     |

## Supported Payment Gateways

UniBee currently supports the following payment gateways:

### 1. Stripe

* **Gateway Name**: `stripe`
* **Gateway Type**: Bank Card (1)
* **Features**:
  * Auto-charge support for subscriptions
  * PCI DSS compliant
  * Global coverage
* **Use Cases**: Global SaaS products, subscription services

**Supported Payment Types**: Stripe supports numerous payment types. You can choose which specific payment types to enable in the gateway configuration. The following table lists the available payment types:

<table>
  <thead>
    <tr>
      <th>Payment Type</th>
      <th>Type ID</th>
      <th>Category</th>
      <th>Country/Region</th>
    </tr>
  </thead>

  <tbody>
    <tr><td>Visa</td><td>visa</td><td>card</td><td>Global</td></tr>
    <tr><td>Mastercard</td><td>mastercard</td><td>card</td><td>Global</td></tr>
    <tr><td>American Express</td><td>amex</td><td>card</td><td>Global</td></tr>
    <tr><td>Discover</td><td>discover</td><td>card</td><td>US, Global</td></tr>
    <tr><td>JCB</td><td>jcb</td><td>card</td><td>Japan, Asia</td></tr>
    <tr><td>Diners Club</td><td>diners</td><td>card</td><td>Global</td></tr>
    <tr><td>UnionPay</td><td>unionpay</td><td>card</td><td>China</td></tr>
    <tr><td>Cartes Bancaires</td><td>cartes\_bancaires</td><td>card</td><td>France</td></tr>
    <tr><td>Apple Pay</td><td>apple\_pay</td><td>wallet</td><td>Global</td></tr>
    <tr><td>Google Pay</td><td>google\_pay</td><td>wallet</td><td>Global</td></tr>
    <tr><td>Alipay</td><td>alipay</td><td>wallet</td><td>China</td></tr>
    <tr><td>WeChat Pay</td><td>wechat\_pay</td><td>wallet</td><td>China</td></tr>
    <tr><td>ACH Direct Debit</td><td>ach\_direct\_debit</td><td>bank\_transfer</td><td>US</td></tr>
    <tr><td>SEPA Direct Debit</td><td>sepa\_debit</td><td>bank\_transfer</td><td>EU</td></tr>
    <tr><td>BACS Direct Debit</td><td>bacs\_debit</td><td>bank\_transfer</td><td>UK</td></tr>
    <tr><td>iDEAL</td><td>ideal</td><td>bank\_redirect</td><td>Netherlands</td></tr>
    <tr><td>Bancontact</td><td>bancontact</td><td>bank\_redirect</td><td>Belgium</td></tr>
    <tr><td>Giropay</td><td>giropay</td><td>bank\_redirect</td><td>Germany</td></tr>
    <tr><td>Sofort</td><td>sofort</td><td>bank\_redirect</td><td>Germany, Austria</td></tr>
    <tr><td>EPS</td><td>eps</td><td>bank\_redirect</td><td>Austria</td></tr>
    <tr><td>Przelewy24</td><td>p24</td><td>bank\_redirect</td><td>Poland</td></tr>
    <tr><td>BLIK</td><td>blik</td><td>mobile</td><td>Poland</td></tr>
    <tr><td>Affirm</td><td>affirm</td><td>buy\_now\_pay\_later</td><td>US, Canada</td></tr>
    <tr><td>Klarna</td><td>klarna</td><td>buy\_now\_pay\_later</td><td>EU, US</td></tr>
    <tr><td>Afterpay</td><td>afterpay\_clearpay</td><td>buy\_now\_pay\_later</td><td>AU, NZ, US, UK, CA, FR</td></tr>
    <tr><td>Link</td><td>link</td><td>wallet</td><td>Global</td></tr>
    <tr><td>Cash App Pay</td><td>cashapp</td><td>wallet</td><td>US, UK</td></tr>
    <tr><td>GrabPay</td><td>grabpay</td><td>wallet</td><td>Southeast Asia</td></tr>
    <tr><td>FPX</td><td>fpx</td><td>bank\_redirect</td><td>Malaysia</td></tr>
  </tbody>
</table>

> 💡 **Note**: This is a partial list. The complete list of supported payment types can be found in the gateway setup interface or via API.

> ⚠️ **Important**: Before you can enable and configure payment types in UniBee, you must first enable the corresponding payment methods in your **Stripe Dashboard**:
>
> 1. Log in to [Stripe Dashboard](https://dashboard.stripe.com/)
> 2. Navigate to **Settings** → **Payment methods**
> 3. Enable the payment methods you want to offer to your customers
> 4. Only payment methods enabled in Stripe will appear and be available for configuration in UniBee

### 2. PayPal

* **Gateway Name**: `paypal`
* **Gateway Type**: Bank Card (1)
* **Features**:
  * Secure account-based payments
  * Supports PayPal account payments and linked cards
  * Supports 200+ countries and regions
* **Use Cases**: International e-commerce, subscription services

### 3. Payssion

* **Gateway Name**: `payssion`
* **Gateway Type**: Bank Card (1)
* **Features**:
  * Extensive coverage of localized payment methods
  * Supports multiple countries and regions
* **Use Cases**: Multi-region businesses requiring localized payment options

**Supported Payment Types**: Payssion supports 100+ localized payment methods across different regions. You can choose which specific payment types to enable in the gateway configuration. The following table lists the available payment types (grouped by region):

<table>
  <thead>
    <tr>
      <th>Payment Type</th>
      <th>Type ID</th>
      <th>Country/Region</th>
    </tr>
  </thead>

  <tbody>
    <tr><td colspan="3"><strong>China & East Asia</strong></td></tr>
    <tr><td>Alipay</td><td>alipay</td><td>China</td></tr>
    <tr><td>WeChat Pay</td><td>wechat</td><td>China</td></tr>
    <tr><td>UnionPay</td><td>unionpay</td><td>China</td></tr>
    <tr><td>PayEasy</td><td>payeasy</td><td>Taiwan</td></tr>
    <tr><td>Konbini</td><td>konbini</td><td>Japan</td></tr>
    <tr><td>eNETS</td><td>enets</td><td>Singapore</td></tr>
    <tr><td>FPX</td><td>fpx</td><td>Malaysia</td></tr>
    <tr><td>MOLPay</td><td>molpay</td><td>Malaysia</td></tr>
    <tr><td>Dragonpay</td><td>dragonpay</td><td>Philippines</td></tr>
    <tr><td>GCash</td><td>gcash</td><td>Philippines</td></tr>
    <tr><td>TrueMoney</td><td>truemoney</td><td>Thailand</td></tr>
    <tr><td>ATM Transfer</td><td>atm\_transfer</td><td>Thailand</td></tr>
    <tr><td colspan="3"><strong>Southeast Asia</strong></td></tr>
    <tr><td>OVO</td><td>ovo</td><td>Indonesia</td></tr>
    <tr><td>Doku</td><td>doku</td><td>Indonesia</td></tr>
    <tr><td>GrabPay</td><td>grabpay</td><td>Southeast Asia</td></tr>
    <tr><td colspan="3"><strong>Europe</strong></td></tr>
    <tr><td>iDEAL</td><td>ideal</td><td>Netherlands</td></tr>
    <tr><td>Giropay</td><td>giropay</td><td>Germany</td></tr>
    <tr><td>Sofort</td><td>sofort</td><td>Germany, Austria</td></tr>
    <tr><td>EPS</td><td>eps</td><td>Austria</td></tr>
    <tr><td>Bancontact</td><td>bancontact</td><td>Belgium</td></tr>
    <tr><td>Przelewy24</td><td>p24</td><td>Poland</td></tr>
    <tr><td>BLIK</td><td>blik</td><td>Poland</td></tr>
    <tr><td>MyBank</td><td>mybank</td><td>Italy</td></tr>
    <tr><td>Postepay</td><td>postepay</td><td>Italy</td></tr>
    <tr><td>Multibanco</td><td>multibanco</td><td>Portugal</td></tr>
    <tr><td>Trustly</td><td>trustly</td><td>Sweden, EU</td></tr>
    <tr><td>Dankort</td><td>dankort</td><td>Denmark</td></tr>
    <tr><td>MobilePay</td><td>mobilepay</td><td>Denmark, Finland</td></tr>
    <tr><td>Swish</td><td>swish</td><td>Sweden</td></tr>
    <tr><td>Verkkopankki</td><td>verkkopankki</td><td>Finland</td></tr>
    <tr><td>Euteller</td><td>euteller</td><td>Finland</td></tr>
    <tr><td>PayU</td><td>payu</td><td>Poland, Romania</td></tr>
    <tr><td>Paysera</td><td>paysera</td><td>Lithuania</td></tr>
    <tr><td colspan="3"><strong>Russia & CIS</strong></td></tr>
    <tr><td>QIWI</td><td>qiwi</td><td>Russia</td></tr>
    <tr><td>Yandex.Money</td><td>yandex</td><td>Russia</td></tr>
    <tr><td>WebMoney</td><td>webmoney</td><td>Russia</td></tr>
    <tr><td>Alfa-Click</td><td>alfa\_click</td><td>Russia</td></tr>
    <tr><td>Sberbank</td><td>sberbank</td><td>Russia</td></tr>
    <tr><td>Tinkoff</td><td>tinkoff</td><td>Russia</td></tr>
    <tr><td colspan="3"><strong>Latin America</strong></td></tr>
    <tr><td>Boleto Bancário</td><td>boleto</td><td>Brazil</td></tr>
    <tr><td>PIX</td><td>pix</td><td>Brazil</td></tr>
    <tr><td>OXXO</td><td>oxxo</td><td>Mexico</td></tr>
    <tr><td>ToditoCash</td><td>toditocash</td><td>Mexico</td></tr>
    <tr><td>Efecty</td><td>efecty</td><td>Colombia</td></tr>
    <tr><td>PSE</td><td>pse</td><td>Colombia</td></tr>
    <tr><td>Redpagos</td><td>redpagos</td><td>Uruguay</td></tr>
    <tr><td>Servipag</td><td>servipag</td><td>Chile</td></tr>
    <tr><td>Webpay</td><td>webpay</td><td>Chile</td></tr>
    <tr><td>Pago Fácil</td><td>pago\_facil</td><td>Argentina</td></tr>
    <tr><td>Rapipago</td><td>rapipago</td><td>Argentina</td></tr>
    <tr><td>AstroPay Card</td><td>astropay</td><td>Latin America</td></tr>
    <tr><td colspan="3"><strong>Other Regions</strong></td></tr>
    <tr><td>POLi</td><td>poli</td><td>Australia, New Zealand</td></tr>
    <tr><td>M-Pesa</td><td>mpesa</td><td>Kenya</td></tr>
    <tr><td>CashU</td><td>cashu</td><td>Middle East, North Africa</td></tr>
    <tr><td>OneCard</td><td>onecard</td><td>Middle East</td></tr>
  </tbody>
</table>

> 💡 **Note**: This is a partial list. The complete list of supported payment types can be found in the gateway setup interface or via API. Payssion supports 100+ payment methods across different countries.

> ⚠️ **Important**: To enable Payssion payment types, you need to contact **Payssion's business team**:
>
> 1. Visit [Payssion website](https://www.payssion.com/) and contact their business team
> 2. Provide your business information (company name, website, expected transaction volume, etc.)
> 3. Request activation for the specific payment types you need
> 4. After Payssion enables the payment types for your account, they will become available for configuration in UniBee

### 4. Xendit

* **Gateway Name**: `xendit`
* **Gateway Type**: Bank Card (1)
* **Region Focus**: Southeast Asia (e.g., Indonesia, Philippines, Vietnam, Malaysia, etc.)
* **Features**:
  * Multiple payment methods: virtual accounts, cards, e-wallets, QR payments, convenience store cash payments, bank transfer, etc.
  * Full payment lifecycle: create payment, query, cancel, capture
  * Refund support (full and partial refunds, with dedicated `refund_id`)
  * Webhook-based status updates for payments and refunds
* **Use Cases**:
  * SaaS / subscription businesses targeting Southeast Asia
  * Merchants needing localized payment methods in Indonesia, Philippines, Vietnam, Malaysia, etc.
  * Businesses that already use Xendit as their primary payment provider

#### Webhook Configuration Requirements

To use Xendit reliably with UniBee, you **must configure Webhooks correctly in the Xendit dashboard**, otherwise payment and refund statuses may not synchronize correctly.

1. **Locate Webhook Settings in Xendit**
   * Log in to your **Xendit Dashboard**
   * Go to **Settings → Developers → Webhooks**

2. **Configure UniBee Webhook URL**
   * In UniBee Admin Portal, open **Configuration → Payment Gateways → Xendit → Webhook Keys** tab
   * Copy the **Callback URL** shown there
   * Paste this URL into the **Webhook URL** field in Xendit’s Webhook configuration

3. **Enable Required Events**
   * In the Xendit Webhook event list, make sure at least the following events are enabled (exact naming may vary slightly by Xendit version, refer to their docs):
     * **`Refund request succeeded && Refund request failed`** (or equivalent refund completion event)
       * Used by UniBee to determine final refund result (Success / Failed)
     * **`Invoices paid`** (or equivalent invoice/payment success event)
       * Used to mark payments as succeeded and trigger downstream actions (e.g., subscription activation)

4. **Why Webhooks Are Critical for Xendit Refunds**
   * Xendit’s Refund API **does not always provide a stable `status` field**, and `failure_code` may be `null` even when the UI shows success
   * Because of this, **UniBee cannot rely only on API polling to know the final refund status**
   * UniBee uses:
     * API response (for basic info and `refund_id`), **plus**
     * Webhook events (for final status)
   * **If Webhooks are not configured or the refund-related event is not enabled, refunds may remain in a Pending state in UniBee**

5. **Signature Verification**
   * When configuring Xendit Webhooks, you will typically get a **Webhook Secret / Signature key**
   * In UniBee Admin Portal, put this secret into **Xendit → Webhook Keys → Webhook Secret**
   * UniBee will verify signatures for each incoming Webhook request to ensure the request is really from Xendit

> 💡 **Recommendation**: After configuring Webhooks, perform at least one end‑to‑end test in **sandbox mode** to verify:
>
> * Payments created in UniBee are reflected and updated correctly via Xendit Webhooks
> * Refunds triggered in UniBee eventually move to **Success / Failed** based on Xendit’s `Refund finalized` Webhook.

***

### 5. Alipay (Universal Version)

* **Gateway Name**: `alipay`
* **Gateway Type**: Bank Card (1)
* **Payment Mode**: Universal Checkout Mode
* **Features**:
  * **Universal checkout**: Users can select their preferred payment method from Alipay's payment gateway
  * **Simple configuration**: No need to specify payment method types
  * **User-friendly**: Customers choose payment methods based on their preferences
  * Popular in China and Asian markets
* **Use Cases**:
  * Businesses targeting Chinese and Asian markets
  * When you want customers to have flexibility in choosing payment methods
  * Simple integration without managing multiple payment method types

**How It Works:**

Alipay (Universal Version) uses a **universal checkout mode** where:

* Customers are redirected to Alipay's payment gateway
* Alipay displays all available payment methods based on the customer's account and merchant capabilities
* Customers can choose from various payment options (Alipay balance, linked cards, credit options, etc.)
* You don't need to specify which payment methods to show - Alipay handles this automatically

> ⚠️ **Important**: To use Alipay, you need to:
>
> 1. **Register an Alipay merchant account**: Visit [Alipay Global Merchant Services](https://global.alipay.com/) or contact Alipay's merchant services team
> 2. **Complete merchant verification**: Submit required business and company documentation for account verification
> 3. **Configure credentials**: Provide Client ID, Alipay Public Key, and Merchant Private Key in UniBee
> 4. Once your Alipay merchant account is approved, you can start using the gateway
>
> Note: The application process may vary depending on your region and business type. Contact Alipay support for the latest requirements.

### 6. Changelly

* **Gateway Name**: `changelly`
* **Gateway Type**: Cryptocurrency (2)
* **Features**:
  * Cryptocurrency payment processing
  * Real-time exchange rate conversion
  * Supports various cryptocurrencies
* **Use Cases**: Cryptocurrency-focused businesses

### 7. Unitpay

* **Gateway Name**: `unitpay`
* **Gateway Type**: Bank Card (1)
* **Features**:
  * Payment gateway for Russia and CIS markets
  * Supports various payment methods for the region
* **Use Cases**: Businesses targeting users in Russia and CIS countries

### 8. Wire Transfer

* **Gateway Name**: `wire_transfer`
* **Gateway Type**: Wire Transfer (3)
* **Features**:
  * Bank wire transfer payments
  * Suitable for large-amount payments
  * Manual confirmation required
  * May require minimum payment amount
* **Use Cases**: B2B subscriptions, enterprise customers, large transactions

### 9. Alipay+ (Enhanced Version)

* **Gateway Name**: `alipay+`
* **Gateway Type**: Alipay+ (6)
* **Payment Mode**: Predefined Payment Method Mode
* **Features**:
  * **40+ payment methods**: Supports extensive local payment methods across Asia-Pacific
  * **Precise control**: You specify exactly which payment methods to offer
  * **Regional targeting**: Perfect for multi-region businesses requiring localized payment experiences
  * **Targeted marketing**: Show specific payment methods based on customer location or preferences
* **Use Cases**:
  * Businesses targeting multiple Asia-Pacific countries
  * When you need to control which specific payment methods customers see
  * Regional localization requirements
  * Businesses needing to leverage specific local payment methods (e.g., GCash in Philippines, DANA in Indonesia)

**How It Works:**

Alipay+ uses a **predefined payment method mode** where:

* You must specify which payment methods to enable during gateway configuration
* Customers are directed directly to the specified payment method
* You have full control over the payment experience
* Supports 40+ payment methods across Asia-Pacific regions

**Supported Payment Methods (Examples):**

Alipay+ supports a wide range of payment methods across different regions:

* **China**: Alipay (ALIPAY\_CN), JKOPay
* **Hong Kong**: AlipayHK (ALIPAY\_HK)
* **Indonesia**: DANA, OVO, GoPay, ShopeePay, QRIS, various bank transfers (Maybank, BNI, etc.)
* **Japan**: PayPay, Konbini (convenience stores), Pay-easy
* **Malaysia**: Touch'n Go eWallet, Boost, Grabpay
* **Philippines**: GCash, Maya, Grabpay
* **Singapore**: Grabpay
* **South Korea**: Kakao Pay, NAVER Pay, Toss Pay
* **Thailand**: TrueMoney, LINE Pay, K PLUS
* **Vietnam**: ZaloPay, MoMo
* **Europe**: Bancontact (Belgium), EPS (Austria)
* **And more**: Additional local payment methods across Asia-Pacific

> 💡 **Note**: For a complete list of supported payment methods, refer to the gateway configuration interface in UniBee or check the API documentation.

> ⚠️ **Important**: To use Alipay+, you need to:
>
> 1. **Register an Alipay+ merchant account**: Visit [Alipay Global Merchant Services](https://global.alipay.com/) or contact Alipay's merchant services team
> 2. **Complete merchant verification**: Submit required business and company documentation
> 3. **Apply for specific payment methods**: Request activation for the payment methods you want to offer based on your target markets
> 4. **Configure credentials and payment methods**:
>    * Provide Client ID, Alipay+ Public Key, and Merchant Private Key
>    * Select at least one payment method type to enable
> 5. Once approved and configured, the specified payment methods will be available to your customers
>
> Note: Different payment methods may have different approval requirements depending on your region and business type. Contact Alipay support for detailed information.

***

## Alipay vs Alipay+: Which Should You Choose?

UniBee supports two Alipay integration options, both based on Antom Online Payments API but with different approaches:

### Comparison Table

| Feature               | Alipay (Universal)                                           | Alipay+ (Enhanced)                                  |
| --------------------- | ------------------------------------------------------------ | --------------------------------------------------- |
| **Payment Selection** | Customer chooses                                             | Merchant specifies                                  |
| **User Experience**   | Universal checkout - customer selects from available options | Direct to specified payment method                  |
| **Configuration**     | Simple - no payment method selection needed                  | Requires selecting specific payment methods         |
| **Payment Methods**   | Dynamic - Alipay shows available options                     | 40+ predefined methods across Asia-Pacific          |
| **Control Level**     | Limited - Alipay controls what's shown                       | Full control - you choose what customers see        |
| **Best For**          | Simple integration, user flexibility                         | Multi-region, localized experience, precise control |

### When to Choose Alipay (Universal Version)

Choose **Alipay** if you:

* ✅ Want customers to have flexibility in choosing their preferred payment method
* ✅ Prefer a simple, quick integration without managing payment method types
* ✅ Primarily serve the Chinese market
* ✅ Want a universal checkout experience where Alipay handles payment method selection
* ✅ Don't need to control which specific payment methods are displayed

**Example Use Case:**

* A SaaS platform targeting Chinese users who may have different payment preferences
* You want to provide a simple payment option and let customers choose their preferred Alipay payment method

### When to Choose Alipay+ (Enhanced Version)

Choose **Alipay+** if you:

* ✅ Need to control which specific payment methods customers see
* ✅ Operate in multiple Asia-Pacific countries and need localized payment experiences
* ✅ Want to offer specific local payment methods (e.g., GCash in Philippines, DANA in Indonesia)
* ✅ Need to provide different payment options for different regions or customer segments
* ✅ Require precise payment method management for marketing or operational purposes

**Example Use Cases:**

* An e-commerce platform operating in Philippines, Indonesia, and Malaysia, wanting to offer GCash, DANA, and Touch'n Go respectively
* A subscription service targeting specific demographics with preferred payment methods
* A business wanting to optimize conversion by showing the most relevant payment method for each region

### Key Differences Summary

**Alipay (Universal):**

* Simpler configuration
* Customer-driven payment method selection
* Less control but easier to set up
* Best for businesses wanting quick integration with flexibility

**Alipay+:**

* More configuration required
* Merchant-driven payment method selection
* Full control over payment experience
* Best for businesses needing regional localization and precise payment method targeting

> 💡 **Tip**: You can configure both Alipay and Alipay+ gateways simultaneously in UniBee if you need different payment experiences for different scenarios or regions.

### 10. FireKassa

* **Gateway Name**: `firekassa`
* **Gateway Type**: Bank Card (1)
* **Features**:
  * Payment gateway services
  * Supports various payment methods
* **Use Cases**: E-commerce and online businesses

### 11. MulenPay

* **Gateway Name**: `mulenpay`
* **Gateway Type**: Bank Card (1)
* **Features**:
  * Payment processing services
  * Supports various payment methods
* **Use Cases**: Online payment processing

### 12. Blockonomics

* **Gateway Name**: `blockonomics`
* **Gateway Type**: Cryptocurrency (2)
* **Features**:
  * Bitcoin payment processing
  * Direct Bitcoin payments
  * No intermediaries
* **Use Cases**: Cryptocurrency-focused businesses, Bitcoin payment acceptance

### 13. Yuno (Payment Link Mode)

* **Gateway Name**: `yuno`
* **Gateway Type**: Bank Card (1)
* **Payment Mode**: Hosted Payment Link (Yuno Checkout Page)
* **Features**:
  * UniBee creates a hosted checkout session (Payment Link) and redirects the user to Yuno
  * Payment status and refund results are synchronized via Yuno Webhooks
  * Supports vaulted token (auto-charge / DIRECT flow) when configured on your UniBee gateway

#### Prerequisites (Yuno Dashboard)

Payment Link may fail to be created or launched (for example: **payment method not available**) unless the following are all configured in Yuno:

1. **Connections**: enable at least one connection.
2. **Routing**: select at least one payment method and bind it to an enabled connection.
3. **Checkout builder**: enable the display toggle for that payment method and **Publish settings**.

Also note that `POST /payment-links` may require `payment_method_types` to be **present and non-empty** (for example `["CARD"]`). Omitting it or sending an empty array can result in a 400 error (behavior may vary by environment/account configuration).

#### Gateway Setup (UniBee + Yuno)

To use Yuno reliably with UniBee, configure both sides as follows.

1. **Configure Yuno gateway settings in UniBee**
   * Go to **Configuration → Payment Gateways** and configure a `yuno` gateway.
   * Essentials / Public-Private Keys (as shown in the UniBee setup modal):
     * `GatewayName`: `yuno`
     * `Account ID` (UniBee field): Yuno `account_id`
     * `Public API Key` (UniBee field): Yuno `public-api-key`
     * `Private Secret Key` (UniBee field): Yuno `private-secret-key`
   * Webhook Keys (as shown in the UniBee setup modal):
     * `Callback URL`: copy the full URL
     * `Webhook Key`: set this into UniBee `WebhookSecret`
     * UniBee will use `WebhookSecret` to verify the webhook header `x-hmac-signature`.

2. **Use the UniBee callback URL in the Yuno dashboard**
   * In Yuno **Developers → Webhooks → Add webhook**:
     * Endpoint URL: paste the **Callback URL** you copied from UniBee.
     * Enable **Use HMAC Authentication**.
   * If you prefer to fetch the callback URL programmatically, you can use:
     * [Payment Gateway Webhook Setup API](/api-reference/gateway/payment-gateway-webhook-setup)

3. **Configure webhook signature verification**

   * UniBee verifies:
     * Header: `x-hmac-signature`
     * Algorithm: `HMAC-SHA256`
     * Encoding: **Base64** (some environments may also accept hex)
     * Secret: UniBee `WebhookSecret`

   **Note**: If Yuno’s UI still requires fields like `x-api-key` / `x-secret`, you can fill placeholder values. UniBee’s verification is based on `x-hmac-signature`.

4. **Enable required events in Yuno**
   * Payment events (examples):
     * `payment.purchase`, `payment.authorized`, `payment.captured`, `payment.failed`, `payment.cancelled`, `payment.succeeded`
   * Refund events (examples):
     * `payment.refund`, `refund.succeeded`, `refund.failed`

> Tip: After enabling webhooks, run at least one end-to-end test in sandbox mode and verify:
>
> * payments move to `PaymentSuccess` after `payment.succeeded`
> * refunds end up in the correct refund result states after `refund.succeeded` / `refund.failed`

### 14. Hyperswitch

* **Gateway Name**: `hyperswitch`
* **Gateway Type**: Bank Card (1)
* **Positioning**: Payment orchestration layer — Hyperswitch routes payments to downstream connectors (PSPs). Actual card brands and rails depend on your Hyperswitch connector configuration.
* **Features**:
  * Customer-present payments and off-session charges (including mandate-based auto-charge for renewals, when configured)
  * Refunds and refund status updates
  * Payment and refund status updates via **Hyperswitch webhooks** when delivered, with **polling** as a complementary sync path in UniBee
  * Optional **Revenue Recovery**: Hyperswitch can own retry/dunning for failed charges; UniBee still consumes final outcomes from Hyperswitch (webhooks and/or polling, depending on configuration)
* **Use Cases**:
  * Merchants who want a single UniBee integration while routing to multiple PSPs through Hyperswitch
  * Teams already operating on Hyperswitch and connecting it to UniBee for subscriptions and invoicing

**API credentials (UniBee)**: In the gateway **Public/Private Keys** step, configure your Hyperswitch **API key** as the private credential UniBee uses for server-to-server calls (Hyperswitch expects it in the `api-key` header). Use **Sandbox** vs **Production** keys that match your environment.

#### Webhooks and status sync

For many merchants, **you do not need a separate “create webhook endpoint in Hyperswitch Dashboard” flow** the way some other gateways require. UniBee still exposes the standard inbound URL (for reference and for features that need an explicit endpoint), but **focus on API credentials first**; payment status can be reconciled via Hyperswitch APIs and UniBee’s payment checker even when you are not manually wiring a webhook URL in Hyperswitch.

* **UniBee inbound URL (reference)**\
  `POST /payment/gateway_webhook_entry/{gatewayId}/notifications`\
  Replace `{gatewayId}` with your Hyperswitch gateway id in UniBee. You may see this as **Callback URL** under **Webhook Keys** in the UniBee gateway setup, or via [Payment Gateway Webhook Setup API](/api-reference/gateway/payment-gateway-webhook-setup).

* **When Hyperswitch does send webhooks**, configure verification in UniBee:
  * Copy Hyperswitch **Business Profile** field **`payments_response_hash_key`** into UniBee **`WebhookSecret`** (the Webhook Key field in UniBee, if shown).
  * UniBee verifies:
    * Header: `x-webhook-signature-512`
    * Algorithm: `HMAC-SHA512` over the **raw request body**, compared against `WebhookSecret`

* **Typical webhook event types (examples)**
  * Payments: `payment_succeeded`, `payment_failed`, `payment_processing`, `payment_cancelled`
  * Refunds: `refund_succeeded`, `refund_failed`

See [Hyperswitch Webhooks](https://docs.hyperswitch.io/explore-hyperswitch/payment-orchestration/quickstart/webhooks) for payload details. If you use **Revenue Recovery** or other Hyperswitch modules that require an explicit outbound webhook URL in their own settings, follow Hyperswitch’s documentation for that module — requirements can differ from basic card payments.

## Gateway Payment Type Structure

Each gateway payment type contains the following information:

| Field           | Description                            | Example                     |
| --------------- | -------------------------------------- | --------------------------- |
| **name**        | Display name of the payment type       | "Visa", "Alipay", "Bitcoin" |
| **paymentType** | Unique identifier for the payment type | "visa", "alipay", "btc"     |
| **category**    | Category classification                | "card", "wallet", "crypto"  |
| **countryName** | Supported countries/regions            | "US", "CN", "Global"        |
| **autoCharge**  | Whether auto-charge is supported       | `true` or `false`           |

## How to Query Gateway Payment Types

**Note**: The following gateways support payment types selection (they have corresponding JSON configuration files in the backend):

* **Stripe** (`stripe`): Supports various card types and payment methods
* **Payssion** (`payssion`): Supports numerous localized payment methods across different regions
* **Alipay+** (`alipay+`): Supports 40+ payment methods across Asia-Pacific (requires selecting specific payment methods)

**Important Notes:**

* **Alipay** (`alipay`) uses a universal checkout mode and does NOT require payment type selection - Alipay handles payment method display automatically
* Other gateways (including FireKassa, MulenPay, Blockonomics, Changelly, Unitpay, PayPal, Wire Transfer) process payments as a single method without selecting specific payment types

To get the complete list of payment types supported by Stripe, Payssion, or Alipay, use the Gateway Setup API:

**API Endpoint**: [Get Payment Gateway List](/api-reference/gateway/get-payment-gateway-list)

```shell theme={null}
curl --location --request GET "$UniBee_API_Host/merchant/gateway/list" \
  --header "Authorization: Bearer $UNIBEE_API_KEY" \
  --header 'Content-Type: application/json'
```

For gateways that support payment types (Stripe, Payssion, Alipay), the response includes a `setupGatewayPaymentTypes` field which contains the complete list of available payment types. For other gateways, this field will be empty or null.

**Example Response Structure**:

```json theme={null}
{
  "code": 0,
  "data": {
    "gateways": [
      {
        "gatewayId": 25,
        "gatewayName": "stripe",
        "gatewayType": 1,
        "setupGatewayPaymentTypes": [
          {
            "name": "Visa",
            "paymentType": "visa",
            "category": "card",
            "countryName": "Global",
            "autoCharge": true
          },
          {
            "name": "Mastercard",
            "paymentType": "mastercard",
            "category": "card",
            "countryName": "Global",
            "autoCharge": true
          }
          // ... more payment types
        ]
      }
      // ... more gateways
    ]
  }
}
```

## Configuring Payment Gateways and Payment Types

You can configure payment gateways through the UniBee Admin Portal or via API. The Admin Portal provides a comprehensive interface for managing all aspects of your payment gateways.

### Accessing Gateway Configuration

1. Navigate to **Configuration** → **Payment Gateways** in the UniBee Admin Portal
2. You'll see a list of all available payment gateways with their current status:
   * **Ready** (green badge): Gateway is fully configured and ready to use
   * **Not Set** (gray badge): Gateway needs to be configured

### Gateway Configuration Features

#### 1. Gateway List Management

**View Gateway Status**:

* See all available payment gateways in a list view
* Each gateway shows its logo, name, display name, and description
* Status indicator shows whether the gateway is ready or needs setup

**Drag and Drop Sorting**:

* Reorder gateways by dragging and dropping items in the list
* The order determines how payment options appear to customers
* Changes are saved automatically

**Gateway Actions**:

* Click **"Set up"** button for new gateways to configure them
* Click **"Edit"** button for configured gateways to modify settings
* Gateway logos can be clicked to visit the gateway's official website (if available)

#### 2. Essentials Configuration Tab

Configure basic gateway settings:

**Display Name**:

* Set a custom display name that customers will see
* This name appears in the payment selection interface

**Gateway Icons**:

* Upload gateway icons/logos (up to 5 icons)
* Supported formats: `.png`, `.jpg`, `.jpeg`, `.svg`
* Maximum file size: 2MB per icon
* Drag and drop to reorder icons
* Icons are displayed in the customer-facing payment selector

**Currency Exchange Rate** (if enabled for the gateway):

* Configure exchange rates for different currency pairs
* Set conversion rates from base currency to target currency
* Add multiple exchange rate configurations
* Useful when gateway supports different currencies than your base currency

#### 3. Public/Private Keys Configuration Tab

Configure gateway authentication credentials:

**Public Key**:

* Enter your gateway's public key (also called API key or publishable key)
* Keys are automatically desensitized (masked) after saving for security
* Required for most payment gateways

**Private Key / Secret Key**:

* Enter your gateway's private/secret key
* This is sensitive information and will be masked after saving
* Required for payment processing

**Payment Types Selection** (if gateway supports multiple payment types):

* Select which specific payment types to enable for this gateway
* Use multi-select dropdown to choose from available payment types
* Each payment type shows:
  * Display name
  * Payment type identifier
  * Supported country/region
* Only selected payment types will be available to customers

**Note**: Payment types selection is also known as "Sub Gateway" configuration. This feature is currently supported by the following gateways (they have corresponding JSON configuration files in the backend):

* **Stripe** (`stripe`): Supports various card types and payment methods
* **Payssion** (`payssion`): Supports numerous localized payment methods across different regions
* **Alipay+** (`alipay+`): Supports 40+ payment methods across Asia-Pacific (you must select at least one payment method)

**Important Note**:

* **Alipay** (`alipay`) is a separate gateway that uses a universal checkout mode. It does NOT require payment types selection because Alipay automatically displays available payment methods based on the customer's account and merchant capabilities. Customers can choose from any available Alipay payment option.

#### 4. Webhook Keys Configuration Tab

Configure webhook settings (if the gateway requires webhook integration):

**Callback URL**:

* View the webhook endpoint URL provided by UniBee
* This URL needs to be configured in your gateway's dashboard
* Copy the URL using the copy button

**Webhook Key / Secret**:

* Enter the webhook secret/key from your gateway
* Used to verify webhook requests from the gateway
* Some gateways provide integration links for easy setup

**Prerequisites**:

* You must configure Public/Private Keys first before setting up webhooks
* Follow the gateway's documentation link (if provided) to complete webhook setup

#### 5. Wire Transfer Configuration

Wire Transfer gateways have a specialized configuration interface:

**Minimum Amount**:

* Set the minimum payment amount for wire transfers
* Amount is specified in your selected currency

**Bank Account Information**:

* **Account Holder**: Name of the account holder
* **BIC** (Bank Identifier Code): 8 or 11 characters
* **IBAN** (International Bank Account Number): Up to 34 characters
* **Address**: Bank address

#### 6. Advanced Configuration Options

**Archive Gateway**:

* Archive gateways that are no longer needed
* Archived gateways won't appear in customer payment options
* Can be restored later if needed
* Available via API: [Payment Gateway Archive API](/api-reference/gateway/payment-gateway-archive)

**Country Configuration**:

* Configure gateway availability by country
* Enable or disable gateways for specific countries
* Available via API: [Payment Gateway Country Config Edit API](/api-reference/gateway/payment-gateway-country-config-edit)

### Configuration Workflow

1. **Initial Setup**:
   * Click **"Set up"** on a gateway
   * Start with **Essentials** tab to configure display name and icons
   * Move to **Public/Private Keys** tab to enter API credentials
   * Select payment types (if gateway supports multiple types)
   * Configure **Webhook Keys** (if required by the gateway)

2. **Verification**:
   * After saving, check if gateway status changes to **"Ready"**
   * Test payments using sandbox/test mode before going live

3. **Ongoing Management**:
   * Use **"Edit"** button to update any configuration
   * Drag and drop to reorder gateways for better customer experience
   * Monitor gateway status and update credentials as needed

### API Configuration

For programmatic configuration, use the following APIs:

* [Payment Gateway Setup API](/api-reference/gateway/payment-gateway-setup): Create or update gateway configuration
* [Get Payment Gateway List API](/api-reference/gateway/get-payment-gateway-list): Retrieve all configured gateways
* [Get Payment Gateway Setup List API](/api-reference/gateway/get-payment-gateway-setup-list): Get detailed configuration list
* [Edit Payment Gateway Sort API](/api-reference/gateway/edit-payment-gateway-sort): Update gateway display order
* [Payment Gateway Archive API](/api-reference/gateway/payment-gateway-archive): Archive/unarchive gateways
* [Payment Gateway Country Config Edit API](/api-reference/gateway/payment-gateway-country-config-edit): Configure country-specific settings
* [Wire Transfer Setup API](/api-reference/gateway/wire-transfer-setup): Configure wire transfer accounts
* [Wire Transfer Edit API](/api-reference/gateway/wire-transfer-edit): Update wire transfer configuration