Skip to main content
Jp Morgan Wallet

Update a virtual account

Overview

You can use the J.P. Morgan Wallet™ API to update your Virtual Transaction Accounts (VTAs). The following steps describe the general process of updating a VTA:

  1. You submit an API request to update a VTA.

  2. Wallet validates the format of the request.

    • If validation fails: Wallet sends a synchronous reject notification.
    • If validation succeeds: Wallet continues to the next step.

  3. Wallet validates the schema.

    • If validation fails: Wallet sends a synchronous reject notification.
    • If validation succeeds: Wallet sends a synchronous accept notification and continues to the next step.

  4. Wallet finishes executing all validations.

    • If any validations fail: Wallet sends a terminal asynchronous reject notification.
    • If all validations succeed: Wallet sends a terminal asynchronous completion notification.

For an overview of virtual accounts, see Virtual accounts.

Notes:

  • You cannot update the standard virtual accounts that we create when we establish your Wallet program.
  • You cannot update Virtual Summary Accounts (VSAs).
  • You can only update one VTA per request.

Update the state of a Virtual Transaction Account

Update the state of a VTA by sending a request to the Wallet API.

The following table lists the possible states you can set for a VTA depending on its current state. For more information about VTA states, see Virtual accounts - States.

VTA state change rules
Current state Possible new states
PENDING_OPEN
  • OPEN
  • PENDING_CLOSE
  • CLOSED
OPEN (default state when you create a VTA)
  • PENDING_CLOSE
  • CLOSED (if balance is zero)
PENDING_CLOSE
  • OPEN
  • CLOSED (if balance is zero)
CLOSED None (VTA is permanently closed)

Endpoints

Send an API request to one of the following endpoints to update the state of a VTA. For the specification, see the API reference.

Endpoints for "Update the state of a VTA" request
HTTP method Request v2.xx v3.xx
POST Update a VTA Not supported /wallets/{accountIdentification}/update

Request

Path parameters

Include the following parameters in the URL.

Path parameters for "Update the state of a VTA" request
Parameter Required / Optional Description
accountIdentification Required VTA ID. Case-sensitive.

Header parameters

Include the following parameters in the header.

Header parameters for the "Update the state of a VTA" request
Parameter Required / Optional Description
programId Required Your Wallet program ID.

Body parameters

Include the following parameters in the request body.

Body parameters for "Update the state of a VTA" request
Parameter Required / Optional Description
messageIdentification.clientReferenceId Required ID that you define to associate with this request. Must be unique.
virtualAccountDetail.virtualAccountState Optional State to set this VTA to. You can set the state to OPEN, PENDING_CLOSE, or CLOSED.

Response

If the request is successful, the API returns a response with the following fields:

  • acknowledgedMessageIdentification
    • clientReferenceId: The client reference ID that you specified in the request.
    • requestReferenceId: ID associated with this request that the API generates.
    • virtualAccountIdentification: The ID of the VTA that the API updated.
    • receivedDateTime: The date and time when the API received the request.

Notification

After the API completes the request, in addition to the response, Wallet sends an asynchronous notification providing the following information:

  • originalInformationAndStatus
    • clientReferenceId: The client reference ID that you specified in the request.
    • requestReferenceId: ID associated with this request that the API generates.
    • activityType: The action that the API performed.
    • activityDescription: Description of the action that the API performed.
    • initiatedBy: The initiator of the action.
    • receivedDateTime: The date and time that Wallet received the request.
    • completedDateTime: The date and time that Wallet completed the request.
  • currentVirtualAccountDetail
    • parentVirtualAccountIdentification: The ID of the parent VSA.
    • virtualAccountIdentification: The ID of the VTA that Wallet updated.
    • virtualAccountType: The type of virtual account.
    • virtualAccountState: The state of the VTA.
    • accountOptions
      • paymentRoutingNumber: The PRN of the VTA (if available).
      • balanceLimits
        • minimumBalance: The minimum balance of the VTA.
        • maximumBalance: The maximum balance of the VTA.

Examples

The following example request body updates the state of a VTA.

Example request body: Update the state of a VTA
Json
{
    "messageIdentification": {
        "clientReferenceId": "LL-tz3xkt"
    },
    "virtualAccountDetail": {
        "virtualAccountState": "PENDING_CLOSE"
    }
}

The following is the synchronous response to the previous example request.

Example synchronous response: Update the state of a VTA
Json
{
    "acknowledgedMessageIdentification": {
        "clientReferenceId": "LL-tz3xkt",
        "requestReferenceId": "01476af7-8a68-41d8-b1ea-2c2cb67ae63b",
        "virtualAccountIdentification": "SALES-VTA1",
        "receivedDateTime": "2025-03-27T20:38:09.582+0000"
    }
}

The following is the asynchronous notification that Wallet sends after the previous example request is completed.

Example asynchronous notification: Update the state of a VTA
Json
{
    "groupHeader": {
        "messageIdentification": "561105f0-fad0-46da-8641-ab88bc8c6074",
        "creationDateTime": "2025-03-27T20:38:09.794+0000"
    },
    "originalInformationAndStatus": {
        "clientReferenceId": " LL-tz3xkt ",
        "requestReferenceId": "01476af7-8a68-41d8-b1ea-2c2cb67ae63b",
        "activityType": "UPDATE",
        "activityDescription": "Account Updated",
        "initiatedBy": "API",
        "receivedDateTime": "2025-03-27T20:38:09.746+00:00",
        "completedDateTime": "2025-03-27T20:38:09.746+00:00"
    },
    "currentVirtualAccountDetail": {
        "parentVirtualAccountIdentification": "NORTH-VSA",
        "virtualAccountIdentification": "SALES-VTA1",
        "virtualAccountType": "EVTA",
        "virtualAccountState": "PENDING_CLOSE",
        "accountOptions": {
            "paymentRoutingNumber": {},
            "balanceLimits": {
                "minimumBalance": "-20.0",
                "maximumBalance": "20.0"
            }
        }
    }
}

Assign a Payment Routing Number to a Virtual Transaction Account

You can submit an API request to assign a PRN to a VTA. For information about PRNs, see Virtual accounts - Payment Routing Numbers (PRNs).

The following requirements must be met to assign a PRN to a VTA:

  • The VTA must be in the OPEN state.
  • The VTA must not have a PRN.

Endpoints

Send an API request to one of the following endpoints to assign a PRN to a VTA. For the specification, see the API reference.

Endpoints for "Assign a PRN to a VTA" request
HTTP method Request v2.xx v3.xx
POST Update a VTA Not supported /wallets/{accountIdentification}/update

Request

Path parameters

Include the following parameters in the URL.

Path parameters for "Assign a PRN to a VTA" request
Parameter Required / Optional Description
accountIdentification Required VTA ID. Case-sensitive.

Header parameters

Include the following parameters in the header.

Header parameters for "Assign a PRN to a VTA" request
Parameter Required / Optional Description
programId Required Your Wallet program ID.

Body parameters

Include the following parameters in the request body.

Body parameters for "Assign a PRN to a VTA" request
Parameter Required / Optional Description
messageIdentification.clientReferenceId Required ID that you define to associate with this request. Must be unique.
virtualAccountDetail.accountOptions.paymentRoutingNumber Optional Set to true to assign a PRN to the VTA. Default is false.

Response

If the request is successful, the API returns a response with the following fields:

  • acknowledgedMessageIdentification
    • clientReferenceId: The client reference ID that you specified in the request.
    • requestReferenceId: ID associated with this request that the API generates.
    • virtualAccountIdentification: The ID of the VTA that the API updated.
    • receivedDateTime: The date and time when the API received the request.

Notification

After the API completes the request, in addition to the response, Wallet sends an asynchronous notification providing the following information:

  • originalInformationAndStatus
    • clientReferenceId: The client reference ID that you specified in the request.
    • requestReferenceId: ID associated with this request that the API generates.
    • activityType: The action that the API performed.
    • activityDescription: Description of the action that the API performed.
    • initiatedBy: The initiator of the action.
    • receivedDateTime: The date and time that Wallet received the request.
    • completedDateTime: The date and time that Wallet completed the request.
  • currentVirtualAccountDetail
    • parentVirtualAccountIdentification: The ID of the parent VSA.
    • virtualAccountIdentification: The ID of the VTA that Wallet updated.
    • virtualAccountType: The type of virtual account.
    • virtualAccountState: The state of the VTA.
    • accountOptions
      • paymentRoutingNumber
        • paymentRoutingNumber: The PRN that Wallet assigned to the VTA.
      • balanceLimits
        • minimumBalance: The minimum balance of the VTA.
        • maximumBalance: The maximum balance of the VTA.

Examples

The following example request body assigns a PRN to a VTA:

Example request body: Assign a PRN to a VTA
Json
{
    "messageIdentification": {
        "clientReferenceId": "LL-apemtq"
    },
    "virtualAccountDetail": {
        "accountOptions": {
            "paymentRoutingNumber": "true"
        }
    }
}

The following is the synchronous response to the previous example request:

Example synchronous response: Assign a PRN to a VTA
Json
{
    "acknowledgedMessageIdentification": {
        "clientReferenceId": "LL-apemtq",
        "requestReferenceId": "dff63377-fdde-4e03-9e56-b5300d3433ae",
        "virtualAccountIdentification": "SALES-VTA2",
        "receivedDateTime": "2025-03-28T20:46:36.473+0000"
    }
}

The following is the asynchronous notification that Wallet sends after the previous example request is completed:

Example asynchronous notification: Assign a PRN to a VTA
Json
{
    "groupHeader": {
        "messageIdentification": "d866ef8d-b6a1-414e-b413-fa5f07a12d9e",
        "creationDateTime": "2025-03-28T20:46:37.181+0000"
    },
    "originalInformationAndStatus": {
        "clientReferenceId": "LL-apemtq",
        "requestReferenceId": "dff63377-fdde-4e03-9e56-b5300d3433ae",
        "activityType": "UPDATE",
        "activityDescription": "Account Updated",
        "initiatedBy": "API",
        "receivedDateTime": "2025-03-28T20:46:37.121+00:00",
        "completedDateTime": "2025-03-28T20:46:37.121+00:00"
    },
    "currentVirtualAccountDetail": {
        "parentVirtualAccountIdentification": "NORTH-VSA",
        "virtualAccountIdentification": "SALES-VTA2",
        "virtualAccountType": "EVTA",
        "virtualAccountState": "OPEN",
        "accountOptions": {
            "paymentRoutingNumber": {
                "paymentRoutingNumber": "XXXXXXXXXX"
            },
            "balanceLimits": {
                "minimumBalance": "-20.0",
                "maximumBalance": "20.0"
            }
        }
    }
}

Deactivate a Payment Routing Number

To deactivate a PRN associated with a VTA, you must close the VTA.

After you close a VTA, Wallet does not deactivate its PRN until the end of the day. If a payment is made to the PRN while it is still active and the VTA is closed, Wallet transfers the funds to the Default VTA.

Update the balance limits of a Virtual Transaction Account

You can submit an API request to update the balance limits of a VTA. For information about balance limits, see Virtual accounts - Balance limits.

Notes:

  • The VTA must be in the PENDING_OPEN, OPEN, or PENDING_CLOSE state.
  • The minimum balance must be less than or equal to the maximum balance.
  • The balance limits can be negative, zero, or positive.
  • By default, the smallest and largest allowed balance limits are:
    • Minimum: -99999999999.99
    • Maximum: 99999999999.99

Endpoints

Send an API request to one of the following endpoints to update the balance limits of a VTA. For the specification, see the API reference.

Endpoints for "Update the balance limits of a VTA" request
HTTP method Request v2.xx v3.xx
POST Update a VTA Not supported /wallets/{accountIdentification}/update

Request

Path parameters

Include the following parameters in the URL.

Path parameters for "Update the balance limits of a VTA" request
Parameter Required / Optional Description
accountIdentification Required VTA ID. Case-sensitive.

Header parameters

Include the following parameters in the header.

Header parameters for "Update the balance limits of a VTA" request
Parameter Required / Optional Description
programId Required Your Wallet program ID.

Body parameters

Include the following parameters in the request body.

Body parameters for "Update the balance limits of a VTA" request
Parameter Required / Optional Description
messageIdentification.clientReferenceId Required ID that you define to associate with this request. Must be unique.
virtualAccountDetail.accountOptions.balanceLimits.maximumBalance Optional The VTA balance cannot go above this limit.
virtualAccountDetail.accountOptions.balanceLimits.minimumBalance Optional The VTA balance cannot go below this limit.

Response

If the request is successful, the API returns a response with the following fields:

  • acknowledgedMessageIdentification
    • clientReferenceId: The client reference ID that you specified in the request.
    • requestReferenceId: ID associated with this request that the API generates.
    • virtualAccountIdentification: The ID of the VTA that the API updated.
    • receivedDateTime: The date and time when the API received the request.

Notification

After the API completes the request, in addition to the response, Wallet sends an asynchronous notification providing the following information:

  • originalInformationAndStatus
    • clientReferenceId: The client reference ID that you specified in the request.
    • requestReferenceId: ID associated with this request that the API generates.
    • activityType: The action that the API performed.
    • activityDescription: Description of the action that the API performed.
    • initiatedBy: The initiator of the action.
    • receivedDateTime: The date and time that Wallet received the request.
    • completedDateTime: The date and time that Wallet completed the request.
  • currentVirtualAccountDetail
    • parentVirtualAccountIdentification: The ID of the parent VSA.
    • virtualAccountIdentification: The ID of the VTA that Wallet updated.
    • virtualAccountType: The type of virtual account.
    • virtualAccountState: The state of the VTA.
    • accountOptions
      • paymentRoutingNumber
        • paymentRoutingNumber: The PRN that Wallet assigned to the VTA (if available).
        • status: The status of the PRN.
        • country: The country that the PRN is associated with.
        • routingInformation
          • type: The type of routing ID.
          • value: The routing ID.
      • balanceLimits
        • minimumBalance: The minimum balance of the VTA.
        • maximumBalance: The maximum balance of the VTA.

Example

The following example request body updates the balance limits of a VTA:

Example request body: Update the balance limits of a VTA
Json
{
    "messageIdentification": {
        "clientReferenceId": "LL-pvh20x"
    },
    "virtualAccountDetail": {
        "accountOptions": {
            "balanceLimits": {
                "minimumBalance": "-99999999999.99",
                "maximumBalance": "99999999999.99"
            }
        }
    }
}

The following is the synchronous response to the previous example request:

Example synchronous response: Update the balance limits of a VTA
Json
{
    "acknowledgedMessageIdentification": {
        "clientReferenceId": "LL-pvh20x",
        "requestReferenceId": "1d98179f-c6ae-4816-af4f-69e08e83bac1",
        "virtualAccountIdentification": "SALES-VTA1",
        "receivedDateTime": "2025-03-13T20:57:07.414+0000"
    }
}

The following is the asynchronous notification that Wallet sends after the previous example request is completed:

Example asynchronous notification: Update the balance limits of a VTA
Json
{
    "groupHeader": {
        "messageIdentification": "9b9db166-c497-4ed6-bbdd-1cd192bd66bb",
        "creationDateTime": "2025-03-13T20:57:07.627+0000"
    },
    "originalInformationAndStatus": {
        "clientReferenceId": "LL-pvh20x",
        "requestReferenceId": "1d98179f-c6ae-4816-af4f-69e08e83bac1",
        "activityType": "UPDATE",
        "activityDescription": "Account Updated",
        "initiatedBy": "API",
        "receivedDateTime": "2025-03-13T20:57:07.561+00:00",
        "completedDateTime": "2025-03-13T20:57:07.561+00:00"
    },
    "currentVirtualAccountDetail": {
        "parentVirtualAccountIdentification": "NORTH-VSA",
        "virtualAccountIdentification": "SALES-VTA1",
        "virtualAccountType": "EVTA",
        "virtualAccountState": "OPEN",
        "accountOptions": {
            "paymentRoutingNumber": {
                "paymentRoutingNumber": "XXXXXXXXXX",
                "status": "ACTIVE",
                "country": "US",
                "routingInformation": [
                    {
                        "type": "ABA",
                        "value": "XXXXXXXXXX"
                    }
                ]
            },
            "balanceLimits": {
                "minimumBalance": "-99999999999.99",
                "maximumBalance": "99999999999.99"
            }
        }
    }
}

Add a posting restriction to a Virtual Transaction Account

You can submit an API request to add a posting restriction to a VTA.

A posting restriction prevents certain types of transactions from posting to a VTA. There are three types of posting restrictions:

  • DEBITS: Rejects debit transactions on the VTA.
  • CREDITS: Rejects credit transactions on the VTA.
  • ALL: Rejects both debit and credit transactions on the VTA.

Notes:

  • The VTA must be in the PENDING_OPEN, OPEN, or PENDING_CLOSE state.
  • You can only add one posting restriction per API request.
  • A VTA can have multiples of the same type of posting restriction, but it only takes one to prevent that type of transaction from posting to the VTA.
  • After you add a posting restriction to a VTA, it remains until you remove it.

Endpoints

Send an API request to one of the following endpoints to add a posting restriction to a VTA. For the specification, see the API reference.

Endpoints for "Add a posting restriction to a VTA" request
HTTP method Request v2.xx v3.xx
POST Add a posting restriction to a VTA Not supported /wallets/{accountIdentification}/postingrestriction

Request

Path parameters

Include the following parameters in the URL.

Path parameters for "Add a posting restriction to a VTA" request
Parameter Required / Optional Description
accountIdentification Required VTA ID. Case-sensitive.

Header parameters

Include the following parameters in the header.

Header parameters for "Add a posting restriction to a VTA" request
Parameter Required / Optional Description
programId Required Your Wallet program ID.

Body parameters

Include the following parameters in the request body.

Body parameters for "Add a posting restriction to a VTA" request
Parameter Required / Optional Description
messageIdentification.clientReferenceId Required ID that you define to associate with this request. Must be unique.
virtualAccountDetail.restrictionType Required The type of posting restriction to add to the VTA.

Response

If the request is successful, the API returns a response with the following fields:

  • acknowledgedMessageIdentification
    • clientReferenceId: The client reference ID that you specified in the request.
    • requestReferenceId: ID associated with this request that the API generates.
    • virtualAccountIdentification: The ID of the VTA that the API updated.
    • receivedDateTime: The date and time when the API received the request.

Notification

After the API completes the request, in addition to the response, Wallet sends an asynchronous notification providing the following information:

  • originalInformationAndStatus
    • clientReferenceId: The client reference ID that you specified in the request.
    • restrictionId: A unique ID that Wallet assigns to the posting restriction. Use this to remove the posting restriction.
    • requestReferenceId: A unique ID that Wallet assigns to this request.
    • activityType: The action that the API performed.
    • activityDescription: Description of the action that the API performed.
    • initiatedBy: The initiator of the action.
    • receivedDateTime: The date and time that Wallet received the request.
    • completedDateTime: The date and time that Wallet completed the request.
  • currentVirtualAccountDetail
    • parentVirtualAccountIdentification: The ID of the parent VSA.
    • virtualAccountIdentification: The ID of the VTA that Wallet updated.
    • virtualAccountType: The type of virtual account.
    • virtualAccountState: The state of the VTA.
    • accountOptions
      • paymentRoutingNumber: The PRN associated with the VTA (if available).
      • balanceLimits
        • minimumBalance: The minimum balance of the VTA.
        • maximumBalance: The maximum balance of the VTA.
      • postingRestrictions: Array of posting restrictions on the VTA.
        • restrictionId: Unique ID associated with this restriction.
        • restrictionType: The type of restriction.
        • restrictionReason: The reason that the restriction was added. Always Client Requested when you add the restriction by API.

Examples

The following example request body adds a posting restriction to a VTA:

Example request body: Add a posting restriction to a VTA
Json
{
    "messageIdentification": {
        "clientReferenceId": "LL-lnfix2"
    },
    "virtualAccountDetail": {
        "virtualAccountIdentification": "SALES-VTA1",
        "restrictionType": "CREDITS"
    }
}

The following is the synchronous response to the previous example request:

Example synchronous response: Add a posting restriction to a VTA
Json
{
    "acknowledgedMessageIdentification": {
        "clientReferenceId": "LL-lnfix2",
        "requestReferenceId": "8755fd95-8c6c-4c8e-95be-8f22d64d3e5e",
        "virtualAccountIdentification": "SALES-VTA1",
        "restrictionType": "CREDITS",
        "restrictionReason": "Client Requested",
        "receivedDateTime": "2025-03-03T15:09:00.772+0000"
    }
}

The following is the asynchronous notification that Wallet sends after the previous example request is completed:

Example asynchronous notification: Add a posting restriction to a VTA
Json
{
    "groupHeader": {
        "messageIdentification": "d8334af3-b250-4e13-8402-01aff204a9ea",
        "creationDateTime": "2025-03-03T15:09:00.969+0000"
    },
    "originalInformationAndStatus": {
        "clientReferenceId": "LL-lnfix2",
        "restrictionId": "9b1c7226-6ca4-4ab2-b920-859974123d1f",
        "requestReferenceId": "8755fd95-8c6c-4c8e-95be-8f22d64d3e5e",
        "activityType": "ADD_RESTRICTION",
        "activityDescription": "Posting restriction added",
        "initiatedBy": "API",
        "receivedDateTime": "2025-03-03T15:09:00.915+00:00",
        "completedDateTime": "2025-03-03T15:09:00.915+00:00"
    },
    "currentVirtualAccountDetail": {
        "parentVirtualAccountIdentification": "NORTH-VSA",
        "virtualAccountIdentification": "SALES-VTA1",
        "virtualAccountType": "EVTA",
        "virtualAccountState": "OPEN",
        "accountOptions": {
            "paymentRoutingNumber": {},
            "balanceLimits": {
                "minimumBalance": "-1.00",
                "maximumBalance": "5000.00"
            },
            "postingRestrictions": [
                {
                    "restrictionId": "c4eef50e-12de-4d72-b5b3-31cc95bc7845",
                    "restrictionType": "DEBITS",
                    "restrictionReason": "Client Requested"
                }, 
                {
                    "restrictionId": "9b1c7226-6ca4-4ab2-b920-859974123d1f",
                    "restrictionType": "CREDITS",
                    "restrictionReason": "Client Requested"
                }
            ]
        }
    }
}

Remove a posting restriction from a Virtual Transaction Account

You can submit an API request to remove a posting restriction from a VTA.

Notes:

  • The VTA must be in the PENDING_OPEN, OPEN, or PENDING_CLOSE state.
  • The posting restriction that you are trying to remove must exist and must not have already been removed.
  • You can only remove one posting restriction per API request.

Endpoints

Send an API request to one of the following endpoints to remove a posting restriction from a VTA. For the specification, see the API reference.

Endpoints for "Remove a posting restriction from a VTA" request
HTTP method Request v2.xx v3.xx
POST Remove a posting restriction from a VTA Not supported /wallets/{accountIdentification}/postingrestriction/remove

Request

Path parameters

Include the following parameters in the URL.

Path parameters for "Remove a posting restriction from a VTA" request
Parameter Required / Optional Description
accountIdentification Required VTA ID. Case-sensitive.

Header parameters

Include the following parameters in the header.

Header parameters for "Remove a posting restriction from a VTA" request
Parameter Required / Optional Description
programId Required Your Wallet program ID.

Body parameters

Include the following parameters in the request body.

Body parameters for "Remove a posting restriction from a VTA" request
Parameter Required / Optional Description
messageIdentification.clientReferenceId Required ID that you define to associate with this request. Must be unique.
virtualAccountDetail.restrictionId Required ID of the posting restriction to remove from the VTA. Wallet assigned this ID when you added the posting restriction to the VTA. You can get this ID by submitting an API request to get details about the VTA.

Response

If the request is successful, the API returns a response with the following fields:

  • acknowledgedMessageIdentification
    • clientReferenceId: The client reference ID that you specified in the request.
    • requestReferenceId: ID that Wallet generates that is associated with this request.
    • virtualAccountIdentification: The ID of the VTA that Wallet updated.
    • receivedDateTime: The date and time when Wallet received the request.

Notification

After the API completes the request, in addition to the response, Wallet sends an asynchronous notification providing the following information:

  • originalInformationAndStatus
    • clientReferenceId: The client reference ID that you specified in the request.
    • restrictionId: The ID of the posting restriction that you removed.
    • requestReferenceId: A unique ID that Wallet assigns to this request.
    • activityType: The action that the API performed.
    • activityDescription: Description of the action that the API performed.
    • initiatedBy: The initiator of the action.
    • receivedDateTime: The date and time that Wallet received the request.
    • completedDateTime: The date and time that Wallet completed the request.
  • currentVirtualAccountDetail
    • parentVirtualAccountIdentification: The ID of the parent VSA.
    • virtualAccountIdentification: The ID of the VTA that Wallet updated.
    • virtualAccountType: The type of virtual account.
    • virtualAccountState: The state of the VTA.
    • accountOptions
      • paymentRoutingNumber: The PRN associated with the VTA (if available).
      • balanceLimits
        • minimumBalance: The minimum balance of the VTA.
        • maximumBalance: The maximum balance of the VTA.
      • postingRestrictions: Array of posting restrictions on the VTA.
        • restrictionId: Unique ID associated with this restriction.
        • restrictionType: The type of restriction.
        • restrictionReason: The reason that the restriction was added. Always Client Requested when you add the restriction by API.

Examples

The following example request body removes a posting restriction from a VTA:

Example request body: Remove a posting restriction from a VTA
Json
{
    "messageIdentification": {
        "clientReferenceId": "LL-nejxx4"
    },
    "virtualAccountDetail": {
        "restrictionId": "c4eef50e-12de-4d72-b5b3-31cc95bc7845"
    }
}

The following is the synchronous response to the previous example request:

Example synchronous response: Remove a posting restriction from a VTA
Json
{
    "acknowledgedMessageIdentification": {
        "clientReferenceId": "LL-nejxx4",
        "requestReferenceId": "5040fe52-d25e-4cbc-887c-c00c9d1ffc7a",
        "virtualAccountIdentification": "SALES-VTA1",
        "receivedDateTime": "2025-03-03T19:35:11.830+0000"
    }
}

The following is the asynchronous notification that Wallet sends after the previous example request is completed:

Example asynchronous notification: Remove a posting restriction from a VTA
Json
{
    "groupHeader": {
        "messageIdentification": "6eca1691-ba55-4a98-8564-fd85c66266aa",
        "creationDateTime": "2025-03-03T19:35:12.068+0000"
    },
    "originalInformationAndStatus": {
        "clientReferenceId": "LL-nejxx4",
        "restrictionId": "c4eef50e-12de-4d72-b5b3-31cc95bc7845",
        "requestReferenceId": "5040fe52-d25e-4cbc-887c-c00c9d1ffc7a",
        "activityType": "REMOVE_RESTRICTION",
        "activityDescription": "Posting restriction removed",
        "initiatedBy": "API",
        "receivedDateTime": "2025-03-03T19:35:11.992+00:00",
        "completedDateTime": "2025-03-03T19:35:11.992+00:00"
    },
    "currentVirtualAccountDetail": {
        "parentVirtualAccountIdentification": "NORTH-VSA",
        "virtualAccountIdentification": "SALES-VTA1",
        "virtualAccountType": "EVTA",
        "virtualAccountState": "OPEN",
        "accountOptions": {
            "paymentRoutingNumber": {},
            "balanceLimits": {
                "minimumBalance": "-1.00",
                "maximumBalance": "5000.00"
            },
            "postingRestrictions": [
                {
                    "restrictionId": "9b1c7226-6ca4-4ab2-b920-859974123d1f",
                    "restrictionType": "CREDITS",
                    "restrictionReason": "Client Requested"
                }
            ]
        }
    }
}

Close a Virtual Transaction Account

To close a VTA, follow these steps:

  1. Set the VTA's state to PENDING_CLOSE. See Update the state of a Virtual Transaction Account.
  2. Reduce the VTA's balance to zero by transferring all of its funds to other accounts. To transfer funds between VTAs, see Move funds between VTAs (Virtual-to-Virtual).
  3. Set the VTA's state to CLOSED. The VTA is now permanently closed.

After you close a VTA, Wallet does not deactivate its PRN until the end of the day. If a payment is made to the PRN while it is still active and the VTA is closed, Wallet transfers the funds to the Default VTA.

A VTA in the CLOSED state cannot process financial or non-financial requests, and its balance must be zero. After setting a VTA's state to CLOSED, you cannot change it again.