API reference

Tenant API v1.1

Tenant API for A2A InstaPay (Fintechnology Asia Pacific Lanka Ltd, licensed to FINAP USA LLC). Companion to the A2A InstaPay PaaS Tenant Integration Specification v1.0 and the A2A InstaPay Tenant API Reference v1.1. Example values are illustrative and do not reflect pricing.

Sandbox base URL	`https://sandbox.a2ainstapay.com`
Authentication	OAuth 2.0 client credentials: POST /oauth/token, then `Authorization: Bearer <access_token>`
Format	JSON over HTTPS. Amounts are integers in cents (USD). Times are ISO 8601 in UTC.
Contract files	OpenAPI 3.1 (YAML) · OpenAPI 3.1 (JSON) · Postman collection

Conventions for idempotency, pagination, rate limits and versioning are in API conventions. Try any endpoint against your own workspace in the API explorer.

Errors#

Every error uses the same envelope. code is stable and meant for your code; message is for people and may change. Quote request_id when you contact support.

Field in error	Type	Required	Description
`code`	string	Yes	Stable error code from the error catalog. Code against this value. Example: `limit_exceeded`
`message`	string	Yes	Readable description for logs and support. Do not show it to customers or parse it. Example: `The payment exceeds the daily amount limit for this customer.`
`param`	string or null	No	The request field the error relates to, where there is one. Example: `amount`
`request_id`	string	Yes	Identifier of the request, also returned in the A2A-Request-Id header. Quote it to support. Example: `req_4Hk8Lm2Np6`
`details`	object or null	No	Additional structured information for some errors, described in the catalog.

Example

{
  "error": {
    "code": "limit_exceeded",
    "message": "The amount exceeds the daily amount limit.",
    "param": "amount",
    "request_id": "req_8Hw2Kd9Lq4Zx7c",
    "details": {
      "limit": "daily_amount"
    }
  }
}

Authentication#

POST `/oauth/token`#

Obtain an access token

Exchanges the Tenant's client credentials for an access token. Send the body as application/x-www-form-urlencoded. Cache the token and request a new one shortly before it expires.

No access token; send the client credentials

Request body

Field	Type	Required	Description
`grant_type`	string, one of `client_credentials`	Yes	Always client_credentials. Example: `client_credentials`
`client_id`	string	Yes	Client identifier for the environment. Example: `cli_sbx_example_01`
`client_secret`	string	Yes	Client secret for the environment. Example: `sk_sbx_redacted`

Example request

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

Response

200 OK, with a Token object.

Example response

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

Errors

Status	Error codes
400	parameter_missing
401	invalid_client
429	rate_limited
500	internal_error

Customers#

POST `/v1/customers`#

Registers a consumer or merchant and returns the customer with an onboarding session. Open the session with the SDK to start verification.

Requires an access token
Requires an Idempotency-Key header

Request body

Field	Type	Required	Description
`type`	string, one of `individual`, `business`	Yes	individual for a consumer, business for a merchant. Example: `individual`
`external_ref`	string	Yes	The Tenant's own reference, unique within the Tenant, up to 64 characters. Example: `member-10482`
`email`	string	Yes	E-mail address. Example: `member@example.com`
`mobile_number`	string	Yes	US mobile number in E.164 format. Example: `+12025550148`
`prefill`	object or null	No	Optional values to prefill the hosted screens: first_name, last_name, or for a business legal_name. Used for an existing operation.

Example request

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-10482","email":"member@example.com","mobile_number":"+12025550148","prefill":{"first_name":"Avery","last_name":"Morgan"}}'

Response

201 Created, with a Customer object.

Example response

{
  "id": "cus_c9T2kXq4Lm",
  "object": "customer",
  "type": "individual",
  "external_ref": "member-10482",
  "email": "member@example.com",
  "mobile_number_last4": "4821",
  "business": null,
  "verification": {
    "status": "created",
    "updated_at": "2026-10-15T14:03:22Z",
    "retry_available_at": null
  },
  "account_id": null,
  "pin_locked": false,
  "onboarding_session": {
    "id": "ses_1Kd7Fg3Hj8",
    "flow": "onboarding",
    "token": "st_sbx_8a3c1e7f9b2d4a6c",
    "expires_at": "2026-10-15T14:33:22Z"
  },
  "created_at": "2026-10-15T14:03:22Z",
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
400	idempotency_key_missing, parameter_invalid, parameter_missing
401	authentication_required
403	flow_not_enabled
409	duplicate_external_ref, duplicate_mobile_number
429	rate_limited
500	internal_error

GET `/v1/customers`#

Find a customer by external reference

Returns a list containing the customer with the given external_ref, or an empty list.

Requires an access token

Parameters

Name	In	Required	Description
`external_ref`	query	Yes	The Tenant's reference.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/customers" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a CustomerList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "cus_c9T2kXq4Lm",
      "object": "customer",
      "type": "individual",
      "external_ref": "member-10482",
      "email": "member@example.com",
      "mobile_number_last4": "4821",
      "business": null,
      "verification": {
        "status": "approved",
        "updated_at": "2026-10-15T14:04:10Z",
        "retry_available_at": null
      },
      "account_id": "acct_c3J8vN2Qe6",
      "pin_locked": false,
      "created_at": "2026-10-15T14:03:22Z",
      "updated_at": "2026-10-15T14:04:10Z",
      "version": 3
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
400	parameter_missing
401	authentication_required
429	rate_limited
500	internal_error

GET `/v1/customers/{id}`#

Retrieve a customer

Returns the customer, including verification status, account identifier and PIN lock status.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Customer identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/customers/{id}" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a Customer object.

Example response

{
  "id": "cus_c9T2kXq4Lm",
  "object": "customer",
  "type": "individual",
  "external_ref": "member-10482",
  "email": "member@example.com",
  "mobile_number_last4": "4821",
  "business": null,
  "verification": {
    "status": "approved",
    "updated_at": "2026-10-15T14:04:10Z",
    "retry_available_at": null
  },
  "account_id": "acct_c3J8vN2Qe6",
  "pin_locked": false,
  "created_at": "2026-10-15T14:03:22Z",
  "updated_at": "2026-10-15T14:04:10Z",
  "version": 3
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

GET `/v1/customers/{id}/owners`#

List owners of a business

Returns the owners and control person of a business customer, with their verification status.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Business customer identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/customers/{id}/owners" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a OwnerList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "own_2Lp9Vc4Mz7",
      "object": "owner",
      "customer_id": "cus_m7R5pWz1Hd",
      "name": "Jordan Ellis",
      "role": "owner_and_control_person",
      "ownership_percent": 60,
      "verification_status": "approved",
      "invited_at": "2026-10-15T14:03:22Z",
      "updated_at": "2026-10-15T14:04:10Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
401	authentication_required
404	not_found
409	invalid_state
429	rate_limited
500	internal_error

GET `/v1/customers/{id}/documents`#

List accepted customer documents

Returns the customer documents the customer has accepted or must accept, with versions and times.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Customer identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/customers/{id}/documents" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a DocumentAcceptanceList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "dacc_3Nb6Vc9Xz2",
      "object": "document_acceptance",
      "customer_id": "cus_c9T2kXq4Lm",
      "document_type": "digital_account_terms",
      "version": "2026.10",
      "status": "accepted",
      "accepted_at": "2026-10-15T14:03:22Z",
      "channel": "onboarding"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

POST `/v1/customers/{id}/close`#

Request account closure

Requests closure of the customer's Digital Account. The account moves to closing; the remaining balance is paid to the customer's linked account, or held where a legal or compliance hold applies. account.closed follows.

Requires an access token
Requires an Idempotency-Key header

Parameters

Name	In	Required	Description
`id`	path	Yes	Customer identifier.

Request body

Field	Type	Required	Description
`reason`	string, one of `customer_request`, `tenant_request`	Yes	Who requested the closure. Example: `customer_request`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/customers/{id}/close" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"customer_request"}'

Response

202 Accepted, with a Customer object.

Example response

{
  "id": "cus_c9T2kXq4Lm",
  "object": "customer",
  "type": "individual",
  "external_ref": "member-10482",
  "email": "member@example.com",
  "mobile_number_last4": "4821",
  "business": null,
  "verification": {
    "status": "approved",
    "updated_at": "2026-10-15T14:04:10Z",
    "retry_available_at": null
  },
  "account_id": "acct_c3J8vN2Qe6",
  "pin_locked": false,
  "created_at": "2026-10-15T14:03:22Z",
  "updated_at": "2026-10-15T14:04:10Z",
  "version": 7
}

Errors

Status	Error codes
400	idempotency_key_missing
401	authentication_required
404	not_found
409	invalid_state
429	rate_limited
500	internal_error

Hosted sessions#

POST `/v1/sessions`#

Create a hosted session

Creates a single-use session for a hosted flow. Use it to start pin_reset, contact_change or terms_acceptance, or to replace an onboarding or payment_confirm session that expired before the customer finished.

Requires an access token
Requires an Idempotency-Key header

Request body

Field	Type	Required	Description
`flow`	string, one of `onboarding`, `payment_confirm`, `pin_reset`, `contact_change`, `terms_acceptance`	Yes	Hosted flow. Example: `pin_reset`
`customer_id`	string	Yes	Customer identifier. Example: `cus_c9T2kXq4Lm`
`target`	Target or null	No	Record to confirm. Required for payment_confirm.
`return_url`	string or null	No	Registered return address, for mobile browsers. Example: `https://app.example.com/a2a/return`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/sessions" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"flow":"pin_reset","customer_id":"cus_c9T2kXq4Lm"}'

Response

201 Created, with a Session object.

Example response

{
  "id": "ses_6Yt2Rw9Qe4",
  "object": "session",
  "flow": "pin_reset",
  "customer_id": "cus_c9T2kXq4Lm",
  "target": null,
  "status": "created",
  "token": "st_sbx_5e1a9c3f7b2d8a4c",
  "return_url": "https://app.example.com/a2a/return",
  "expires_at": "2026-10-15T14:18:22Z",
  "created_at": "2026-10-15T14:03:22Z"
}

Errors

Status	Error codes
400	idempotency_key_missing, parameter_missing
401	authentication_required
409	invalid_state
422	account_restricted, session_invalid
429	rate_limited
500	internal_error

POST `/v1/sessions/exchange`#

Exchange a result token

Exchanges the result token returned by the SDK for the outcome of the flow. Call it from the Tenant's server. A result token can be exchanged once. The webhook for the underlying record remains the source of truth.

Requires an access token

Request body

Field	Type	Required	Description
`result_token`	string	Yes	Result token from the SDK. Example: `rt_sbx_7d2e9f1a3c5b`

Example request

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

Response

200 OK, with a SessionOutcome object.

Example response

{
  "object": "session_outcome",
  "session_id": "ses_8Qw3Ez5Rt2",
  "flow": "payment_confirm",
  "status": "completed",
  "customer_id": "cus_c9T2kXq4Lm",
  "verification_status": null,
  "target": {
    "type": "payment",
    "id": "pay_3As6Df9Gh2"
  },
  "target_status": "completed",
  "terms_decision": null
}

Errors

Status	Error codes
400	parameter_missing
401	authentication_required
422	result_token_invalid
429	rate_limited
500	internal_error

Bank linking#

POST `/v1/customers/{id}/link-tokens`#

Create a Plaid link token

Creates a Plaid link token bound to the customer. Open Plaid with it in the Tenant's application.

Requires an access token
Requires an Idempotency-Key header

Parameters

Name	In	Required	Description
`id`	path	Yes	Customer identifier.

Request body

Field	Type	Required	Description
`platform`	string, one of `web`, `ios`, `android`	Yes	Platform on which Plaid will open: web for web applications and installed web apps, or ios or android for native applications. Example: `web`
`redirect_uri`	string or null	No	Required for web: the Tenant's registered bank-linking return page, to which Plaid returns after a bank's own sign-in. See section 7. Example: `https://app.example.com/bank-link/return`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/customers/{id}/link-tokens" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"platform":"web","redirect_uri":"https://app.example.com/bank-link/return"}'

Response

201 Created, with a LinkToken object.

Example response

{
  "object": "link_token",
  "link_token": "link-sandbox-7c1f2e3d-4b5a-6c7d-8e9f-0a1b2c3d4e5f",
  "expiration": "2026-10-15T18:03:22Z"
}

Errors

Status	Error codes
400	idempotency_key_missing, parameter_invalid, parameter_missing
401	authentication_required
404	not_found
422	account_restricted, customer_not_verified
429	rate_limited
500	internal_error

POST `/v1/customers/{id}/linked-accounts`#

Submit a Plaid public token

Submits the public token returned by Plaid. A2A InstaPay retrieves the account, runs the ownership, account type, RTP and Request for Payment checks, and returns the linked account with status pending. linked_account.verified or linked_account.failed follows.

Requires an access token
Requires an Idempotency-Key header

Parameters

Name	In	Required	Description
`id`	path	Yes	Customer identifier.

Request body

Field	Type	Required	Description
`public_token`	string	Yes	Public token from Plaid. Example: `public-sandbox-5a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d`
`plaid_account_id`	string or null	No	Account selected in Plaid, where the customer had several. Example: `vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/customers/{id}/linked-accounts" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"public_token":"public-sandbox-5a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d","plaid_account_id":"vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D"}'

Response

201 Created, with a LinkedAccount object.

Example response

{
  "id": "la_5Gh2Xw8Pq1",
  "object": "linked_account",
  "customer_id": "cus_c9T2kXq4Lm",
  "status": "pending",
  "institution_name": "First Community Bank",
  "account_type": "checking",
  "account_mask": "6623",
  "capabilities": {
    "withdrawal": false,
    "load": false,
    "pay_by_bank": false
  },
  "withdrawal_hold_until": null,
  "failure_code": null,
  "created_at": "2026-10-15T14:05:41Z",
  "updated_at": "2026-10-15T14:05:41Z",
  "version": 1
}

Errors

Status	Error codes
400	idempotency_key_missing
401	authentication_required
404	not_found
409	linked_account_exists
422	customer_not_verified, link_token_mismatch
429	rate_limited
500	internal_error

GET `/v1/customers/{id}/linked-accounts`#

List linked accounts

Returns the customer's linked accounts, including removed ones, newest first.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Customer identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/customers/{id}/linked-accounts" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a LinkedAccountList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "la_5Gh2Xw8Pq1",
      "object": "linked_account",
      "customer_id": "cus_c9T2kXq4Lm",
      "status": "verified",
      "institution_name": "First Community Bank",
      "account_type": "checking",
      "account_mask": "6623",
      "capabilities": {
        "withdrawal": true,
        "load": true,
        "pay_by_bank": true
      },
      "withdrawal_hold_until": "2026-10-16T14:05:41Z",
      "failure_code": null,
      "created_at": "2026-10-15T14:05:41Z",
      "updated_at": "2026-10-15T14:05:41Z",
      "version": 2
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

DELETE `/v1/customers/{id}/linked-accounts/{linked_account_id}`#

Remove a linked account

Removes the linked account. Pending withdrawals to it are not affected. linked_account.removed follows.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Customer identifier.
`linked_account_id`	path	Yes	Linked account identifier.

Example request

curl -X DELETE "https://sandbox.a2ainstapay.com/v1/customers/{id}/linked-accounts/{linked_account_id}" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a LinkedAccount object.

Example response

{
  "id": "la_5Gh2Xw8Pq1",
  "object": "linked_account",
  "customer_id": "cus_c9T2kXq4Lm",
  "status": "removed",
  "institution_name": "First Community Bank",
  "account_type": "checking",
  "account_mask": "6623",
  "capabilities": {
    "withdrawal": false,
    "load": false,
    "pay_by_bank": false
  },
  "withdrawal_hold_until": null,
  "failure_code": null,
  "created_at": "2026-10-15T14:05:41Z",
  "updated_at": "2026-10-15T14:05:41Z",
  "version": 3
}

Errors

Status	Error codes
401	authentication_required
404	not_found
409	invalid_state
429	rate_limited
500	internal_error

Accounts#

GET `/v1/accounts`#

Find a customer's Digital Account

Returns a list containing the customer's Digital Account.

Requires an access token

Parameters

Name	In	Required	Description
`customer_id`	query	Yes	Customer identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/accounts" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a AccountList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "acct_c3J8vN2Qe6",
      "object": "account",
      "customer_id": "cus_c9T2kXq4Lm",
      "type": "consumer",
      "status": "active",
      "currency": "USD",
      "opened_at": "2026-10-15T14:04:10Z",
      "closed_at": null,
      "updated_at": "2026-10-15T14:04:10Z",
      "version": 1
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
400	parameter_missing
401	authentication_required
429	rate_limited
500	internal_error

GET `/v1/accounts/{id}/balance`#

Retrieve a balance

Returns the ledger, available, earmarked and pending outgoing amounts.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Digital Account identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/accounts/{id}/balance" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a Balance object.

Example response

{
  "object": "balance",
  "account_id": "acct_c3J8vN2Qe6",
  "currency": "USD",
  "ledger": 15000,
  "available": 12000,
  "earmarked": 2000,
  "pending_outgoing": 1000,
  "as_of": "2026-10-15T14:05:41Z"
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

GET `/v1/accounts/{id}/transactions`#

List transactions

Returns the account's transactions, newest first.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Digital Account identifier.
`from`	query	No	Earliest creation time.
`to`	query	No	Latest creation time.
`type`	query	No	Transaction type filter.
`limit`	query	No	Page size, 1 to 100, default 25.
`cursor`	query	No	next_cursor from the previous page.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/accounts/{id}/transactions" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a TransactionList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "txn_2Qa5Ws8Ed1",
      "object": "transaction",
      "account_id": "acct_c3J8vN2Qe6",
      "type": "payment_sent",
      "direction": "debit",
      "amount": 2500,
      "fee_amount": 0,
      "net_amount": 2500,
      "currency": "USD",
      "status": "posted",
      "counterparty": {
        "type": "merchant",
        "customer_id": "cus_m7R5pWz1Hd",
        "display_name": "Riverside Coffee"
      },
      "source_type": "payment",
      "source_id": "pay_3As6Df9Gh2",
      "description": "Order 55120",
      "created_at": "2026-10-15T14:04:10Z",
      "posted_at": "2026-10-15T14:04:10Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
400	parameter_invalid
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

GET `/v1/accounts/{id}/statements`#

List statements

Returns the account's periodic statements, newest first.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Digital Account identifier.
`limit`	query	No	Page size, 1 to 100, default 25.
`cursor`	query	No	next_cursor from the previous page.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/accounts/{id}/statements" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a StatementList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "stmt_7Rf4Tg1Yh6",
      "object": "statement",
      "account_id": "acct_c3J8vN2Qe6",
      "period_start": "2026-09-01",
      "period_end": "2026-09-30",
      "opening_balance": 0,
      "closing_balance": 15000,
      "currency": "USD",
      "download_url": "https://files.example-a2a.test/statements/stmt_7Rf4Tg1Yh6.pdf?sig=redacted",
      "download_url_expires_at": "2026-10-15T14:20:22Z",
      "available_at": "2026-10-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

Loads#

POST `/v1/loads`#

Create a load

Creates a load into the customer's Digital Account by Request for Payment to the customer's linked account. The load is returned with status requires_confirmation and a payment_confirm session. Open the session with the SDK; the customer confirms with the PIN or a passkey. A load that is not confirmed before the session expires fails with failure_code confirmation_expired.

Requires an access token
Requires an Idempotency-Key header

Request body

Field	Type	Required	Description
`customer_id`	string	Yes	Customer identifier. Example: `cus_c9T2kXq4Lm`
`amount`	integer	Yes	Amount in cents. Example: `10000`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/loads" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_c9T2kXq4Lm","amount":10000}'

Response

201 Created, with a Load object.

Example response

{
  "id": "load_7Ty4Ui2Op9",
  "object": "load",
  "customer_id": "cus_c9T2kXq4Lm",
  "account_id": "acct_c3J8vN2Qe6",
  "linked_account_id": "la_5Gh2Xw8Pq1",
  "amount": 10000,
  "currency": "USD",
  "status": "requires_confirmation",
  "failure_code": null,
  "confirmation_session": {
    "id": "ses_3Lm8Nb2Vc6",
    "flow": "payment_confirm",
    "token": "st_sbx_2f9c7a1e5b8d4c3a",
    "expires_at": "2026-10-15T14:08:22Z"
  },
  "created_at": "2026-10-15T14:03:22Z",
  "confirmed_at": null,
  "settled_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
400	idempotency_key_missing
401	authentication_required
403	flow_not_enabled
422	account_restricted, capability_unavailable, customer_not_verified, limit_exceeded, linked_account_required
429	rate_limited
500	internal_error

GET `/v1/loads/{id}`#

Retrieve a load

Returns the load.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Load identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/loads/{id}" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a Load object.

Example response

{
  "id": "load_7Ty4Ui2Op9",
  "object": "load",
  "customer_id": "cus_c9T2kXq4Lm",
  "account_id": "acct_c3J8vN2Qe6",
  "linked_account_id": "la_5Gh2Xw8Pq1",
  "amount": 10000,
  "currency": "USD",
  "status": "requires_confirmation",
  "failure_code": null,
  "created_at": "2026-10-15T14:03:22Z",
  "confirmed_at": null,
  "settled_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

Payment requests#

POST `/v1/payment-requests`#

Create a payment request

Creates a dynamic request with an amount, paid once, or a static request for a collection point, on which the payer enters the amount. Encode qr_payload in a QR code or in the Tenant's Link-to-Pay link.

Requires an access token
Requires an Idempotency-Key header

Request body

Field	Type	Required	Description
`type`	string, one of `dynamic`, `static`	Yes	Request type. Example: `dynamic`
`merchant_customer_id`	string	Yes	Merchant to be paid. Example: `cus_m7R5pWz1Hd`
`amount`	integer or null	No	Amount in cents. Required for dynamic requests. Example: `2500`
`order_reference`	string or null	No	The Tenant's order reference. Example: `ORD-55120`
`collection_point`	CollectionPoint or null	No	Required for static requests.
`expires_in`	integer or null	No	Validity of a dynamic request in seconds, up to 604800 (seven days). Defaults to the Tenant configuration. Example: `900`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/payment-requests" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"type":"dynamic","merchant_customer_id":"cus_m7R5pWz1Hd","amount":2500,"order_reference":"ORD-55120","expires_in":900}'

Response

201 Created, with a PaymentRequest object.

Example response

{
  "id": "pr_1Zx4Cv7Bn5",
  "object": "payment_request",
  "type": "dynamic",
  "merchant_customer_id": "cus_m7R5pWz1Hd",
  "amount": 2500,
  "currency": "USD",
  "order_reference": "ORD-55120",
  "collection_point": null,
  "status": "open",
  "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample",
  "expires_at": "2026-10-15T14:18:22Z",
  "paid_payment_id": null,
  "created_at": "2026-10-15T14:03:22Z",
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
400	idempotency_key_missing, parameter_missing
401	authentication_required
403	flow_not_enabled
422	payee_not_eligible
429	rate_limited
500	internal_error

GET `/v1/payment-requests/{id}`#

Retrieve a payment request

Returns the payment request.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Payment request identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/payment-requests/{id}" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a PaymentRequest object.

Example response

{
  "id": "pr_1Zx4Cv7Bn5",
  "object": "payment_request",
  "type": "dynamic",
  "merchant_customer_id": "cus_m7R5pWz1Hd",
  "amount": 2500,
  "currency": "USD",
  "order_reference": "ORD-55120",
  "collection_point": null,
  "status": "open",
  "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample",
  "expires_at": "2026-10-22T14:03:22Z",
  "paid_payment_id": null,
  "created_at": "2026-10-15T14:03:22Z",
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

POST `/v1/payment-requests/{id}/cancel`#

Cancel a payment request

Cancels an open payment request. payment_request.canceled follows.

Requires an access token
Requires an Idempotency-Key header

Parameters

Name	In	Required	Description
`id`	path	Yes	Payment request identifier.

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/payment-requests/{id}/cancel" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Response

200 OK, with a PaymentRequest object.

Example response

{
  "id": "pr_1Zx4Cv7Bn5",
  "object": "payment_request",
  "type": "dynamic",
  "merchant_customer_id": "cus_m7R5pWz1Hd",
  "amount": 2500,
  "currency": "USD",
  "order_reference": "ORD-55120",
  "collection_point": null,
  "status": "canceled",
  "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample",
  "expires_at": "2026-10-22T14:03:22Z",
  "paid_payment_id": null,
  "created_at": "2026-10-15T14:03:22Z",
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 2
}

Errors

Status	Error codes
400	idempotency_key_missing
401	authentication_required
404	not_found
409	invalid_state
429	rate_limited
500	internal_error

Payments#

POST `/v1/payments`#

Create a payment

Creates a consumer-to-merchant payment from balance or by bank, or a merchant-to-merchant payment from balance. Give either payee_customer_id or qr_payload. The payment is returned with status requires_confirmation and a payment_confirm session for the payer. A payment that is not confirmed before the session expires is canceled.

Requires an access token
Requires an Idempotency-Key header

Request body

Field	Type	Required	Description
`payer_customer_id`	string	Yes	Payer. Example: `cus_c9T2kXq4Lm`
`payee_customer_id`	string or null	No	Merchant to pay. Required unless qr_payload is given. Example: `cus_m7R5pWz1Hd`
`qr_payload`	string or null	No	Payload from a QR code or Link-to-Pay link.
`amount`	integer or null	No	Amount in cents. Required unless a dynamic qr_payload sets it; may be lower than a requested amount but never higher. Example: `2500`
`source`	string, one of `balance`, `bank_account`	Yes	Source of funds. bank_account is pay by bank. Example: `balance`
`order_reference`	string or null	No	The Tenant's order reference. Example: `ORD-55120`
`invoice_reference`	string or null	No	Required for merchant-to-merchant payments.
`description`	string or null	No	Description shown to both parties, up to 140 characters. Example: `Order 55120`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/payments" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"payer_customer_id":"cus_c9T2kXq4Lm","payee_customer_id":"cus_m7R5pWz1Hd","amount":2500,"source":"balance","order_reference":"ORD-55120","description":"Order 55120"}'

Response

201 Created, with a Payment object.

Example response

{
  "id": "pay_3As6Df9Gh2",
  "object": "payment",
  "type": "consumer_to_merchant",
  "source": "balance",
  "payer_customer_id": "cus_c9T2kXq4Lm",
  "payee_customer_id": "cus_m7R5pWz1Hd",
  "payment_request_id": "pr_1Zx4Cv7Bn5",
  "amount": 2500,
  "currency": "USD",
  "fees": [
    {
      "type": "platform",
      "amount": 50,
      "paid_by": "payee"
    }
  ],
  "net_amount": 2450,
  "refunded_amount": 0,
  "status": "requires_confirmation",
  "failure_code": null,
  "order_reference": "ORD-55120",
  "invoice_reference": null,
  "description": "Order 55120",
  "confirmation_session": {
    "id": "ses_8Qw3Ez5Rt2",
    "flow": "payment_confirm",
    "token": "st_sbx_2f9c7a1e5b8d4c3a",
    "expires_at": "2026-10-15T14:08:22Z"
  },
  "created_at": "2026-10-15T14:03:22Z",
  "confirmed_at": null,
  "completed_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
400	idempotency_key_missing, parameter_missing
401	authentication_required
403	flow_not_enabled
422	account_restricted, amount_mismatch, capability_unavailable, customer_not_verified, insufficient_funds, limit_exceeded, payee_not_eligible, payment_request_expired, payment_request_invalid, payment_request_paid
429	rate_limited
500	internal_error

GET `/v1/payments/{id}`#

Retrieve a payment

Returns the payment.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Payment identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/payments/{id}" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a Payment object.

Example response

{
  "id": "pay_3As6Df9Gh2",
  "object": "payment",
  "type": "consumer_to_merchant",
  "source": "balance",
  "payer_customer_id": "cus_c9T2kXq4Lm",
  "payee_customer_id": "cus_m7R5pWz1Hd",
  "payment_request_id": "pr_1Zx4Cv7Bn5",
  "amount": 2500,
  "currency": "USD",
  "fees": [
    {
      "type": "platform",
      "amount": 50,
      "paid_by": "payee"
    }
  ],
  "net_amount": 2450,
  "refunded_amount": 0,
  "status": "requires_confirmation",
  "failure_code": null,
  "order_reference": "ORD-55120",
  "invoice_reference": null,
  "description": "Order 55120",
  "created_at": "2026-10-15T14:03:22Z",
  "confirmed_at": null,
  "completed_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

POST `/v1/payments/{id}/cancel`#

Cancel a payment

Cancels a payment that has not been confirmed. payment.canceled follows.

Requires an access token
Requires an Idempotency-Key header

Parameters

Name	In	Required	Description
`id`	path	Yes	Payment identifier.

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/payments/{id}/cancel" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Response

200 OK, with a Payment object.

Example response

{
  "id": "pay_3As6Df9Gh2",
  "object": "payment",
  "type": "consumer_to_merchant",
  "source": "balance",
  "payer_customer_id": "cus_c9T2kXq4Lm",
  "payee_customer_id": "cus_m7R5pWz1Hd",
  "payment_request_id": "pr_1Zx4Cv7Bn5",
  "amount": 2500,
  "currency": "USD",
  "fees": [
    {
      "type": "platform",
      "amount": 50,
      "paid_by": "payee"
    }
  ],
  "net_amount": 2450,
  "refunded_amount": 0,
  "status": "canceled",
  "failure_code": null,
  "order_reference": "ORD-55120",
  "invoice_reference": null,
  "description": "Order 55120",
  "created_at": "2026-10-15T14:03:22Z",
  "confirmed_at": null,
  "completed_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 2
}

Errors

Status	Error codes
400	idempotency_key_missing
401	authentication_required
404	not_found
409	invalid_state
429	rate_limited
500	internal_error

Withdrawals#

POST `/v1/withdrawals`#

Create a withdrawal

Creates a withdrawal to the customer's own verified linked account. The withdrawal is returned with status requires_confirmation and a payment_confirm session. A withdrawal that is not confirmed before the session expires fails with failure_code confirmation_expired.

Requires an access token
Requires an Idempotency-Key header

Request body

Field	Type	Required	Description
`customer_id`	string	Yes	Customer identifier. Example: `cus_m7R5pWz1Hd`
`amount`	integer	Yes	Amount in cents. Example: `50000`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/withdrawals" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_m7R5pWz1Hd","amount":50000}'

Response

201 Created, with a Withdrawal object.

Example response

{
  "id": "wd_6Mn3Bv8Cx1",
  "object": "withdrawal",
  "customer_id": "cus_m7R5pWz1Hd",
  "account_id": "acct_m4K1sB7Yt9",
  "linked_account_id": "la_9Kj3Hg6Fd2",
  "amount": 50000,
  "currency": "USD",
  "status": "requires_confirmation",
  "failure_code": null,
  "confirmation_session": {
    "id": "ses_9Wq4Er7Ty1",
    "flow": "payment_confirm",
    "token": "st_sbx_2f9c7a1e5b8d4c3a",
    "expires_at": "2026-10-15T14:08:22Z"
  },
  "created_at": "2026-10-15T14:03:22Z",
  "confirmed_at": null,
  "settled_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
400	idempotency_key_missing
401	authentication_required
422	account_restricted, customer_not_verified, insufficient_funds, limit_exceeded, linked_account_required, withdrawal_hold
429	rate_limited
500	internal_error

GET `/v1/withdrawals/{id}`#

Retrieve a withdrawal

Returns the withdrawal.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Withdrawal identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/withdrawals/{id}" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a Withdrawal object.

Example response

{
  "id": "wd_6Mn3Bv8Cx1",
  "object": "withdrawal",
  "customer_id": "cus_m7R5pWz1Hd",
  "account_id": "acct_m4K1sB7Yt9",
  "linked_account_id": "la_9Kj3Hg6Fd2",
  "amount": 50000,
  "currency": "USD",
  "status": "requires_confirmation",
  "failure_code": null,
  "created_at": "2026-10-15T14:03:22Z",
  "confirmed_at": null,
  "settled_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

Refunds#

POST `/v1/refund-requests`#

Request a refund

Requests a refund of a completed payment to the original payer. The refund is returned with status requested and a payment_confirm session for the merchant's authorized user. A refund that is not confirmed before the session expires fails with failure_code confirmation_expired.

Requires an access token
Requires an Idempotency-Key header

Request body

Field	Type	Required	Description
`payment_id`	string	Yes	Payment to refund. Example: `pay_3As6Df9Gh2`
`amount`	integer	Yes	Refund amount in cents. Example: `1000`
`reason`	string, one of `requested_by_customer`, `duplicate`, `goods_not_received`, `other`	Yes	Reason. Example: `requested_by_customer`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/refund-requests" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"payment_id":"pay_3As6Df9Gh2","amount":1000,"reason":"requested_by_customer"}'

Response

201 Created, with a Refund object.

Example response

{
  "id": "rf_4Lk7Jh2Gf9",
  "object": "refund",
  "payment_id": "pay_3As6Df9Gh2",
  "merchant_customer_id": "cus_m7R5pWz1Hd",
  "payer_customer_id": "cus_c9T2kXq4Lm",
  "amount": 1000,
  "currency": "USD",
  "reason": "requested_by_customer",
  "destination": "balance",
  "status": "requested",
  "failure_code": null,
  "confirmation_session": {
    "id": "ses_2Zx8Cv5Bn3",
    "flow": "payment_confirm",
    "token": "st_sbx_2f9c7a1e5b8d4c3a",
    "expires_at": "2026-10-15T14:08:22Z"
  },
  "created_at": "2026-10-15T14:03:22Z",
  "completed_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
400	idempotency_key_missing
401	authentication_required
404	not_found
409	invalid_state
422	account_restricted, refund_exceeds_payment, refund_window_closed
429	rate_limited
500	internal_error

GET `/v1/refund-requests/{id}`#

Retrieve a refund

Returns the refund.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Refund identifier.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/refund-requests/{id}" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a Refund object.

Example response

{
  "id": "rf_4Lk7Jh2Gf9",
  "object": "refund",
  "payment_id": "pay_3As6Df9Gh2",
  "merchant_customer_id": "cus_m7R5pWz1Hd",
  "payer_customer_id": "cus_c9T2kXq4Lm",
  "amount": 1000,
  "currency": "USD",
  "reason": "requested_by_customer",
  "destination": "balance",
  "status": "requested",
  "failure_code": null,
  "created_at": "2026-10-15T14:03:22Z",
  "completed_at": null,
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

Disputes#

POST `/v1/disputes`#

Forward a customer notice

Forwards a customer's notice of an error, an unauthorized transfer or a purchase dispute. Forward every notice within one business day of receiving it, with the time the customer gave it.

Requires an access token
Requires an Idempotency-Key header

Request body

Field	Type	Required	Description
`customer_id`	string	Yes	Customer who gave notice. Example: `cus_c9T2kXq4Lm`
`type`	string, one of `error`, `unauthorized_transfer`, `purchase_dispute`	Yes	Type of notice. Example: `unauthorized_transfer`
`payment_id`	string or null	No	Payment concerned. Example: `pay_3As6Df9Gh2`
`transaction_id`	string or null	No	Transaction concerned, where there is no payment.
`description`	string	Yes	The customer's description, as given, up to 2,000 characters. Example: `I did not make this payment.`
`notice_received_at`	string (date-time)	Yes	When the customer gave notice to the Tenant. Example: `2026-10-15T13:40:00Z`

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/disputes" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":"cus_c9T2kXq4Lm","type":"unauthorized_transfer","payment_id":"pay_3As6Df9Gh2","description":"I did not make this payment.","notice_received_at":"2026-10-15T13:40:00Z"}'

Response

201 Created, with a Dispute object.

Example response

{
  "id": "dsp_9Po2Iu5Yt3",
  "object": "dispute",
  "customer_id": "cus_c9T2kXq4Lm",
  "type": "unauthorized_transfer",
  "payment_id": "pay_3As6Df9Gh2",
  "transaction_id": null,
  "description": "I did not make this payment.",
  "regulation_e": true,
  "notice_received_at": "2026-10-15T13:40:00Z",
  "status": "received",
  "provisional_credit_amount": null,
  "outcome": null,
  "resolved_at": null,
  "created_at": "2026-10-15T14:03:22Z",
  "updated_at": "2026-10-15T14:03:22Z",
  "version": 1
}

Errors

Status	Error codes
400	idempotency_key_missing, parameter_missing
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

GET `/v1/disputes`#

List disputes

Returns disputes, newest first.

Requires an access token

Parameters

Name	In	Required	Description
`customer_id`	query	No	Filter by customer.
`status`	query	No	Filter by status.
`limit`	query	No	Page size, 1 to 100, default 25.
`cursor`	query	No	next_cursor from the previous page.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/disputes" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a DisputeList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "dsp_9Po2Iu5Yt3",
      "object": "dispute",
      "customer_id": "cus_c9T2kXq4Lm",
      "type": "unauthorized_transfer",
      "payment_id": "pay_3As6Df9Gh2",
      "transaction_id": null,
      "description": "I did not make this payment.",
      "regulation_e": true,
      "notice_received_at": "2026-10-15T13:40:00Z",
      "status": "received",
      "provisional_credit_amount": null,
      "outcome": null,
      "resolved_at": null,
      "created_at": "2026-10-15T14:03:22Z",
      "updated_at": "2026-10-15T14:03:22Z",
      "version": 1
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
400	parameter_invalid
401	authentication_required
429	rate_limited
500	internal_error

Webhook events#

GET `/v1/webhook-events`#

List webhook events

Returns events with their delivery status, newest first. Events are kept for 30 days.

Requires an access token

Parameters

Name	In	Required	Description
`type`	query	No	Filter by event type.
`delivery_status`	query	No	Filter by delivery status.
`from`	query	No	Earliest event time.
`limit`	query	No	Page size, 1 to 100, default 25.
`cursor`	query	No	next_cursor from the previous page.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/webhook-events" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a WebhookEventList object.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "evt_18Uj8Ik2Ol4",
      "object": "event",
      "type": "payment.completed",
      "api_version": "v1",
      "environment": "sandbox",
      "created_at": "2026-10-15T14:04:10Z",
      "data": {
        "object": {
          "id": "pay_3As6Df9Gh2",
          "object": "payment",
          "type": "consumer_to_merchant",
          "source": "balance",
          "payer_customer_id": "cus_c9T2kXq4Lm",
          "payee_customer_id": "cus_m7R5pWz1Hd",
          "payment_request_id": "pr_1Zx4Cv7Bn5",
          "amount": 2500,
          "currency": "USD",
          "fees": [
            {
              "type": "platform",
              "amount": 50,
              "paid_by": "payee"
            }
          ],
          "net_amount": 2450,
          "refunded_amount": 0,
          "status": "completed",
          "failure_code": null,
          "order_reference": "ORD-55120",
          "invoice_reference": null,
          "description": "Order 55120",
          "created_at": "2026-10-15T14:03:22Z",
          "confirmed_at": "2026-10-15T14:04:10Z",
          "completed_at": "2026-10-15T14:04:10Z",
          "updated_at": "2026-10-15T14:04:10Z",
          "version": 2
        },
        "previous_attributes": {
          "status": "requires_confirmation"
        }
      },
      "delivery": {
        "status": "delivered",
        "attempts": 1,
        "last_attempt_at": "2026-10-15T14:04:10Z",
        "last_response_status": 200,
        "next_attempt_at": null
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errors

Status	Error codes
400	parameter_invalid
401	authentication_required
429	rate_limited
500	internal_error

POST `/v1/webhook-events/{id}/resend`#

Resend a webhook event

Queues the event for delivery again with a fresh signature timestamp. The event identifier is unchanged.

Requires an access token

Parameters

Name	In	Required	Description
`id`	path	Yes	Event identifier.

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/webhook-events/{id}/resend" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Response

202 Accepted, with a WebhookEvent object.

Example response

{
  "id": "evt_18Uj8Ik2Ol4",
  "object": "event",
  "type": "payment.completed",
  "api_version": "v1",
  "environment": "sandbox",
  "created_at": "2026-10-15T14:04:10Z",
  "data": {
    "object": {
      "id": "pay_3As6Df9Gh2",
      "object": "payment",
      "type": "consumer_to_merchant",
      "source": "balance",
      "payer_customer_id": "cus_c9T2kXq4Lm",
      "payee_customer_id": "cus_m7R5pWz1Hd",
      "payment_request_id": "pr_1Zx4Cv7Bn5",
      "amount": 2500,
      "currency": "USD",
      "fees": [
        {
          "type": "platform",
          "amount": 50,
          "paid_by": "payee"
        }
      ],
      "net_amount": 2450,
      "refunded_amount": 0,
      "status": "completed",
      "failure_code": null,
      "order_reference": "ORD-55120",
      "invoice_reference": null,
      "description": "Order 55120",
      "created_at": "2026-10-15T14:03:22Z",
      "confirmed_at": "2026-10-15T14:04:10Z",
      "completed_at": "2026-10-15T14:04:10Z",
      "updated_at": "2026-10-15T14:04:10Z",
      "version": 2
    },
    "previous_attributes": {
      "status": "requires_confirmation"
    }
  },
  "delivery": {
    "status": "pending",
    "attempts": 3,
    "last_attempt_at": "2026-10-15T14:05:41Z",
    "last_response_status": 500,
    "next_attempt_at": "2026-10-15T14:06:00Z"
  }
}

Errors

Status	Error codes
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

Reports#

GET `/v1/reports/reconciliation`#

Retrieve the daily reconciliation report

Returns the summary for a business date and a time-limited address of the posting-level file. Reports are available from 06:00 Eastern Time the next day.

Requires an access token

Parameters

Name	In	Required	Description
`date`	query	Yes	Business date (Eastern Time), YYYY-MM-DD.

Example request

curl -X GET "https://sandbox.a2ainstapay.com/v1/reports/reconciliation" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN"

Response

200 OK, with a ReconciliationReport object.

Example response

{
  "object": "reconciliation_report",
  "date": "2026-10-14",
  "account_structure": "dedicated_fbo",
  "currency": "USD",
  "opening_balance": 1250000,
  "closing_balance": 1301800,
  "totals": {
    "loads": 250000,
    "payments": 410000,
    "withdrawals": 180000,
    "refunds": 12000,
    "fees": 8200,
    "adjustments": 0
  },
  "fee_clearing_swept": 8200,
  "postings_count": 1342,
  "file": {
    "format": "csv",
    "download_url": "https://files.example-a2a.test/recon/2026-10-14.csv?sig=redacted",
    "expires_at": "2026-10-15T14:20:22Z"
  },
  "generated_at": "2026-10-15T06:00:00Z"
}

Errors

Status	Error codes
400	parameter_missing
401	authentication_required
404	not_found
429	rate_limited
500	internal_error

Sandbox#

POST `/v1/sandbox/simulate/{event}`#

Simulate an event (sandbox only)

Moves a sandbox record as if the bank, a provider or a reviewer had acted, and sends the resulting webhook.

Requires an access token
Sandbox only

Parameters

Name	In	Required	Description
`event`	path	Yes	Event to simulate. See the list in section 11.

Request body

Field	Type	Required	Description
`object_id`	string	Yes	Record to act on. Example: `pay_3As6Df9Gh2`
`failure_code`	string or null	No	For failure events, the failure code to apply.

Example request

curl -X POST "https://sandbox.a2ainstapay.com/v1/sandbox/simulate/{event}" \
  -H "Authorization: Bearer $A2A_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"object_id":"pay_3As6Df9Gh2"}'

Response

202 Accepted, with a SimulationResult object.

Example response

{
  "object": "simulation",
  "event": "payment.completed",
  "object_id": "pay_3As6Df9Gh2",
  "status": "accepted"
}

Errors

Status	Error codes
401	authentication_required
403	sandbox_only
404	not_found
409	invalid_state
429	rate_limited
500	internal_error

Objects#

Error#

Field	Type	Required	Description
`code`	string	Yes	Stable error code from the error catalog. Code against this value. Example: `limit_exceeded`
`message`	string	Yes	Readable description for logs and support. Do not show it to customers or parse it. Example: `The payment exceeds the daily amount limit for this customer.`
`param`	string or null	No	The request field the error relates to, where there is one. Example: `amount`
`request_id`	string	Yes	Identifier of the request, also returned in the A2A-Request-Id header. Quote it to support. Example: `req_4Hk8Lm2Np6`
`details`	object or null	No	Additional structured information for some errors, described in the catalog.

Token#

Field	Type	Required	Description
`access_token`	string	Yes	Bearer token for the Authorization header. Example: `at_sbx_6c1f0e9b2a7d4e8f9a0b1c2d3e4f5a6b`
`token_type`	string, one of `Bearer`	Yes	Always Bearer. Example: `Bearer`
`expires_in`	integer	Yes	Lifetime of the token in seconds. Example: `900`
`scope`	string	Yes	Scope granted to the client. Example: `tenant`

ConfirmationSession#

Field	Type	Required	Description
`id`	string	Yes	Session identifier. Example: `ses_8Qw3Ez5Rt2`
`flow`	string, one of `onboarding`, `payment_confirm`, `pin_reset`, `contact_change`, `terms_acceptance`	Yes	Hosted flow the session opens. Example: `payment_confirm`
`token`	string	No	Single-use session token to pass to the SDK. Treat it as a secret and do not log it. Example: `st_sbx_2f9c7a1e5b8d4c3a`
`expires_at`	string (date-time)	Yes	Time after which the token can no longer be opened. Example: `2026-10-15T14:08:22Z`

Target#

Field	Type	Required	Description
`type`	string, one of `payment`, `load`, `withdrawal`, `refund`	Yes	Type of record the customer confirms. Example: `payment`
`id`	string	Yes	Identifier of that record. Example: `pay_3As6Df9Gh2`

Session#

Field	Type	Required	Description
`id`	string	Yes	Session identifier. Example: `ses_8Qw3Ez5Rt2`
`object`	string, one of `session`	Yes	Object type. Example: `session`
`flow`	string, one of `onboarding`, `payment_confirm`, `pin_reset`, `contact_change`, `terms_acceptance`	Yes	Hosted flow. Example: `payment_confirm`
`customer_id`	string	Yes	Customer the session is bound to. Example: `cus_c9T2kXq4Lm`
`target`	Target or null	No	Record to confirm. Present for payment_confirm only.
`status`	string, one of `created`, `completed`, `canceled`, `expired`	Yes	Session status. Example: `created`
`token`	string or null	No	Single-use session token. Returned only when the session is created. Example: `st_sbx_2f9c7a1e5b8d4c3a`
`return_url`	string or null	No	Registered return address used for redirects on mobile browsers. Example: `https://app.example.com/a2a/return`
`expires_at`	string (date-time)	Yes	Expiry of the session token. Example: `2026-10-15T14:08:22Z`
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:03:22Z`

SessionOutcome#

Field	Type	Required	Description
`object`	string, one of `session_outcome`	Yes	Object type. Example: `session_outcome`
`session_id`	string	Yes	Session identifier. Example: `ses_8Qw3Ez5Rt2`
`flow`	string, one of `onboarding`, `payment_confirm`, `pin_reset`, `contact_change`, `terms_acceptance`	Yes	Hosted flow. Example: `payment_confirm`
`status`	string, one of `completed`, `canceled`, `expired`	Yes	How the customer left the flow. Example: `completed`
`customer_id`	string	Yes	Customer identifier. Example: `cus_c9T2kXq4Lm`
`verification_status`	string or null	No	For onboarding: the customer's verification status when the flow ended.
`target`	Target or null	No	For payment_confirm: the confirmed record.
`target_status`	string or null	No	For payment_confirm: status of the confirmed record after confirmation, for example processing or completed. Example: `completed`
`terms_decision`	string or null	No	For terms_acceptance: the customer's decision.

Verification#

Field	Type	Required	Description
`status`	string, one of `created`, `pending`, `in_review`, `approved`, `rejected`	Yes	Verification status. See the Tenant Integration Specification, section 9. Example: `approved`
`updated_at`	string (date-time)	Yes	Time of the last status change. Example: `2026-10-15T14:04:10Z`
`retry_available_at`	string or null	No	For rejected customers: when a new application may be started.

BusinessProfile#

Field	Type	Required	Description
`legal_name`	string or null	No	Verified legal name. Present once captured on the hosted screen. Example: `Riverside Coffee Co LLC`
`trading_name`	string or null	No	Trading name shown to payers. Example: `Riverside Coffee`
`industry`	string or null	No	Industry from the program's industry list. Example: `Coffee shops and cafes`
`owners_status`	string, one of `not_started`, `pending`, `complete`	Yes	Progress of owner and control person verification. Example: `complete`

Customer#

Field	Type	Required	Description
`id`	string	Yes	Customer identifier. Example: `cus_c9T2kXq4Lm`
`object`	string, one of `customer`	Yes	Object type. Example: `customer`
`type`	string, one of `individual`, `business`	Yes	Consumer (individual) or merchant (business). Example: `individual`
`external_ref`	string	Yes	The Tenant's own reference for the customer, unique within the Tenant. Example: `member-10482`
`email`	string	Yes	E-mail address supplied by the Tenant, or as changed on the contact_change screen. Example: `member@example.com`
`mobile_number_last4`	string	Yes	Last four digits of the verified mobile number. Example: `4821`
`business`	BusinessProfile or null	No	Business details. Present for business customers only.
`verification`	Verification	Yes	Verification status.
`account_id`	string or null	No	Digital Account identifier. Present once the customer is approved. Example: `acct_c3J8vN2Qe6`
`pin_locked`	boolean	Yes	True while the PIN is locked after failed attempts. Example: `false`
`onboarding_session`	ConfirmationSession or null	No	Onboarding session. Returned only when the customer is created.
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:03:22Z`
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:04:10Z`
`version`	integer	Yes	Increases by one on every change. Use it to discard out-of-date webhook events. Example: `3`

Owner#

Field	Type	Required	Description
`id`	string	Yes	Owner identifier. Example: `own_2Lp9Vc4Mz7`
`object`	string, one of `owner`	Yes	Object type. Example: `owner`
`customer_id`	string	Yes	Business customer the person belongs to. Example: `cus_m7R5pWz1Hd`
`name`	string	Yes	Name of the person as entered by the merchant. Example: `Jordan Ellis`
`role`	string, one of `owner`, `control_person`, `owner_and_control_person`	Yes	Role in the business. Example: `owner_and_control_person`
`ownership_percent`	integer or null	No	Ownership percentage, for owners. Example: `60`
`verification_status`	string, one of `invited`, `pending`, `in_review`, `approved`, `rejected`	Yes	Verification status of the person. Example: `approved`
`invited_at`	string or null	No	When a verification link was sent to the person. Example: `2026-10-15T14:03:22Z`
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:04:10Z`

DocumentAcceptance#

Field	Type	Required	Description
`id`	string	Yes	Acceptance record identifier. Example: `dacc_3Nb6Vc9Xz2`
`object`	string, one of `document_acceptance`	Yes	Object type. Example: `document_acceptance`
`customer_id`	string	Yes	Customer identifier. Example: `cus_c9T2kXq4Lm`
`document_type`	string, one of `digital_account_terms`, `esign_consent`, `privacy_notice`, `cip_notice`, `merchant_services_agreement`, `acceptable_use_policy`	Yes	Customer document. Example: `digital_account_terms`
`version`	string	Yes	Document version accepted. Example: `2026.10`
`status`	string, one of `accepted`, `superseded`, `pending_acceptance`	Yes	Status of the acceptance. pending_acceptance means a new version awaits acceptance on the terms_acceptance screen. Example: `accepted`
`accepted_at`	string or null	No	Time of acceptance. Example: `2026-10-15T14:03:22Z`
`channel`	string or null	No	Hosted flow in which the document was accepted. Example: `onboarding`

LinkToken#

Field	Type	Required	Description
`object`	string, one of `link_token`	Yes	Object type. Example: `link_token`
`link_token`	string	Yes	Plaid link token to open Plaid in the Tenant's application. Example: `link-sandbox-7c1f2e3d-4b5a-6c7d-8e9f-0a1b2c3d4e5f`
`expiration`	string (date-time)	Yes	Expiry of the link token. Example: `2026-10-15T18:03:22Z`

Capabilities#

Field	Type	Required	Description
`withdrawal`	boolean	Yes	The bank can receive RTP credit transfers, so withdrawals are available. Example: `true`
`load`	boolean	Yes	The bank can receive a Request for Payment, so loads are available. Example: `true`
`pay_by_bank`	boolean	Yes	The bank can receive a Request for Payment, so pay by bank is available. Example: `true`

LinkedAccount#

Field	Type	Required	Description
`id`	string	Yes	Linked account identifier. Example: `la_5Gh2Xw8Pq1`
`object`	string, one of `linked_account`	Yes	Object type. Example: `linked_account`
`customer_id`	string	Yes	Customer identifier. Example: `cus_c9T2kXq4Lm`
`status`	string, one of `pending`, `held_for_review`, `verified`, `failed`, `removed`	Yes	Status of the link. Example: `verified`
`institution_name`	string	Yes	Name of the bank. Example: `First Community Bank`
`account_type`	string, one of `checking`, `savings`	Yes	Account type. Example: `checking`
`account_mask`	string	Yes	Last four digits of the account number. Example: `6623`
`capabilities`	Capabilities	Yes	What the account can be used for. All false until verified.
`withdrawal_hold_until`	string or null	No	Withdrawals to a newly linked account are held until this time. Example: `2026-10-16T14:05:41Z`
`failure_code`	string or null	No	Reason for a failed link.
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:05:41Z`
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:05:41Z`
`version`	integer	Yes	Increases by one on every change. Example: `2`

Account#

Field	Type	Required	Description
`id`	string	Yes	Digital Account identifier. Example: `acct_c3J8vN2Qe6`
`object`	string, one of `account`	Yes	Object type. Example: `account`
`customer_id`	string	Yes	Customer identifier. Example: `cus_c9T2kXq4Lm`
`type`	string, one of `consumer`, `merchant`	Yes	Account type. Example: `consumer`
`status`	string, one of `active`, `suspended`, `dormant`, `closing`, `closed`	Yes	Account status. Example: `active`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`opened_at`	string (date-time)	Yes	Opening time. Example: `2026-10-15T14:04:10Z`
`closed_at`	string or null	No	Closing time.
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:04:10Z`
`version`	integer	Yes	Increases by one on every change. Example: `1`

Balance#

Field	Type	Required	Description
`object`	string, one of `balance`	Yes	Object type. Example: `balance`
`account_id`	string	Yes	Digital Account identifier. Example: `acct_c3J8vN2Qe6`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`ledger`	integer	Yes	Total balance in cents. Example: `15000`
`available`	integer	Yes	Amount that can be spent or withdrawn now: ledger less earmarked and pending outgoing amounts. Example: `12000`
`earmarked`	integer	Yes	Amount reserved for open refunds or disputes. Example: `2000`
`pending_outgoing`	integer	Yes	Amount reserved for payments and withdrawals in progress. Example: `1000`
`as_of`	string (date-time)	Yes	Time of the balance. Example: `2026-10-15T14:05:41Z`

Counterparty#

Field	Type	Required	Description
`type`	string, one of `consumer`, `merchant`, `bank_account`	Yes	Counterparty type. Example: `merchant`
`customer_id`	string or null	No	Counterparty customer identifier, for consumers and merchants of the same Tenant. Example: `cus_m7R5pWz1Hd`
`display_name`	string	Yes	Name to show in the transaction history. Example: `Riverside Coffee`

Transaction#

Field	Type	Required	Description
`id`	string	Yes	Transaction identifier. Example: `txn_2Qa5Ws8Ed1`
`object`	string, one of `transaction`	Yes	Object type. Example: `transaction`
`account_id`	string	Yes	Digital Account identifier. Example: `acct_c3J8vN2Qe6`
`type`	string, one of `load`, `payment_sent`, `payment_received`, `withdrawal`, `refund_sent`, `refund_received`, `dispute_credit`, `dispute_reversal`, `adjustment`	Yes	Transaction type. Example: `payment_sent`
`direction`	string, one of `credit`, `debit`	Yes	Effect on the account. Example: `debit`
`amount`	integer	Yes	Gross amount in cents. Example: `2500`
`fee_amount`	integer	Yes	Fees deducted from this account for the transaction, in cents. Example: `0`
`net_amount`	integer	Yes	Amount credited or debited after fees, in cents. Example: `2500`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`status`	string, one of `pending`, `posted`, `reversed`	Yes	Posting status. Example: `posted`
`counterparty`	Counterparty or null	No	The other party.
`source_type`	string, one of `load`, `payment`, `withdrawal`, `refund`, `dispute`, `adjustment`	Yes	Record that created the transaction. Example: `payment`
`source_id`	string	Yes	Identifier of that record. Example: `pay_3As6Df9Gh2`
`description`	string or null	No	Description shown to the customer. Example: `Order 55120`
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:04:10Z`
`posted_at`	string or null	No	Posting time. Example: `2026-10-15T14:04:10Z`

Statement#

Field	Type	Required	Description
`id`	string	Yes	Statement identifier. Example: `stmt_7Rf4Tg1Yh6`
`object`	string, one of `statement`	Yes	Object type. Example: `statement`
`account_id`	string	Yes	Digital Account identifier. Example: `acct_c3J8vN2Qe6`
`period_start`	string (date)	Yes	First day of the period. Example: `2026-09-01`
`period_end`	string (date)	Yes	Last day of the period. Example: `2026-09-30`
`opening_balance`	integer	Yes	Opening balance in cents. Example: `0`
`closing_balance`	integer	Yes	Closing balance in cents. Example: `15000`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`download_url`	string	Yes	Time-limited address of the PDF statement. Request the statement again for a fresh address. Example: `https://files.example-a2a.test/statements/stmt_7Rf4Tg1Yh6.pdf?sig=redacted`
`download_url_expires_at`	string (date-time)	Yes	Expiry of the download address. Example: `2026-10-15T14:20:22Z`
`available_at`	string (date-time)	Yes	When the statement became available. Example: `2026-10-01T09:00:00Z`

Load#

Field	Type	Required	Description
`id`	string	Yes	Load identifier. Example: `load_7Ty4Ui2Op9`
`object`	string, one of `load`	Yes	Object type. Example: `load`
`customer_id`	string	Yes	Customer identifier. Example: `cus_c9T2kXq4Lm`
`account_id`	string	Yes	Digital Account credited. Example: `acct_c3J8vN2Qe6`
`linked_account_id`	string	Yes	Bank account the Request for Payment is sent to. Example: `la_5Gh2Xw8Pq1`
`amount`	integer	Yes	Amount in cents. Example: `10000`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`status`	string, one of `requires_confirmation`, `processing`, `settled`, `failed`	Yes	Load status. Example: `requires_confirmation`
`failure_code`	string or null	No	Reason for a failed load.
`confirmation_session`	ConfirmationSession or null	No	payment_confirm session. Returned only when the load is created.
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:03:22Z`
`confirmed_at`	string or null	No	Time the customer confirmed.
`settled_at`	string or null	No	Time the funds were credited.
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:03:22Z`
`version`	integer	Yes	Increases by one on every change. Example: `1`

CollectionPoint#

Field	Type	Required	Description
`reference`	string	Yes	The Tenant's reference for the store, counter or machine. Example: `store-12-counter-2`
`name`	string	Yes	Name shown to the payer on the confirmation screen. Example: `Riverside Coffee, Main St counter 2`

PaymentRequest#

Field	Type	Required	Description
`id`	string	Yes	Payment request identifier. Example: `pr_1Zx4Cv7Bn5`
`object`	string, one of `payment_request`	Yes	Object type. Example: `payment_request`
`type`	string, one of `dynamic`, `static`	Yes	dynamic carries an amount and is paid once; static identifies a collection point and the payer enters the amount. Example: `dynamic`
`merchant_customer_id`	string	Yes	Merchant to be paid. Example: `cus_m7R5pWz1Hd`
`amount`	integer or null	No	Requested amount in cents. Present for dynamic requests. Example: `2500`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`order_reference`	string or null	No	The Tenant's order reference. Example: `ORD-55120`
`collection_point`	CollectionPoint or null	No	Collection point. Present for static requests.
`status`	string, one of `open`, `paid`, `expired`, `canceled`	Yes	Request status. A static request stays open until canceled. Example: `open`
`qr_payload`	string	Yes	Payload signed by A2A InstaPay, to encode in the QR code or in the Tenant's Link-to-Pay link. Example: `A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample`
`expires_at`	string or null	No	Expiry of a dynamic request. Example: `2026-10-22T14:03:22Z`
`paid_payment_id`	string or null	No	Payment that paid a dynamic request.
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:03:22Z`
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:03:22Z`
`version`	integer	Yes	Increases by one on every change. Example: `1`

Fee#

Field	Type	Required	Description
`type`	string, one of `platform`, `tenant`	Yes	Fee type. Example: `platform`
`amount`	integer	Yes	Fee in cents. Example: `50`
`paid_by`	string, one of `payer`, `payee`	Yes	Party whose amount the fee is taken from. Example: `payee`

Payment#

Field	Type	Required	Description
`id`	string	Yes	Payment identifier. Example: `pay_3As6Df9Gh2`
`object`	string, one of `payment`	Yes	Object type. Example: `payment`
`type`	string, one of `consumer_to_merchant`, `merchant_to_merchant`	Yes	Payment type. Example: `consumer_to_merchant`
`source`	string, one of `balance`, `bank_account`	Yes	Source of funds. Example: `balance`
`payer_customer_id`	string	Yes	Payer. Example: `cus_c9T2kXq4Lm`
`payee_customer_id`	string	Yes	Merchant paid. Example: `cus_m7R5pWz1Hd`
`payment_request_id`	string or null	No	Payment request paid, where the payment came from a QR code or link. Example: `pr_1Zx4Cv7Bn5`
`amount`	integer	Yes	Amount in cents. Example: `2500`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`fees`	array of Fee	Yes	Fees on the payment.
`net_amount`	integer	Yes	Amount credited to the merchant after fees, in cents. Example: `2450`
`refunded_amount`	integer	Yes	Total refunded so far, in cents. Example: `0`
`status`	string, one of `requires_confirmation`, `processing`, `completed`, `failed`, `canceled`, `refunded`, `partially_refunded`	Yes	Payment status. Example: `requires_confirmation`
`failure_code`	string or null	No	Reason for a failed payment.
`order_reference`	string or null	No	The Tenant's order reference. Example: `ORD-55120`
`invoice_reference`	string or null	No	Invoice reference. Required for merchant-to-merchant payments.
`description`	string or null	No	Description shown to both parties. Example: `Order 55120`
`confirmation_session`	ConfirmationSession or null	No	payment_confirm session. Returned only when the payment is created.
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:03:22Z`
`confirmed_at`	string or null	No	Time the payer confirmed.
`completed_at`	string or null	No	Time the merchant was credited.
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:03:22Z`
`version`	integer	Yes	Increases by one on every change. Example: `1`

Withdrawal#

Field	Type	Required	Description
`id`	string	Yes	Withdrawal identifier. Example: `wd_6Mn3Bv8Cx1`
`object`	string, one of `withdrawal`	Yes	Object type. Example: `withdrawal`
`customer_id`	string	Yes	Customer identifier. Example: `cus_m7R5pWz1Hd`
`account_id`	string	Yes	Digital Account debited. Example: `acct_m4K1sB7Yt9`
`linked_account_id`	string	Yes	Bank account credited. Example: `la_9Kj3Hg6Fd2`
`amount`	integer	Yes	Amount in cents. Example: `50000`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`status`	string, one of `requires_confirmation`, `processing`, `settled`, `failed`	Yes	Withdrawal status. Example: `requires_confirmation`
`failure_code`	string or null	No	Reason for a failed withdrawal. A failed withdrawal releases the reserved amount.
`confirmation_session`	ConfirmationSession or null	No	payment_confirm session. Returned only when the withdrawal is created.
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:03:22Z`
`confirmed_at`	string or null	No	Time the customer confirmed.
`settled_at`	string or null	No	Time the transfer was final.
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:03:22Z`
`version`	integer	Yes	Increases by one on every change. Example: `1`

Refund#

Field	Type	Required	Description
`id`	string	Yes	Refund identifier. Example: `rf_4Lk7Jh2Gf9`
`object`	string, one of `refund`	Yes	Object type. Example: `refund`
`payment_id`	string	Yes	Payment refunded. Example: `pay_3As6Df9Gh2`
`merchant_customer_id`	string	Yes	Merchant issuing the refund. Example: `cus_m7R5pWz1Hd`
`payer_customer_id`	string	Yes	Consumer refunded. Example: `cus_c9T2kXq4Lm`
`amount`	integer	Yes	Refund amount in cents. Example: `1000`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`reason`	string, one of `requested_by_customer`, `duplicate`, `goods_not_received`, `other`	Yes	Reason given by the merchant. Example: `requested_by_customer`
`destination`	string, one of `balance`, `bank_account`	Yes	Where the refund is sent: the consumer's Digital Account, or the consumer's linked account for pay by bank. Example: `balance`
`status`	string, one of `requested`, `pending_funds`, `processing`, `completed`, `failed`	Yes	Refund status. Example: `requested`
`failure_code`	string or null	No	Reason for a failed refund.
`confirmation_session`	ConfirmationSession or null	No	payment_confirm session for the merchant. Returned only when the refund is requested.
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:03:22Z`
`completed_at`	string or null	No	Time the refund was applied.
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:03:22Z`
`version`	integer	Yes	Increases by one on every change. Example: `1`

Dispute#

Field	Type	Required	Description
`id`	string	Yes	Dispute identifier. Example: `dsp_9Po2Iu5Yt3`
`object`	string, one of `dispute`	Yes	Object type. Example: `dispute`
`customer_id`	string	Yes	Customer who gave notice. Example: `cus_c9T2kXq4Lm`
`type`	string, one of `error`, `unauthorized_transfer`, `purchase_dispute`	Yes	Type of notice. Example: `unauthorized_transfer`
`payment_id`	string or null	No	Payment concerned, where there is one. Example: `pay_3As6Df9Gh2`
`transaction_id`	string or null	No	Transaction concerned, where there is one.
`description`	string	Yes	The customer's description, as given. Example: `I did not make this payment.`
`regulation_e`	boolean	Yes	True where the notice is handled under Regulation E error resolution. Example: `true`
`notice_received_at`	string (date-time)	Yes	When the customer first gave notice, to the Tenant or to A2A InstaPay. Example: `2026-10-15T13:40:00Z`
`status`	string, one of `received`, `investigating`, `provisional_credit`, `resolved`, `closed`	Yes	Dispute status. Example: `received`
`provisional_credit_amount`	integer or null	No	Provisional credit given, in cents.
`outcome`	string or null	No	Result of the investigation.
`resolved_at`	string or null	No	Time the investigation was completed.
`created_at`	string (date-time)	Yes	Creation time. Example: `2026-10-15T14:03:22Z`
`updated_at`	string (date-time)	Yes	Time of the last change. Example: `2026-10-15T14:03:22Z`
`version`	integer	Yes	Increases by one on every change. Example: `1`

EventData#

Field	Type	Required	Description
`object`	object	Yes	The full object after the change, in the same form the API returns.
`previous_attributes`	object or null	No	Values of the changed fields before the change.

Event#

Field	Type	Required	Description
`id`	string	Yes	Unique event identifier. Use it to discard duplicate deliveries. Example: `evt_5Ujm8Ik2Ol4`
`object`	string, one of `event`	Yes	Object type. Example: `event`
`type`	string	Yes	Event type, from the event catalog. Example: `payment.completed`
`api_version`	string, one of `v1`	Yes	API version of the object in data. Example: `v1`
`environment`	string, one of `sandbox`, `production`	Yes	Environment that sent the event. Example: `sandbox`
`created_at`	string (date-time)	Yes	Time of the change. Example: `2026-10-15T14:04:10Z`
`data`	EventData	Yes	The changed object.

Delivery#

Field	Type	Required	Description
`status`	string, one of `pending`, `delivered`, `retrying`, `failed`	Yes	Delivery status to the Tenant's endpoint. Example: `delivered`
`attempts`	integer	Yes	Number of delivery attempts. Example: `1`
`last_attempt_at`	string or null	No	Time of the last attempt. Example: `2026-10-15T14:04:10Z`
`last_response_status`	integer or null	No	HTTP status returned by the Tenant on the last attempt. Example: `200`
`next_attempt_at`	string or null	No	Time of the next attempt, while retrying.

WebhookEvent#

Field	Type	Required	Description
`id`	string	Yes	Unique event identifier. Use it to discard duplicate deliveries. Example: `evt_5Ujm8Ik2Ol4`
`object`	string, one of `event`	Yes	Object type. Example: `event`
`type`	string	Yes	Event type, from the event catalog. Example: `payment.completed`
`api_version`	string, one of `v1`	Yes	API version of the object in data. Example: `v1`
`environment`	string, one of `sandbox`, `production`	Yes	Environment that sent the event. Example: `sandbox`
`created_at`	string (date-time)	Yes	Time of the change. Example: `2026-10-15T14:04:10Z`
`data`	EventData	Yes	The changed object.
`delivery`	Delivery	Yes	Delivery record.

ReconTotals#

Field	Type	Required	Description
`loads`	integer	Yes	Total loads credited, in cents. Example: `250000`
`payments`	integer	Yes	Total payments between Digital Accounts and by bank, in cents. Example: `410000`
`withdrawals`	integer	Yes	Total withdrawals, in cents. Example: `180000`
`refunds`	integer	Yes	Total refunds, in cents. Example: `12000`
`fees`	integer	Yes	Total fees posted to the fee clearing position, in cents. Example: `8200`
`adjustments`	integer	Yes	Total dispute credits, reversals and other adjustments, in cents. Example: `0`

FileLink#

Field	Type	Required	Description
`format`	string, one of `csv`	Yes	File format. Example: `csv`
`download_url`	string	Yes	Time-limited address of the file. Example: `https://files.example-a2a.test/recon/2026-10-14.csv?sig=redacted`
`expires_at`	string (date-time)	Yes	Expiry of the address. Example: `2026-10-15T14:20:22Z`

ReconciliationReport#

Field	Type	Required	Description
`object`	string, one of `reconciliation_report`	Yes	Object type. Example: `reconciliation_report`
`date`	string (date)	Yes	Business date (Eastern Time). Example: `2026-10-14`
`account_structure`	string, one of `dedicated_fbo`, `tenant_scheme`	Yes	Account structure of the Tenant. Example: `dedicated_fbo`
`currency`	string, one of `USD`	Yes	Currency. Example: `USD`
`opening_balance`	integer	Yes	Sum of the Tenant's customer balances at the start of the day, in cents. Example: `1250000`
`closing_balance`	integer	Yes	Sum of the Tenant's customer balances at the end of the day, in cents. Example: `1301800`
`totals`	ReconTotals	Yes	Totals by movement type.
`fee_clearing_swept`	integer	Yes	Fees swept from the fee clearing position to operating accounts during the day, in cents. Example: `8200`
`postings_count`	integer	Yes	Number of postings in the file. Example: `1342`
`file`	FileLink	Yes	The posting-level file.
`generated_at`	string (date-time)	Yes	Time the report was produced. Example: `2026-10-15T06:00:00Z`

SimulationResult#

Field	Type	Required	Description
`object`	string, one of `simulation`	Yes	Object type. Example: `simulation`
`event`	string	Yes	Simulated event. Example: `payment.completed`
`object_id`	string	Yes	Record the simulation acted on. Example: `pay_3As6Df9Gh2`
`status`	string, one of `accepted`	Yes	The simulation was accepted; the resulting webhook follows. Example: `accepted`

Tenant API v1.1

Errors#

Authentication#

POST /oauth/token#

Request body

Response

Errors

Customers#

POST /v1/customers#

Request body

Response

Errors

GET /v1/customers#

Parameters

Response

Errors

GET /v1/customers/{id}#

Parameters

Response

Errors

GET /v1/customers/{id}/owners#

Parameters

Response

Errors

GET /v1/customers/{id}/documents#

Parameters

Response

Errors

POST /v1/customers/{id}/close#

Parameters

Request body

Response

Errors

Hosted sessions#

POST /v1/sessions#

Request body

Response

Errors

POST /v1/sessions/exchange#

Request body

Response

Errors

Bank linking#

POST /v1/customers/{id}/link-tokens#

Parameters

Request body

Response

Errors

POST /v1/customers/{id}/linked-accounts#

Parameters

Request body

Response

Errors

GET /v1/customers/{id}/linked-accounts#

Parameters

Response

Errors

DELETE /v1/customers/{id}/linked-accounts/{linked_account_id}#

Parameters

Response

Errors

Accounts#

GET /v1/accounts#

Parameters

Response

Errors

GET /v1/accounts/{id}/balance#

Parameters

Response

Errors

GET /v1/accounts/{id}/transactions#

Parameters

Response

Errors

GET /v1/accounts/{id}/statements#

Parameters

Response

Errors

Loads#

POST /v1/loads#

POST `/oauth/token`#

POST `/v1/customers`#

GET `/v1/customers`#

GET `/v1/customers/{id}`#

GET `/v1/customers/{id}/owners`#

GET `/v1/customers/{id}/documents`#

POST `/v1/customers/{id}/close`#

POST `/v1/sessions`#

POST `/v1/sessions/exchange`#

POST `/v1/customers/{id}/link-tokens`#

POST `/v1/customers/{id}/linked-accounts`#

GET `/v1/customers/{id}/linked-accounts`#

DELETE `/v1/customers/{id}/linked-accounts/{linked_account_id}`#

GET `/v1/accounts`#

GET `/v1/accounts/{id}/balance`#

GET `/v1/accounts/{id}/transactions`#

GET `/v1/accounts/{id}/statements`#

POST `/v1/loads`#

GET `/v1/loads/{id}`#

POST `/v1/payment-requests`#

GET `/v1/payment-requests/{id}`#

POST `/v1/payment-requests/{id}/cancel`#

POST `/v1/payments`#

GET `/v1/payments/{id}`#

POST `/v1/payments/{id}/cancel`#

POST `/v1/withdrawals`#

GET `/v1/withdrawals/{id}`#

POST `/v1/refund-requests`#

GET `/v1/refund-requests/{id}`#

POST `/v1/disputes`#