Payment methods

A session’s methods array is what the merchant wishes for this session. What is displayed may be a subset, depending on the constraints declared in their own configuration.

The properties every payment method shares

Field	Role
method	card, applepay, paypal, wero, ancv, oney.
id	Optional. Instance key: lets one payment method appear several times
label	Optional. Display label of a promoted instance (“American Express”). If absent, the UI uses the localized method name.
range	Optional. Min and max amounts, overriding the defaults of the configuration. For Oney, this is set at plan level.

Filtering the available payment methods

A contract is rarely worldwide: an Amex opened for a few countries, a PayPal for the SEPA zone, a financing plan reserved to one sales channel. Those limits are defined in your configuration (acl), and you only specify the filters to apply in the session (paymentMethodFilters).

{
  currency: "EUR", total: 1000_00, orderId: "EP-123456",
  paymentMethodFilters: {
    country: "ES",   // The country of the sale: ISO 3166-1 alpha-2
    channel: "LBM",  // Your sales channel: free text
  },
  methods: [ /* … */ ],
}

• country is yours to declare. It is the payer’s country or the country of the selling site.
• channel is your vocabulary. We match it against what your contracts declare in their acl.

Cards

{
  method: "card",
  partialAuth: true,                                         // only if the acquirer supports it
  schemes: ["cb", "visa", "mastercard", "maestro"],          // display order = this order
  cardHolder: true,                                          // ask for the holder's name
  threeDSecure: "sca",                                       // default: ask for the challenge
}

schemes: the list of accepted networks. They are shown on the payment method row and in the form heading in the order you list them. Available: cb, visa, mastercard, amex, maestro, diners, discover, jcb, china_union_pay. Absent, the default is cb, visa, mastercard.

cardHolder: adds a “Cardholder name” field, first in the form.

partialAuth: true: the issuer may authorize less than requested. Omit it if your contract does not support partial authorizations.

threeDSecure: the 3-D Secure preference: sca asks for the authentication challenge, frictionless asks to be spared it.

createAlias — how to register this card for later payments, as one block:

createAlias: {
  mode: "oneclick" | "subscription",
  recurringFrequency: 30, // the number of days between two payments
  recurringExpiry: "2030-12-31", // ISO expiry date of the registration
  maximumFutureDebit: 150_00, // optional: the ceiling on later debits, in cents
  futureDebitType: "guarantee", // optional: why the card will be debited later
}

If the createAlias property is present, the object must carry mode, recurringFrequency and recurringExpiry, and an authentication challenge is required. A session that would ask for a registration and threeDSecure: "frictionless" is refused at creation.

The createAlias property can be added systematically on the cards that support it when the session is created. The alias is only created if the session carries mustCreateAlias: true.

Under the pay button, the card form tells the payer that the card is registered and will be debited later. Two optional properties make that sentence precise, in the payer’s language:

• maximumFutureDebit: the ceiling on later debits, in cents: what one debit may take, or, for a guarantee, what all of them may take in total. It is shown to the payer, enforced when you debit the card, and never sent to the PSP.
• futureDebitType: why the card will be debited later. guarantee: the card is registered as a deposit on what the payer is entrusted with (equipment, accommodation), and may be debited, in one or several goes, for damage or charges identified at the end of the service (equipment returned damaged or not at all, accommodation to clean or repair, keys lost…).

Both require mode: "subscription": in oneclick, the payer pays again themselves, and a session that carries either property is refused at creation.

Debiting the card later

Once the session is PAID, you debit the registered card from your server, without your customer:

POST /api/sessions/{sessionId}/debit
Authorization: Bearer <your API token>
Idempotency-Key: retenue-EP-123456-01

{ "amount": 8000, "extraData": "retenue-EP-123456-01" }

• The card must have been registered with mode: "subscription", and recurringExpiry must not have passed.
• maximumFutureDebit, when declared, caps each debit, or, for a guarantee, all of them together: a deposit is withheld in one or several goes, up to its amount.
• One debit at a time: a second one waits for the verdict of the first.
• The same Idempotency-Key returns the debit already recorded, never a second one.

The call answers 202 with the debit, and its verdict reaches you in the debit webhook. Tell your customer yourself: we do not contact them. See the API reference for every refusal.

Apple Pay

{ method: "applepay" },

Apple Pay does not support authorization: it therefore never offers to pay a partial amount. It stays offered at all times, but it can only settle the session.

The Apple Pay payment method only appears in Safari.

PayPal

{ method: "paypal" },

The payer is redirected to PayPal to complete the payment.

Wero

{ method: "wero" },

Wero does not support authorization: it therefore never offers to pay a partial amount. It stays offered at all times, but it can only settle the session.

ANCV (Chèques-Vacances Connect)

{ method: "ancv" },

The customer enters their Chèque-Vacances Connect id on the page, then confirms in the ANCV app (where they may approve a lower amount than requested).

Limiting what is paid in Chèques-Vacances

authorizationAmountLimit sets the most this order may be paid in Chèques-Vacances, in minor units of the session currency — possibly below the total:

{ method: "ancv", authorizationAmountLimit: 30000 }, // 300 € at most

Unlike range, it does not hide the method. On a 1 000 € order, Chèques-Vacances stays offered: the authorization requests 300 €, the form tells the customer they can authorize up to that amount in their ANCV app, and the rest is paid with another method. Once the remaining balance is below the limit, the form requests the remaining balance, as usual. A tranche above the limit is refused (MethodNotEligible).

Oney (pay in installments)

{
  method: "oney",
  plans: [
    { installments: 3, withFees: true },
    { installments: 4, withFees: true },
    // a fee-free 3×, if your contract has one
    // etc.
  ],
}

The form only shows the plans eligible for the amount. Each plan is also filtered against the paymentMethodFilters. If no plan is left, the Oney payment method is removed from the session.

Required declarations for Oney

A financed order must declare cartItems with their detail, billing and shipping in full (see the API reference).

travel cart line

A line in the travel category requires the session to carry the stay and the passenger (travel property, see the API reference).

It also affects eligibility: the number of days between the order and the earliest travel.stays[].arrivalDate must exceed the withdrawal period (14 days).