Skip to main content

Retrieve payment methods

Before rendering the checkout UI, call the eligibility endpoint to get the list of payment methods available for the order. This prevents displaying options the PSP cannot fulfill and lets you tailor the UI to each customer.

Endpoint​

curl -X POST 'https://api.purse-sandbox.com/payment/v2/eligible-solutions' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-raw '{
    "entity_id": "${ENTITY_ID}",
    "amount": 4999,
    "currency": "EUR",
    "order": {
      "reference": "order-456",
      "net_amount": 4999,
      "tax_amount": 833,
      "billing_address": {
        "first_name": "Emily",
        "last_name": "Parker",
        "address_lines": ["67 Rue de Luxembourg"],
        "city": "Lille",
        "postal_code": "59777",
        "country_code": "FR"
      }
    },
    "customer": {
      "reference": "customer-123",
      "type": "PERSON",
      "email": "[email protected]",
      "ip_address": "203.0.113.195",
      "locale": "fr-FR"
    }
  }'
API Endpoint
  • Endpoint: /payment/v2/eligible-solutions
  • Method: POST
  • API Reference

Request fields​

FieldRequiredDescription
entity_idYesYour merchant entity UUID
amountYesAmount in currency minor units (e.g. 4999 = 49.99 EUR)
currencyYesISO 4217 code (e.g. EUR)
orderYesOrder details — reference, amounts, billing address
customerNoCustomer profile — improves PSP-level eligibility filtering
allow_future_usageNotrue if this is the first payment of a recurring series
customer field

Passing customer is optional but recommended. Some PSPs restrict certain payment methods based on customer locale, country, or account history. Without it, the response may include methods that the PSP will later reject.

Response​

{
  "amount": 4999,
  "currency": "EUR",
  "eligible_solutions": [
    {
      "partner": "dalenys",
      "method": "creditcard",
      "supported_brands": ["CARTE_BANCAIRE", "VISA", "MASTERCARD"]
    },
    {
      "partner": "oney",
      "method": "cb3x",
      "additional_data": {
        "opc": "WB123",
        "is_free": "true",
        "customer_display_label": "Payez en 3x sans frais"
      }
    },
    { "partner": "paypal", "method": "wallet" }
  ]
}

Each item in eligible_solutions has:

  • partner — the PSP that will process this method

  • method — the payment method type (e.g. creditcard, cb3x, wallet, giftcard)

  • supported_brands — the card brands accepted for this solution (e.g. VISA, MASTERCARD, CARTE_BANCAIRE, AMERICAN_EXPRESS, MAESTRO, ONEY). Present only on card solutions that have a brand configuration for your entity; absent on wallets and instalment methods.

  • additional_data — merchant-specific data configured for this solution. Present only when such data is configured, today for Oney solutions. It contains:

    • customer_display_label — the label to show the customer for this option
    • is_free — "true" when the instalments carry no fees for the customer, "false" otherwise
    • opc — the Oney operation code configured for your entity, for information only

    All values in additional_data are strings, and any of them can be null when not configured.

Using the response​

Iterate over eligible_solutions to decide which payment method buttons to render:

const { eligible_solutions } = await fetchEligibleSolutions(order, customer);

const hasCreditCard = eligible_solutions.some(s => s.method === 'creditcard');
const hasInstalment = eligible_solutions.some(s => s.method === 'cb3x');

if (hasCreditCard) renderCardForm();
if (hasInstalment) renderInstalmentOption();

Configure the card form​

Take supported_brands from the creditcard solution and pass it as the brands list of SecureFields. The form then accepts only the brands configured for your entity. Keep a default list for the case where supported_brands is absent.

const cardSolution = eligible_solutions.find(s => s.method === 'creditcard');
const brands = cardSolution?.supported_brands ?? ['VISA', 'MASTERCARD', 'CARTE_BANCAIRE'];

const secureForm = await sf.initSecureFields({
  tenantId: '${VAULT_TENANT_ID}',
  config: {
    brands,
    brandSelector: true,
    fields: { /* ... */ },
  },
});

The order of brands sets the order of the brand selector for co-branded cards — see Card brand selection. When the ONEY brand is enabled for your entity, the supported_brands of the Oney card solution contains ONEY. If one form serves several card solutions, its brands list must include the brands of each of them — see Oney private cards for the date-of-birth field.

Label the Oney option​

Use additional_data.customer_display_label as the text of the Oney button, with your own label as a fallback. is_free is a string, so compare it with 'true':

const oney = eligible_solutions.find(s => s.partner === 'oney' && s.method === 'cb3x');

if (oney) {
  const label = oney.additional_data?.customer_display_label ?? 'Pay in 3 instalments';
  const isFree = oney.additional_data?.is_free === 'true';

  renderInstalmentOption({ label, showNoFeesBadge: isFree });
}
Don't cache results

Eligibility depends on the order amount, currency, and customer profile. Always call this endpoint at checkout time — do not reuse results across sessions or orders.

Next steps​