BNPL APIRedirect URLsFAQ
BNPL APIRedirect URLsFAQ
milpay doc
  1. FAQ
  • Frequently Asked Questions
  1. FAQ

Frequently Asked Questions

Merchant Integration FAQ#

Answers to the most common questions from merchants integrating the milpay/instacash installment-payment (BNPL) option into their webshop. Organized by topic — if your question isn't covered here, contact your integration/account manager.

1. Onboarding & Going Live#

How long does an unfinished application stay open before it's automatically cancelled?#

15 days of inactivity, for all merchants. If you're building your own "abandoned application" logic on your side, we recommend using a grace period of at least 24–48 hours before treating an application as abandoned locally, since customers often return to finish later than expected — but the definitive cutoff on our side is always 15 days.

Is there a test/sandbox environment before go-live?#

Yes — new integrations receive a staging merchant ID, offer ID, BNPL identifier, and API key, and the test environment behaves identically to production. A test payment-wallet sandbox account (e.g., Barion) can also be provisioned if your setup requires one.

If an order is deleted on the webshop’s site, is it necessary to call the DELETE /bnpl/external/application/{id} endpoint to close the application?#

Yes, the DELETE endpoint must be called to properly close the application after an order is deleted on the webshop.

2. API Keys, Credentials & Merchant Portal Access#

Where do I find my Merchant ID or BNPL/offer identifier?#

These are sent to you by email during onboarding, along with your API key. If you can't locate that email, contact support and we can look them up and send them to you directly.

I get "No available offer" when testing — what does that mean?#

This is always a misconfiguration on our end, not something wrong with your webshop or payment/wallet provider setup. Contact support with your merchant ID and offer ID and we'll correct the configuration on our side.

I'm hitting HTTP 429 "Too Many Requests" on the available-offers endpoint. Can my rate limit be increased?#

We can issue a higher-limit API key on request. In most cases, though, the underlying fix is proper client-side caching of the available-offers/calculation responses — keyed on price and offer ID — rather than calling the endpoint on every page load. We recommend trying caching first, since it typically resolves the issue without needing a new key.

I'm stuck in the Merchant Portal login flow — the 2FA code never arrives, my password reset is rejected, or I get redirected somewhere unexpected.#

This is a known issue related to browser autofill: some browsers autofill the wrong value into the 2FA code field, which can cause unexpected behavior on submission. Try clearing the field and entering the code manually rather than accepting an autofill suggestion. If a password reset is still stuck, contact support and we'll trigger a fresh reset for your account. A permanent fix for the underlying form behavior is in development.

I run several separate webshops — can they share one Merchant Portal login?#

No. The Merchant Portal is per-shop, and one email address or phone number can only be attached to a single portal account. For multi-shop accounts, we set up a separate portal account per shop — using an email alias per store (e.g., you+shopname@yourdomain.com) is a convenient way to keep all notifications in one inbox while satisfying the one-account-per-shop rule.

3. Webhooks & Order / Payment Status Sync#

What IP addresses do the webhook calls come from?#

193.39.12.114

A customer paid their first installment, but the order never appeared in our system. What should we check?#

Two common causes: (1) the webhook call to your endpoint failed — check your server logs for the relevant timestamp for errors such as a 502 or a timed-out request; or (2) a "fallback" deal was created after an initial failed payment attempt, and your integration was only listening for updates tied to the original deal ID (see next question). If your logs don't show an incoming request at all, contact support with the order/deal ID so we can confirm delivery on our side.

Our integration keys webhook handling on dealId, but we sometimes see two different deal IDs for what looks like the same order. Is that expected?#

Yes. In a fallback scenario (an initial payment attempt fails and the customer retries), a second deal is created that shares the same orderId as the first. We recommend keying your internal order matching on purchase.orderId rather than dealId, and re-fetching current status via GET /bnpl/external/deal/{id} using whichever dealId was supplied in the most recent webhook payload.

We're seeing an application status like REJECT_FALLBACK or CLOSED_FALLBACK that our system doesn't recognize.#

Add these values to your own status-mapping logic — the full list of status codes is documented at doc.instacash.dev/bnpl/status-lists. New statuses are occasionally added, so it's worth checking this list periodically.

Do we need to take any action if we never receive the "order successful" webhook or email, even though the payment shows as completed on your side?#

If we confirm the payment and technical status are both fine on our end, it's safe to fulfill the order even if the automatic notification didn't arrive — but please let support know the specific order ID so we can investigate the notification gap.

If we refund or cancel an order on our platform, does that automatically cancel the BNPL application?#

This depends on your integration type. On Shopify, no — a refund or cancellation does not automatically close the corresponding application on our side; you'll need to close it separately using the "close" button in the Merchant Dashboard. On other platforms, a refund or cancellation on your platform does automatically close the corresponding application on our side.

Why does an order sometimes show as "expired" on our platform a few days after checkout, even though the application later shows as accepted?#

Some platforms (e.g., Shopify) auto-expire unpaid orders after just a few days, while customers actually have up to 15 days to complete a BNPL application — so the two systems can briefly disagree. We recommend never manually closing or deleting a pending order early; if the customer's application window genuinely lapses, it will auto-fail on its own, avoiding this conflict.

Can order creation on our platform be delayed until the BNPL application is confirmed successful?#

Generally no — most platforms require the order to be created within seconds of checkout starting, before the outcome of the BNPL application is known.

We're seeing intermittent API errors (404 / 500 / 504) calling your endpoints.#

Common causes: querying a deal ID that belongs to a different merchant account (returns 404), or calling an older, less stable endpoint instead of the current integration gateway. Make sure you're using the gateway.instacash.hu/bnpl/external/... routes rather than any legacy /api/... routes for the most stable experience.

4. Widget Display#

A product has an extra surcharge (e.g., oversized shipping) — why doesn't the product page's installment total include it?#

This is expected on the product page: the surcharge/shipping cost isn't known yet at that point, since it depends on the shipping method and address, which are only entered later in the cart/checkout flow. Once that information is provided, the surcharge is added and the installment total shown at checkout reflects the correct, full amount.

Can we customize the look or placement of the standard product-page widget?#

On platforms using our shared standard widget, we can adjust minor styling such as color and position, but can't build fully custom designs. If you want a bespoke look, you can build your own front-end display and disable our default widget scripts to hide the standard one — ask support which script names to disable for your platform.

Can the installment option be limited to certain products/categories, or only shown within a specific cart-value range?#

This depends on your platform integration and isn't a self-service setting today. Contact your account manager to discuss a custom configuration for your store.
Built with