Accept local payment methods

Cards are not how most of Europe pays. iDEAL dominates the Netherlands, Bancontact owns Belgium, and SEPA Direct Debit underpins recurring billing across the eurozone. This guide shows how to present these local methods, handle their bank-redirect flows, and reconcile settlement — runnable against the VINR sandbox.

OverviewAskCopy

Local methods split into two families that behave differently after the customer pays:

• Redirect methods (iDEAL, Bancontact, online banking) — the customer is sent to their bank, authorizes, and returns. Confirmation can be near-instant or take seconds.
• Pull / debit methods (SEPA Direct Debit) — you collect a mandate up front, then debit the account. Settlement is asynchronous and can fail days later via a return.

your server          VINR                customer / bank
    │  create payment  │                       │
    │─────────────────►│                       │
    │  checkoutUrl     │                       │
    │◄─────────────────│   redirect to bank    │
    │──────────────────────────────────────────►│ authorizes
    │  payment.completed | payment.failed (webhook)
    │◄─────────────────│◄──────────────────────│

You never hard-code a method list. Create the payment with the customer's country, and the hosted page renders whatever is eligible.

Method availability by regionAskCopy

Eligibility depends on currency, the customer's country, and the amount. VINR filters automatically, but it helps to know the matrix:

Presenting local methodsAskCopy

Create the payment with the buyer context. Passing paymentMethods: ['auto'] (the default) lets VINR pick the eligible set; pass an explicit array to constrain it.

import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

export async function POST(req: Request) {
  const { orderId, country } = await req.json();

  const payment = await vinr.payments.create(
    {
      amount: 2500,                 // €25.00
      currency: 'EUR',
      description: `Order ${orderId}`,
      customer: { country },        // e.g. 'NL' surfaces iDEAL
      paymentMethods: ['auto'],     // or ['ideal', 'bancontact', 'sepa_debit']
      returnUrl: `https://yoursite.com/orders/${orderId}/return`,
      metadata: { orderId },
    },
    { idempotencyKey: `order-${orderId}` },
  );

  return Response.json({ checkoutUrl: payment.checkoutUrl });
}

Redirect the customer to payment.checkoutUrl. The hosted page shows the bank selector (iDEAL, P24) or single-bank redirect (Bancontact) and routes them to their bank.

Handling redirectsAskCopy

Local methods route through the customer's bank, so two states matter that you rarely see with cards: pending (bank is still confirming) and expired (the customer abandoned the redirect).

When the customer lands on your returnUrl, confirm server-side — never trust the redirect parameters alone.

const payment = await vinr.payments.retrieve(paymentId);

switch (payment.status) {
  case 'completed':
    // safe to show success; fulfil on the webhook
    break;
  case 'pending':
    // bank hasn't confirmed yet — show a "processing" state
    break;
  case 'failed':
  case 'expired':
    // offer the customer another method
    break;
}

Because redirect methods can confirm after the browser returns, treat the webhook as the source of truth and fulfil there exactly once.

export async function POST(req: Request) {
  const event = vinr.webhooks.verify(
    await req.text(),
    req.headers.get('x-vinr-signature'),
  );

  switch (event.type) {
    case 'payment.completed':
      await fulfillOrder(event.data.metadata.orderId);   // idempotent
      break;
    case 'payment.failed':
    case 'payment.expired':
      await releaseReservation(event.data.metadata.orderId);
      break;
  }
  return new Response('OK', { status: 200 });
}

Settlement currencyAskCopy

Local methods always settle in their native currency — EUR for iDEAL, Bancontact, and SEPA. If your payout currency differs, VINR converts at settlement and records the rate on the settlement object.

const payment = await vinr.payments.retrieve(paymentId);

console.log(payment.amount);              // 2500  (presented to buyer, EUR)
console.log(payment.settlement.currency); // 'EUR'
console.log(payment.settlement.amount);   // net after fees, minor units

Reconcile against settlement.id (prefix setl_), not the payment amount — fees and FX mean the deposited amount differs from what the customer paid.

Test itAskCopy

In the sandbox, the hosted page renders a simulator for each method instead of a real bank screen:

Go liveAskCopy

Next stepsAskCopy