Skip to main content
This guide walks through the complete Embedded Account Capture flow end to end: creating a session server-side, mounting the iFrame SDK in your browser application, and handling the TOKEN_SUCCESS event to capture the customer_account_token.
You’ll need your username, secret, and participant_id to follow this guide. These are provisioned by your Ingo integration manager at onboarding. See Authentication for the signing guide.
The Embedded Account Capture iFrame enforces application-level domain whitelisting. It will not load under localhost or any domain not registered to your program. Before testing in a browser, confirm your development domain with your Ingo integration manager so it can be added to your program’s allowlist. Plan for this before beginning front-end integration work.

​
Environments

EnvironmentBase URL (Session API)
Sandboxhttps://iip-session-management-uat.ingo.money
Productionhttps://iip-session-management.ingo.money
Your server calls the Session Management API with the recipient’s details. This is the only step that requires HMAC-SHA512 signing. The response returns an authorized_url that your client uses to mount the SDK.
POST /api/v1/sessions/point-in-time/plugin HTTP/1.1
Host: iip-session-management-uat.ingo.money
Authorization: hmac username="test", algorithm="hmac-sha512", headers="request-line x-date content-type content-sha512 content-length", signature="..."
X-Date: Fri, 17 Jan 2020 19:59:29 GMT
Content-sha512: HpXfYk7qDatRNVlGHQOv3ELyAVd+JCdUcpHB5PMnu08=
Content-Length: 285
Content-Type: application/json

{
  "participant_unique_id1": "70646041-01ea-4cd6-b657-18ff88e465c7",
  "recipient_information": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address_line1": "123 Main St",
    "city": "Anytown",
    "state": "GA",
    "zip_code": "30301",
    "email_address": "jane.doe@example.com"
  }
}
Successful response:
{
  "status": 100,
  "client_message": "Success",
  "data": {
    "session_identifier": "7830227a-ba47-4d28-9416-cad41a446db7",
    "authorized_url": "https://iip-webplugin-uat.ingo.money/session/7830227a-...",
    "authorized_url_expiration_utc": "2024-01-17T20:14:19Z",
    "participant_unique_id1": "70646041-01ea-4cd6-b657-18ff88e465c7"
  }
}
The authorized_url is valid for 30 seconds. Pass it to your client immediately — do not store it. If it expires before mounting, use idempotency to refresh it without creating a new session. See Session Management for details.
Add the Ingo Instant Payments SDK script to your page:
<script type="text/javascript"
  src="/path/to/ingo.instantpayments.clientsdk_v2.0.js">
</script>
Add a container element in your HTML where the iFrame will be mounted:
<div id="ingo-container"></div>
Create an SDK instance attached to your container element, then mount it using the authorized_url from step 1 and the desired funding destination:
// Create SDK instance
var webPlugin = IngoInstantPayments.create(
  document.getElementById("ingo-container"),
  {
    autoHeight: true,
    scrolling: false
  }
);

// Mount with the authorized URL and funding destination
webPlugin.mount(
  authorizedUrl,
  IngoInstantPayments.FUNDING_DESTINATIONS.DEBIT
);
Available funding destinations:
ConstantPayment Type
FUNDING_DESTINATIONS.DEBITDebit card
FUNDING_DESTINATIONS.CREDITCredit card
FUNDING_DESTINATIONS.ACHBank account (ACH)
FUNDING_DESTINATIONS.BILLPAYBillPay
FUNDING_DESTINATIONS.PAYPALPayPal
Register an event listener for TOKEN_SUCCESS before or immediately after mounting. This event fires when the recipient has successfully entered and confirmed their account details — it contains the customer_account_token you’ll use for all future IngoPay calls.
webPlugin.addEventListener(
  IngoInstantPayments.EVENTS.TOKEN_SUCCESS,
  function(data) {
    var token = data.customer_account_token;
    // Send the token to your server, then pass it into
    // an IngoPay process call to push funds, or an IngoPay
    // debit call to pull funds.
  }
);
The full event payload:
{
  "session_identifier": "7830227a-ba47-4d28-9416-cad41a446db7",
  "tracer_token": "12345_07834f31-9ff3-48ff-a7e7-072242331688",
  "customer_account_token": "0bef3f2d-3e17-4320-a865-39ffb6b96c2e",
  "event_name": "iip.webplugin.token_success",
  "funding_destination": "debit"
}
Also register listeners for TERMINAL_FAILURE and MAX_VERIFICATION_ATTEMPTS_EXCEEDED to handle cases where the recipient cannot be verified. See SDK Events for the full event reference.
Once you have the token, pass it into any IngoPay process call to push funds or any IngoPay debit call to pull funds. If your product mix includes the Banking Platform, include the ledger routing object in the IngoPay call to direct the transaction to the correct entity’s ledger; otherwise no additional fields are required. See Push Funds to an Account and Pull Funds from an Account for the complete payment type reference.

​
What’s next

Session Management

Idempotency, locale configuration, and session lifecycle.

SDK Reference

Full SDK method reference — create, mount, and addEventListener.

SDK Events

All event types, payloads, and error codes.

Authentication

HMAC-SHA512 signing for the Session Create API.