Mintcash
Guides

Accept APMs

Offer alternative payment methods (APMs) such as iDEAL, Bancontact, BLIK, TWINT and Revolut Pay on the hosted payment page: how to switch them on, how the payment flows, what the customer sees at each step and what to test before going live.

Alternative payment methods, APMs for short, let the customer pay from a bank account or a payment app instead of a card. The payment page sends them to their bank, or to the app on their phone, to approve the payment, then brings them back. This guide covers switching APMs on, the integration, what the customer sees at each step, and what to test.

Before you start

APMs are available on request. Tell your account manager which ones you want, and we enable them on your account.

APMinstrumentUsed by customersSettles in
iDEALidealIn the NetherlandsEUR
BancontactbancontactIn BelgiumEUR
BLIKblikIn PolandPLN
TWINTtwintIn SwitzerlandCHF
Revolut Payrevolut_bankWith a Revolut accountEUR

Your payment stays in the currency you created it in. The customer approves the amount in the APM's currency, converted by our provider at the time of payment, and every webhook and GET /payments response reports your currency and amount.

APMs are for one-time payments

An APM payment leaves no saved card behind, so it can't fund a subscription's renewals. Subscription checkouts never show APMs.

Integration

Your integration is the one-time payment flow, plus one field. List what the payment's page may offer in methods on POST /payments, with apms for every APM enabled on your account, or the APMs by name:

const r = await fetch("https://api.mintcash.me/payments", {
  method: "POST",
  headers: {
    Authorization: `Basic ${btoa(`${publicKey}:${secretKey}`)}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalId: orderId,
    amount: 49.99,
    currency: "USD",
    methods: ["card", "wallets", "apms"],
    returnUrl: `${baseUrl}/order/${orderId}/complete`,
    customer: {
      externalId: customerId,
      email: customer.email,
      name: customer.name,
    },
  }),
});

const { redirectUrl, methods } = await r.json();

The response's methods lists what the page will offer this customer, for example ["card", "apple_pay", "ideal", "bancontact"]. Every rule of methods, how to show the same payment in separate frames of your checkout, and the list layout are in Choose what the checkout offers. The rest of this guide is about the APM flow itself.

The payment page with APMs above the card form
Rendering diagram…
  1. You create the payment; we respond with the redirectUrl.
  2. The payment page shows a button for each APM in methods that's enabled on your account.
  3. The customer picks one and approves the payment at their bank. A bank's page can't run inside a frame, so an embedded page opens it in a new tab, which closes itself when the customer returns. A full-page checkout goes to the bank in the same tab.
  4. We send the webhook to your callbackUrl with the final state. Approval can take a few minutes, and the payment stays pending until the bank confirms it.

Webhooks report the APM as instrument, for example "instrument": "ideal", with card set to null. GET /payments/{paymentId} includes instrument once the customer has chosen a method.

Choosing APMs per payment

To offer only the APMs that suit your customer, name them instead of apms. A single one is fine:

{ "methods": ["card", "ideal"] }

An APM that isn't enabled on your account is left out, and the response's methods shows what the page will offer, so an APM we switch off doesn't break your payment creation. To match your customer's country, map it from your own records and fall back to apms when nothing applies:

const APMS_BY_COUNTRY: Record<string, string[]> = {
  NL: ["ideal"],
  BE: ["bancontact"],
  PL: ["blik"],
  CH: ["twint"],
};

const requested = ["card", "wallets", ...(APMS_BY_COUNTRY[customerCountry] ?? ["apms"])];

What the customer sees, and what you receive

Each row is one moment of the flow: what the page shows, the payment's status, and what reaches you as a webhook and, when embedded, as a mintcash:checkout message.

MomentThe customer seesStatusYou receive
Page loadsThe APM buttons, as tiles or a listcreatedNothing yet
Taps an APM, full page"Taking you to iDEAL…", then the bank's page in the same tabpendingpayment.pending
Taps an APM, embeddedThe bank opens in a new tab. The frame shows "Waiting for payment" with a "Reopen payment" button in case the tab was closedpendingpayment.pending, and mintcash:progress with stage started
The bank can't start the payment"iDEAL isn't available right now, and you haven't been charged. Choose another way to pay." The other methods stay usableback to createdNothing; the payment is open again. After three such failures on one payment it is declined instead
The bank refuses before the customer reaches it"Payment not completed. Your payment wasn't completed, so no charge was made…"failedpayment.failed, and mintcash:checkout with status declined
Approves at the bank"Payment complete", or "Payment received" when embeddedsucceededpayment.succeeded, and mintcash:checkout with status succeeded
Cancels at the bank"Payment not completed…"failedpayment.failed, and mintcash:checkout with status failed
Still at the bank after five minutesThe frame keeps waiting, checking less oftenpendingmintcash:checkout with status pending, once; the final status follows when the bank answers
Comes back through a banking appA result page in a new tab, asking them to switch back to your tab, with a link to your returnUrlper outcomeThe webhook for that outcome
Returns to the checkout while the payment is still open"Your iDEAL payment isn't finished…" with a "Continue to iDEAL" buttonpendingNothing new
The browser blocks the bank tab (embedded)"Your browser blocked the iDEAL tab, so nothing was started. Allow pop-ups for this page and try again, or pay another way."createdNothing
Pays in one frame, then tries another frame of the same paymentThat frame reports the payment as in progresspendingmintcash:checkout with status pending from that frame
The embedded checkout waiting for the bank tab
Embedded: waiting for the bank tab, with a button to reopen it.
The embedded checkout after the browser blocked the bank tab
Embedded: the browser blocked the tab. Nothing was started.
An APM that failed to start
The bank couldn't start the payment. The payment stays open.
An APM payment declined before the bank
Declined before the customer reached the bank.
The success screen after an APM payment
Full page: approved at the bank.
The return tab while it waits for the outcome
The tab the bank returns to, while the outcome settles.

How long a payment stays open

  • The payment page link works for 15 minutes after creation while nothing has been started. After that it shows an expired notice, and you create a new payment.
  • Once the customer has reached the bank, the payment stays pending until the bank answers, however long that takes. Our page keeps watching: every few seconds for the first five minutes, then every fifteen. An embedded page posts pending once at the five-minute mark so you can show a "still processing" state, and posts the final status when it arrives.
  • We can't tell an abandoned bank page from a slow one. If the customer leaves the bank without deciding, the payment stays pending until our provider closes it, which can take as long as the bank's own time limit. Don't block the customer on it: let them start a new payment. The old one can't be paid twice, but if they do complete it later you receive its payment.succeeded like any other, so handle a late success the way you handle one for a card.
  • If an APM fails to start (the bank is unreachable, say), the payment is reopened and the customer can pick another method. After three failed starts on one payment it is declined, so a broken method can't hold a payment open forever.

Coming back from a banking app

On a phone, the bank can send the customer to its app, and the app returns them in a new browser tab. That tab shows the result and asks the customer to switch back to your tab, which already has the outcome. When the payment has a returnUrl, it also offers a link back to it, with ?paymentId= appended. Make sure that page works when opened in a new tab and keeps the customer signed in: session cookies set with SameSite=Strict aren't sent on that link, so use SameSite=Lax.

Embedding

APMs leave the page. An embedded checkout opens the bank in a new tab from the click on the APM button and keeps watching in the frame, so:

  • Your <iframe> needs allow="payment" as for every checkout. If it also has a sandbox attribute, add allow-popups allow-popups-to-escape-sandbox, or every APM button reports the tab as blocked.
  • Keep the frame mounted from mintcash:progress until mintcash:checkout arrives: the result lands in the frame, not in the bank tab.
  • The bank tab closes itself when the customer returns. If the browser refuses, it shows the result and asks the customer to switch back.

What to test

APMs can't be exercised in sandbox: creating a payment with APMs in methods works, and the page renders the buttons, so you can build and style your layout there, but a tap on an APM button can't reach a bank. Once APMs are enabled on your live account, run each flow you plan to ship with a small amount:

  • Happy path: approve at the bank and confirm payment.succeeded.
  • Cancellation: cancel at the bank and confirm payment.failed.
  • Embedded: confirm the bank opens in a new tab and your page receives mintcash:progress and then mintcash:checkout.
  • Phone: pay through a banking app and confirm the link back lands on a working, signed-in page.
  • Two frames, if you use them: start paying in one, then try the other, and confirm it reports the payment as in progress.