Docs / Start

Get started

Get credentials, make your first calls and see a complete flow, in about fifteen minutes.

1. Get credentials#

Create a free account in the developer portal. A workspace is created for you with a client ID, a client secret, an SDK key and a webhook signing secret.

Prefer the command line? This call returns credentials for a workspace that lasts seven days, without an account. You can claim it in the portal later.

curl -X POST https://sandbox.a2ainstapay.com/sandbox/instant

2. Get an access token#

The Tenant API uses OAuth 2.0 client credentials. Tokens last 900 seconds; cache one and request a new one shortly before it expires.

curl -X POST https://sandbox.a2ainstapay.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$A2A_CLIENT_ID \
  -d client_secret=$A2A_CLIENT_SECRET

{ "access_token": "at_sbx_...", "token_type": "Bearer", "expires_in": 900, "scope": "tenant" }

3. Create a customer#

Every request that creates or changes something carries an Idempotency-Key, so a retry never creates a duplicate.

curl -X POST https://sandbox.a2ainstapay.com/v1/customers \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type":"individual","external_ref":"member-1001","email":"alex@example.com","mobile_number":"+12025550148"}'

The response includes onboarding_session.token. In your app, you open the onboarding screen with that token (step 5). For a quick test, finish onboarding without the screens:

curl -X POST https://sandbox.a2ainstapay.com/v1/sandbox/sessions/SESSION_ID/complete \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"outcome":"approved"}'

A few seconds later, GET /v1/customers/{id} shows verification.status as approved and an account_id.

4. Watch a complete flow#

In the portal, open Scenarios and run Link a bank and add funds. Each step shows the request and response, so you can copy them. Then open Records to see each record on its state machine, and Events to see every webhook.

5. Open a hosted screen from your app#

Add the A2A Link SDK to your web app, and open the screen inside the customer's tap:

<script src="https://sandbox.a2ainstapay.com/v1/a2a-link.js"></script>
<script>
  A2ALink.init({ sdkKey: "pk_sbx_your_sdk_key", environment: "sandbox" });
  document.getElementById("open-account").addEventListener("click", () => {
    A2ALink.open({
      fetchToken: async () => (await (await fetch("/api/onboarding", { method: "POST" })).json()).sessionToken,
      onSuccess: ({ resultToken }) => fetch("/api/a2a/exchange", { method: "POST", body: JSON.stringify({ resultToken }) }),
      onExit: ({ reason }) => console.log("Not completed:", reason),
    });
  });
</script>

Your server exchanges the result token with POST /v1/sessions/exchange. See Hosted screens and the web SDK.

6. Receive webhooks#

Set your webhook URL in Webhooks in the portal, or forward webhooks to your own computer without a tunnel:

A2A_CLIENT_ID=... A2A_CLIENT_SECRET=... node a2a-listen.mjs --base https://sandbox.a2ainstapay.com --forward-to http://localhost:3000/webhooks

Verify every signature before you trust an event. Code is in Webhooks.

Next steps#

• Learn the model in Core concepts.
• Try the demo app to see a finished integration, with every call shown live.
• Track your progress towards go-live in Certification in the portal.

Questions about this page? Contact developer support.