Sub-accounts, cases and documents

Merchant sub-accounts, fees, limits and quotes, complaints, privacy requests, the review team's questions, tax documents, closure and document downloads.

Everything a customer can do with A2A InstaPay, they do through your app. This guide covers the account services around money movement.

Merchant sub-accounts#

A merchant can split its balance by store, terminal or machine. Every merchant has a main sub-account (is_main), which holds the merchant-level balance and cannot be deactivated or closed.

Call	Use
`GET /v1/sub-account-types?customer_id=...`	The types the merchant may use; some are for gaming merchants only
`POST /v1/customers/{id}/sub-accounts`	Open one, with `name` and `type_id`
`POST /v1/customers/{id}/sub-accounts/{sub_account_id}`	Rename it
`.../deactivate`, `.../reactivate`, `.../close`	An inactive sub-account takes no payments; close needs a zero balance and is final

Name the sub-account credited with sub_account_id on a payment request or payee_sub_account_id on a payment. An inactive sub-account gives 422 sub_account_inactive. GET /v1/customers/{id}/sub-accounts lists the balances; sub_account.created, .updated and .closed report changes. In the sandbox, a merchant's withdrawals take from the main sub-account first, then from the others.

Fees, limits and quotes#

GET /v1/fees lists the fees in force. Loads, refunds and receiving money are free.
GET /v1/accounts/{id}/limits gives the customer's limits by movement, and what is used today and this month.
POST /v1/quotes returns the fee, the total and whether the movement would be accepted now (can_proceed, with failure_code when not), without creating anything. Show the fee before the customer confirms.

Complaints and privacy requests#

File a customer's complaint with POST /v1/complaints (category, subject, description) and a privacy request with POST /v1/privacy-requests (type access, correction or deletion, with a description). Each gets an A2A InstaPay case number; complaint.updated and privacy_request.updated report progress. A privacy request is answered within 30 days (due_at).

The review team's questions#

A2A InstaPay's review team may ask a merchant a question. information_request.created announces it, and GET /v1/information-requests?customer_id=...&status=open lists the open ones. Open an information_request hosted session for the merchant to answer; the request becomes responded.

Tax documents and accepted documents#

GET /v1/accounts/{id}/tax-documents lists a merchant's Form 1099-K documents, newest first; tax_document.available announces a new one. Each accepted customer document in GET /v1/customers/{id}/documents carries a download_url for its PDF. Links are valid for 15 minutes; list again for a fresh link.

Closing an account#

GET /v1/closure-reasons lists the reasons, with the customer types each applies to. Send reason_code (and optional notes) with POST /v1/customers/{id}/close. The account's closure shows the request: its status, the reason, and what happens to a remaining balance.

Profile and identity changes#

Open a hosted session for the change; the customer signs in with A2A InstaPay and makes it there.

Flow	Who	What
`contact_change`	Consumers	E-mail address
`profile_change`	Consumers and merchants	E-mail and address; a merchant's trading name and business address
`identity_change`	Merchants	Legal name, EIN, entity type or ownership
`pin_change`	Everyone	The A2A InstaPay PIN, with the current one

A change the review team must check finishes with review_required true in the session outcome, and the customer's verification goes to in_review until it is decided.

In the sandbox#

The sandbox teams take each complaint and privacy request a few seconds after it is filed; move them on with the simulation events complaint.updated and privacy_request.updated. Ask a merchant a question with information_request.created, and issue a Form 1099-K with tax_document.available. Run the scenarios Merchant sub-accounts and Complaints, privacy requests and review questions.

Questions about this page? Contact developer support.