Skip to main content

​
Overview

The paymentMethodId parameter allows you to specify which payment method should be used for a transaction. This gives you control over the payment experience and enables features like forcing specific payment methods, building custom selectors, or pre-selecting based on user preferences.
The paymentMethodId is required when creating a payment session. Use getPaymentsMethods() to retrieve available payment method IDs.

​
How it works

1

Retrieve available payment methods

Use getPaymentsMethods() to fetch all available payment methods for your account.
2

Select a payment method

Choose the appropriate payment method based on your business logic (currency, country, user preference, etc.).
3

Use the payment method ID

Pass the id property of the selected payment method as the paymentMethodId parameter in createSession().
4

Payment is processed

The customer will be directed to pay using the specified payment method.

​
Implementation

​
Example with payment method selection

const payviox = new Payviox('your_api_token');

async function processPayment() {
  try {
    // Step 1: Get available payment methods
    const methods = await payviox.getPaymentsMethods({
      currencies: 'USD'
    });

    // Step 2: Select a payment method (e.g., prefer card payments)
    let selectedMethod = methods.find(m => m.type === 'card');
    
    // Fallback to first available method if card not available
    if (!selectedMethod && methods.length > 0) {
      selectedMethod = methods[0];
    }

    if (!selectedMethod) {
      throw new Error('No payment methods available');
    }

    // Step 3: Create session with the payment method ID
    await payviox.createSession({
      amount: 5000,
      currency: 'USD',
      customer: 'user@example.com',
      description: 'Order payment',
      paymentMethodId: selectedMethod.id, // Use the payment method ID
      order_id: 'order_' + Date.now(),
      items: [
        { name: 'Product', quantity: 1, price: 5000 }
      ]
    }, {
      redirect: true
    });

  } catch (error) {
    console.error('Payment error:', error.message);
  }
}

​
Payment method object structure

When you call getPaymentsMethods(), each payment method object contains the following properties:
PropertyTypeDescriptionExample
idstringUnique identifier used as paymentMethodId in createSession()'pm_card', 'pm_bank_transfer'
namestringHuman-readable name to display to users'Credit Card', 'Bank Transfer'
typestringPayment type category'card', 'bank_transfer', 'wallet'
currenciesstring[]List of supported currency codes (ISO 4217)['USD', 'EUR', 'GBP']
countriesstring[]List of supported country codes (ISO 3166-1 alpha-2)['US', 'FR', 'DE']

​
Common use cases

Use CaseDescriptionImplementation
Force specific payment typeOnly allow card payments, bank transfers, etc.Filter methods array by type property: methods.find(m => m.type === 'card')
Filter by currencyShow only payment methods supporting a specific currencyUse getPaymentsMethods({ currencies: 'USD' }) or filter by currencies array
Filter by countryShow only payment methods available in customer’s countryUse getPaymentsMethods({ countries: 'FR' }) or filter by countries array
Custom payment selectorBuild a UI to let users choose their payment methodLoop through methods array and display each name with a selector button
Save user preferenceRemember and reuse customer’s preferred payment methodStore the id from their previous choice and reuse it in subsequent transactions
Multi-currency supportDynamically load payment methods based on selected currencyCall getPaymentsMethods() with different currencies parameter when currency changes

​
Filtering options

The getPaymentsMethods() method accepts optional filters:
FilterTypeDescriptionExample
currenciesstring | string[]Filter by one or multiple currency codes'USD' or ['USD', 'EUR']
countriesstring | string[]Filter by one or multiple country codes'FR' or ['FR', 'DE', 'ES']
Example usage: 
// Single currency
const usdMethods = await payviox.getPaymentsMethods({ currencies: 'USD' });

// Multiple currencies
const euroMethods = await payviox.getPaymentsMethods({ 
  currencies: ['EUR', 'GBP'] 
});

// Currency and country
const frenchMethods = await payviox.getPaymentsMethods({ 
  currencies: 'EUR',
  countries: 'FR'
});

getPaymentsMethods()

View full API reference

createSession()

Create payment sessions