Core concepts

Tenants, customers, Digital Accounts, hosted screens, result tokens, webhooks and statuses.

The three parts of an integration#

Part	What it does	Talks to
Your server	Holds your credentials, calls the Tenant API, exchanges result tokens and receives webhooks	The Tenant API at `https://sandbox.a2ainstapay.com`
Your app	Your customer experience. Opens A2A InstaPay's hosted screens with the A2A Link SDK, and Plaid Link for bank linking	Your server, and the hosted screens
Webhooks	Tell your server about every change	Your webhook endpoint

Your app never calls the Tenant API directly, and it never holds your client secret.

Tenants and workspaces#

You are a Tenant: a company that offers A2A InstaPay to its own customers under its own brand. In the sandbox, each workspace is a separate Tenant configuration with its own credentials, settings, records and clock. Create as many workspaces as you need, for example one per developer or per test suite.

Customers and Digital Accounts#

A customer is a consumer (type: individual) or a merchant (type: business). Your own identifier goes in external_ref. Once A2A InstaPay approves the customer, it opens a Digital Account: consumer or merchant. Balances are held in an FBO (for benefit of) structure at the Sponsor Bank, either a dedicated FBO account for your program or your scheme inside the program FBO.

Hosted screens, sessions and result tokens#

Steps that need the customer's own consent or credentials happen on A2A InstaPay's hosted screens, never in your app: onboarding, confirming money movement with a PIN or passkey, PIN reset, contact changes and accepting updated documents.

Your server creates a record (for example a payment) or a session. The response carries a single-use session token.
Your app opens the hosted screen with the token. The customer completes the step.
Your app receives a result token and sends it to your server.
Your server exchanges it once with POST /v1/sessions/exchange and gets the outcome.

Flow	Used for	Expires after
`onboarding`	Opening a Digital Account	30 minutes
`payment_confirm`	Confirming a load, payment, withdrawal or refund	5 minutes
`pin_reset`	Choosing a new PIN	15 minutes
`contact_change`	Changing e-mail, mobile number or address	15 minutes
`terms_acceptance`	Accepting updated customer documents	30 minutes

Statuses and webhooks#

Every record has a status and a version. Each change raises a signed webhook event with the object after the change and the previous values of the fields that changed. Webhooks are the source of truth: show the outcome of an exchange at once, then rely on the webhook. Every record type follows a published state machine; see the diagrams.

Money movement over RTP#

Movement	How it travels
Load (add funds)	A Request for Payment to the customer's bank; the customer approves it in their banking app, and the bank sends the funds by RTP
Payment from balance	Within A2A InstaPay, from the payer's Digital Account to the merchant's; final at once
Pay by bank	A Request for Payment to the payer's bank; the funds go straight to the merchant's Digital Account
Withdrawal	An RTP credit transfer to the customer's linked bank account
Refund	From the merchant's Digital Account back to the payer, to balance or by RTP

Amounts, time and identifiers#

Amounts are integers in cents, in USD. 2500 is $25.00.
Times are ISO 8601 in UTC. Business dates for statements and reconciliation use US Eastern Time.
Identifiers have a prefix that names the record, such as cus_, acct_, pay_ and evt_.

Environments#

Environment	Purpose	Base URL
Sandbox	Building, testing and certification	`https://sandbox.a2ainstapay.com`
Production	Live operation after go-live	Issued with production credentials

Questions about this page? Contact developer support.