Upgrade Your Virtual Account Integration

Use this guide if your integration already calls Create Virtual Account or processes Virtual Account webhooks. The new behavior is available in Sandbox from August 13, 2026 and takes effect in Production on September 3, 2026.

​

Changes at a glance

The Create path remains POST /v1/virtual/accounts.

​

1. Update the Create request

Keep sending the required x-idempotency-key. Change your request builder to:

1. Add the required two-letter country.
2. Send one three-letter currency value.
3. Send payment_method as LOCAL or SWIFT, or omit it to evaluate both methods. Do not send ALL or AUTO.
4. Treat nickname as optional.
5. Remove logic that uses x-request-id for this endpoint.

For a connected account, continue to send its account ID in x-on-behalf-of. See Create Virtual Account for the request schema and supported combinations for valid values. When retrying after a network failure, send the same request for the same account with the same x-idempotency-key. Use a new key when any application input changes.

​

2. Replace the Create success response

Parse HTTP 200 as an accepted application. It does not mean bank details are ready. Remove parsing of message and request_id. Instead:

1. Store data.account_id and data.direct_id with the application.
2. Store data.application_id.
3. Store data.public_version.
4. Process every entry in data.results[] and identify it by payment_method.
5. Use bank details only when the result is COMPLETED and the individual record is ACTIVE.

If payment_method is omitted, one result can be SKIPPED while another is SUBMITTED. Do not treat the top-level application status as the status of every method.

​

3. Add application queries

Add these endpoints to your integration:

• List Virtual Account Applications discovers and reconciles applications. page_number and page_size are required.
• Retrieve Virtual Account Application returns the latest full details for one application_id.

Keep List Virtual Accounts for issued bank details. It does not list pending applications.

​

4. Update the webhook consumer

Handle all three application event types: Keep your existing signature verification and acknowledgement flow. Change correlation and ordering logic to:

1. Deduplicate deliveries by event_id.
2. Associate the event with the account in data.account_id; use data.direct_id to identify its main account when applicable.
3. Locate the application by data.application_id.
4. Apply only a higher data.public_version.
5. Process every result after applying the event.
6. Call Retrieve when a version is missing or delivery appears out of order.

See Virtual Account Application Webhooks for event timing, examples, and recovery behavior.

​

5. Separate request errors from later failures

A synchronous Create 400 means no application was created and no application webhook will follow. Correct the request or account setup before trying again. After HTTP 200, a receiving method can later become FAILED. In that case, process the virtual.account.update event and use results[].error.code to decide the next action. See Integrate Virtual Accounts with the API for error codes and actions.

​

Sandbox checklist

Before Production rollout, verify that your integration can:

• Send one supported country and currency, with an optional payment_method.
• Retry an identical request with the same x-idempotency-key and retain one application_id.
• Reject reuse of the key for different application input.
• Parse HTTP 200 and process every entry in results[].
• Handle SKIPPED and SUBMITTED results in the same application.
• Store and compare application_id + public_version.
• List applications and retrieve the latest details.
• Accept virtual.account.create before or after the Create response.
• Associate application events with the correct account using account_id and direct_id.
• Apply COMPLETED, FAILED, and CLOSED data without relying on delivery order.
• Use only ACTIVE bank details and stop using CLOSED records, even when close_reason is empty.
• Stop waiting for a webhook after a synchronous Create error.

After the checklist passes, use Integrate Virtual Accounts with the API as the ongoing integration guide.