Accept payments for connected merchants

Use Ionic Blocks to embed a payment form on your platform’s page. Add an empty HTML element where you want the form to appear, then use Ionic.js to mount a Payment Block inside it. Customers enter their card details in that Block. Your platform uses its own API keys and selects the connected merchant with the SDK’s account option. The PaymentIntent belongs to that merchant, who receives the payment. Use the same merchant ID when creating the intent on your server and mounting the Block in the browser. How Connect works explains platform and merchant roles. The Blocks guide covers the shared payment features and options.

Before you begin

Platform test keys from Connect → API keys, with the secret key on your server.
An active connection granting payments:write and payments:read, with those permissions also on the platform key.
Your page’s origin registered for the same mode in Connect → Payment domains.
@ionicfi/sdk 0.4.1 or later and @ionicfi/js 0.2.1 or later.

Select the connected merchant

GET /v1/connected_accounts lists the platform’s connections. Each data[].id is a connected merchant ID. This platform-level request takes no Ionic-Account header. A merchant-scoped request uses Ionic-Account, or the server SDK’s account request option. The selected merchant, amount, and access to the resulting intent must come from your application’s authorization decisions.

Create the PaymentIntent on your server

Use your platform’s secret key and the selected merchant’s ID. The PaymentIntent specifies the payment amount; its client_secret lets the browser display a Block for that payment.

import { Ionic } from "@ionicfi/sdk";

const ionic = new Ionic({ token: process.env.IONIC_PLATFORM_SECRET_KEY });
const paymentIntent = await ionic.paymentIntents.create(
  {
    "Idempotency-Key": requestKey,
    amount: 12500,
    currency: "usd",
    capture_method: "automatic",
  },
  { account: "mer_BBBBBBBBBBBBBB" },
);

requestKey represents the application-assigned key for this operation. Repeating the operation uses the same key and body. The key’s scope includes the receiving merchant and mode. See Idempotency. The create response contains client_secret; secret-key retrieval does not return its value. The browser needs authorized access to that secret, the platform publishable key, and the matching connected merchant ID.

Mount the Payment Block on your page

Add an empty HTML element where you want the payment form to appear:

<div id="payment"></div>

Run this code in the browser after the element exists. Replace the placeholder values with your platform’s publishable key, the connected merchant ID used on your server, and the client_secret returned when that merchant’s PaymentIntent was created.

import { loadIonic } from "@ionicfi/js";

const ionic = await loadIonic("pk_v1_test_...", { account: "mer_BBBBBBBBBBBBBB" });
const blocks = ionic.blocks({ clientSecret: "pi_..._secret_..." });
const payment = blocks.create("payment");
await payment.mount("#payment");

blocks.create("payment") creates the Payment Block. payment.mount("#payment") displays it inside the <div id="payment"> on your page. #payment is the CSS selector for that element. The Block shows Ionic’s card fields, or the intent’s status when card entry is no longer available. Ionic automatically loads the secure card fields in an iframe hosted at embed.ionicfi.com. If your site uses a Content Security Policy, follow the CSP configuration. Mounting displays the Block. Submitting the payment is a separate call to confirmPayment.

Confirm the payment and read its status

ionic.confirmPayment({ blocks }) submits the card details from the mounted Block for its PaymentIntent when your customer chooses to pay. ionic.retrievePaymentIntent(clientSecret) reads that payment’s current status. Both calls use the connected merchant selected in loadIonic. The confirmation methods and retry limits are the same as for a direct merchant. The merchant is fixed for the client’s lifetime. blocks.destroy() removes the UI without canceling a submitted payment. A different merchant requires a new client and an intent belonging to that merchant.

Keep payment data with the correct merchant

Value	Owner or scope
Secret and publishable keys	The platform, in the intended mode.
PaymentIntent and its client secret	The selected connected merchant.
`customer` and saved payment method	The same connected merchant as the intent.
`reference`	Application-supplied correlation text; Ionic does not enforce uniqueness.

Different merchants may use the same reference. A reference does not identify a merchant or authorize access to a client secret. Any application lookup or reuse must preserve the intended merchant and mode as well as the intent’s identity. A platform API key’s access to both merchants does not authorize a customer to access both merchants’ payments.

Platform payment events

A platform webhook endpoint belongs to the platform, so endpoint creation uses platform keys without Ionic-Account. The Program needs connect_webhooks, the key needs webhook-management permissions, and the merchant’s connection needs payments:read for payment events. See Platform webhooks. event.account identifies the connected merchant. A verified signature proves the delivery’s authenticity, not its association with an application’s purchase. The merchant, mode, intent ID, amount, and currency must match the intended payment. reference alone cannot establish that association. Events may be duplicated or arrive out of order. Your application decides how to record payment outcomes and apply fulfillment policy using the event and delivery contracts.

Save a card during the payment

A PaymentIntent with the same merchant’s customer and setup_future_usage: "off_session" enables optional saving. The customer’s consent determines whether saving is requested. See Save the card being entered. For saving without payment, see Save cards for connected merchants. For live-mode setup, see Going live.

Start here

Accept payments

Ionic Blocks

Connect

Recurring billing

After the payment

Build commerce

Concepts

Accept payments for connected merchants

Before you begin

Select the connected merchant

Create the PaymentIntent on your server

Mount the Payment Block on your page

Confirm the payment and read its status

Keep payment data with the correct merchant

Platform payment events

Save a card during the payment

​Before you begin

​Select the connected merchant

​Create the PaymentIntent on your server

​Mount the Payment Block on your page

​Confirm the payment and read its status

​Keep payment data with the correct merchant

​Platform payment events

​Save a card during the payment

Before you begin

Select the connected merchant

Create the PaymentIntent on your server

Mount the Payment Block on your page

Confirm the payment and read its status

Keep payment data with the correct merchant

Platform payment events

Save a card during the payment