Track activation

Follow a v2 account from pending to active with the applications.accounts webhooks or by reading the account, and act on each status_reason.

API version: v2.

A new v2 account is pending while the bank reviews it. Follow it with the applications.accounts.* webhooks, or read GET /v2/accounts/{id} until status is active. For a v2 account you open, Gravv never sends account.activated. Wait for applications.accounts.completed instead.

A money example. Ada's client is ready to pay 1,200.00 USD, but the account is pending with status_reason provider_review. You don't need to do anything. An hour later applications.accounts.completed arrives, you read the account, and you give the client the account and routing numbers.

Read the account

curl --request GET \
     --url https://api.gravv.xyz/v2/accounts/6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11 \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "id": "6f1c2a9e-3b1d-4f7a-9c62-0d8e4b7a5c11",
    "status": "pending",
    "status_reason": "provider_review",
    "status_message": "The bank is reviewing this application. Nothing is outstanding from you or the customer.",
    "requires_user_action": false,
    "currency": "USD",
    "category": "sub_account",
    "blockchain_network": "polygon",
    "application_id": "5e7a9c1b-2d4f-4a6b-8c0d-e1f2a3b4c5d6"
  },
  "error": null
}

• application_id is the application to read or fix. The create response does not include it.
• status_reason is a fixed code. Branch on it, never on status_message, whose text can change.
• If requires_user_action is true, you or the customer must act. Go to Fix a blocked application.
• Bank details (virtual_account_bank_*) appear only once status is active.

Poll every few seconds at first, then less often, because a bank review can take minutes or days.

What each status_reason means

status_reason	Who acts	What to do
awaiting_customer_document	You	Upload every type in required_documents, in one PATCH
awaiting_customer_data	You	Send every field in required_fields, in one PATCH
tos_pending	The customer	Open required_action_url and accept the bank's terms. The application then resumes by itself. There is no API call to accept terms
kyc_pending	The customer	Open required_action_url, the bank's own verification page. If the URL is not there yet, read again later
provider_review, awaiting_activation_details, provider_unavailable, provisioning_retrying	Nobody	Wait. The application continues by itself
manual_review_requested	Gravv	Gravv holds the application for review and sends no webhook. Contact support with the id and application_id
verification_rejected, verification_declined, review_declined	Nobody	The bank said no. The same details get the same answer, so try another option
region_not_supported	Nobody	Choose another bank_code
identity_document_mismatch, information_expired, request_cancelled	You	Open a new account with corrected data
settlement_wallet_unavailable	You	Gravv could not create the wallet on that network. Open a new account on another network

Webhooks

Event	When	Read
applications.accounts.pending	Gravv accepted the application. Gravv does not always send this event	account_id, application_id
applications.accounts.blocked	The application waits on you or the customer	metadata.block_reason, metadata.action_url, metadata.additional_requirements
applications.accounts.completed	The account is active	account_id. The event carries no bank details, so read the account
applications.accounts.failed	The application ended without an account	metadata.fail_reason

Deduplicate on the body's event_id. Gravv can drop a second blocked event of the same type for one application, so always read the application again after you act. The payloads are on Account application events.

Next

When the account is active, read its bank details and give them to the payer.