Jp Morgan Wallet

Create a virtual account

Overview

This document explains how to create virtual accounts in your J.P. Morgan Wallet™ program. For an overview of virtual accounts, see Virtual accounts.

To create a virtual account, submit an API request to create a new Virtual Summary Account (VSA) or Virtual Transaction Account (VTA). The endpoint that you use to create a VSA or a VTA is the same. You can create up to 15 virtual accounts in a single request.

The following steps describe the general process of creating a virtual account.

You submit an API request to create a VSA or VTA.
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.
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.
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 and adds the virtual account to your structure.

Key information

The following table describes important information about the "Create a virtual account" endpoint.

Key information for "Create a virtual account" endpoint
Production endpoint	v3.x: `https://apigateway.jpmorgan.com/tsapi/v3/jpmwallet/wallets` v2.x: `https://apigateway.jpmorgan.com/tsapi/v2/jpmwallet/wallets/batch`
Client testing endpoint	v3.x: `https://apigatewaycat.jpmorgan.com/tsapi/v3/jpmwallet/wallets` v2.x: `https://apigatewaycat.jpmorgan.com/tsapi/v2/jpmwallet/wallets/batch`
Supported branches	All J.P. Morgan branches that support Wallet
Supported currencies	All currencies that the branch supports

Create a Virtual Summary Account

You can use the Wallet API to create a VSA. The process for creating a VSA follows the steps in Create a virtual account.

Requirements

VSA creation requests must adhere to the following requirements:

You must create at least one VSA in your virtual account structure.
You can only create one VSA per request.
VSAs are created in the OPEN state.
VSAs do not have Payment Routing Numbers (PRNs).
VSAs do not have balance limits.

Important parameters

The following sections list important parameters in the VSA creation request. Not all parameters are listed here—for a complete list, see the API reference.

Header parameters

Include the following parameters in the header.

Header parameters for "Create a VSA" request
Parameter	Required / Optional	Description
`programId`	Required	Your Wallet program ID.

Body parameters

Include the following parameters in the request body.

Body parameters for "Create a VSA" request
Parameter	Required / Optional	Description
`messageIdentification.clientReferenceId`	Required	ID associated with this request. Must be unique.
`virtualAccountDetail.parentVirtualAccountIdentification`	Optional	ID of an existing VSA that will be the direct parent of the new VSA. The ID is case-sensitive and must be exact. If you don't provide this, the direct parent of the new VSA will be the top-level VSA, which is identified in the asynchronous notification as the DDA associated with the Wallet program.
`virtualAccountDetail.virtualAccountIdentification`	Required	Unique ID of the new VSA. Maximum 35 characters. Alphanumeric, uppercase and lowercase letters, no special characters except hyphens (`-`).
`virtualAccountDetail.virtualAccountType`	Required	The type of the virtual account. Must be `EVSA`.

Response

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

acknowledgedMessageIdentification
- clientReferenceId: The client reference ID that you submitted in the request.
- requestReferenceId: A request reference ID that the API generates.
- virtualAccountIdentification: The VSA ID that you submitted in the request.
- 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 about the VSA that you created:

originalInformationAndStatus
- clientReferenceId: The reference ID that you provided with the request.
- requestReferenceId: The unique internal request reference ID that Wallet assigned.
- 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 new VSA.
- virtualAccountType: The account type.
- virtualAccountState: The state of the virtual account.
- accountOptions
  - paymentRoutingNumber: The PRN of the virtual account (null for VSAs).
  - balanceLimits: The minimum and maximum balance limits of the virtual account (null for VSAs).

Examples

The following example request creates a new VSA as a direct child of an existing VSA.

Example request body: Create a new VSA under an existing parent VSA

Json

{
    "messageIdentification": {
        "clientReferenceId": "LL-1ztpgv"
    },
    "virtualAccountDetail": {
        "parentVirtualAccountIdentification": "ALL-REGION-VSA",
        "virtualAccountIdentification": "NORTH-VSA",
        "virtualAccountType": "EVSA"
    }
}

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

Example synchronous response: Create a new VSA under an existing parent VSA

Json

{
    "acknowledgedMessageIdentification": {
        "clientReferenceId": "LL-1ztpgv",
        "requestReferenceId": "81369016-0ceb-472b-a841-aaa1edcbefd1",
        "virtualAccountIdentification": "NORTH-VSA",
        "receivedDateTime": "2025-03-27T18:09:40.319+0000"
    }
}

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

Example asynchronous notification: Create a new VSA under an existing parent VSA

Json

{
    "groupHeader": {
        "messageIdentification": "de37af65-5256-414e-b0ae-8994429bdafe",
        "creationDateTime": "2025-03-27T18:09:40.493+0000"
    },
    "originalInformationAndStatus": {
        "clientReferenceId": " LL-1ztpgv ",
        "requestReferenceId": "81369016-0ceb-472b-a841-aaa1edcbefd1",
        "activityType": "CREATE",
        "activityDescription": "New account created",
        "initiatedBy": "API",
        "receivedDateTime": "2025-03-27T18:09:40.439+00:00",
        "completedDateTime": "2025-03-27T18:09:40.439+00:00"
    },
    "currentVirtualAccountDetail": {
        "parentVirtualAccountIdentification": "ALL-REGION-VSA",
        "virtualAccountIdentification": "NORTH-VSA",
        "virtualAccountType": "EVSA",
        "virtualAccountState": "OPEN",
        "accountOptions": {
            "paymentRoutingNumber": {},
            "balanceLimits": {}
        }
    }
}

Create a Virtual Transaction Account

You can use the Wallet API to create a VTA. The process for creating a VTA follows the steps in Create a virtual account.

Requirements

VTA creation requests must adhere to the following requirements:

You can only create one VTA per request.

Important parameters

The following sections list important parameters in the VTA creation request. Not all parameters are listed here—for a complete list, see the API reference.

Header parameters

Include the following parameter in the header.

Header parameters for "Create 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 "Create a VTA" request
Parameter	Required / Optional	Description
`messageIdentification.clientReferenceId`	Required	ID associated with this request that you define. Must be unique.
`virtualAccountDetail.accountOptions.balanceLimits.maximumBalance`	Optional	The account balance will not go above this amount. If not provided, this value is set to your Wallet program's default maximum balance. For more information, see Balance limits.
`virtualAccountDetail.accountOptions.balanceLimits.minimumBalance`	Optional	The account balance will not go below this amount. If not provided, this value is set to your Wallet program's default minimum balance. For more information, see Balance limits.
`virtualAccountDetail.accountOptions.paymentRoutingNumber`	Optional	Set to `true` to assign a PRN to the VTA, or set to `false` to not assign a PRN to the VTA. The default is `false`. For more information, see Payment Routing Numbers (PRNs).
`virtualAccountDetail.parentVirtualAccountIdentification`	Optional	ID of an existing VSA that will be the direct parent of the new VTA. The ID is case-sensitive and must be exact. If you don't provide this, the direct parent of the new VTA will be the top-level VSA, which is identified in the asynchronous notification as the DDA associated with the Wallet program.
`virtualAccountDetail.virtualAccountIdentification`	Required	Unique ID of the new VTA. Maximum 35 characters. Alphanumeric, uppercase and lowercase letters, no special characters except hyphens (`-`).
`virtualAccountDetail.virtualAccountState`	Optional	The state that the VTA is created in. Set to either `PENDING_OPEN` or `OPEN`. The default is `OPEN`.
`virtualAccountDetail.virtualAccountType`	Required	The type of the virtual account. Must be `EVTA`.

Response

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

acknowledgedMessageIdentification
- clientReferenceId: The client reference ID that you submitted in the request.
- requestReferenceId: A request reference ID that the API generates.
- virtualAccountIdentification: The VTA ID that you submitted in the request.
- 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 about the VTA that you created:

originalInformationAndStatus
- clientReferenceId: The reference ID that you provided with the request.
- requestReferenceId: The unique internal request reference ID that Wallet assigned.
- 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 new VTA.
- virtualAccountType: The account type.
- virtualAccountState: The state of the virtual account.
- accountOptions
  - paymentRoutingNumber: PRN information. Null if you didn't assign a PRN. For more information, see Payment Routing Numbers (PRNs).
    - paymentRoutingNumber: The PRN of the virtual account.
    - status: The status of the PRN.
    - country: The country that the PRN is associated with.
    - routingInformation
      - type: The type of routing identifier.
      - value: The routing identifier.
  - balanceLimits: For more information, see Balance limits.
    - minimumBalance: The minimum balance of the virtual account.
    - maximumBalance: The maximum balance of the virtual account.

Examples

The following example request creates a VTA as a direct child of an existing VSA, with no state, with a PRN, and with minimum and maximum balance limits.

Example request body: Create a new VTA

Json

{
    "messageIdentification": {
        "clientReferenceId": "LL-llwb7q"
    },
    "virtualAccountDetail": {
        "parentVirtualAccountIdentification": "NORTH-VSA",
        "virtualAccountIdentification": "SALES-VTA2",
        "virtualAccountState": "",
        "virtualAccountType": "EVTA",
        "accountOptions": {
            "paymentRoutingNumber": "true",
            "balanceLimits": {
                "minimumBalance": "-1.00",
                "maximumBalance": "10000.00"
            }
        }
    }
}

The following is the synchronous response to the previous request.

Example synchronous response: Create a VTA

Json

{
    "acknowledgedMessageIdentification": {
        "clientReferenceId": "LL-llwb7q",
        "requestReferenceId": "caccb5ae-97c9-44f9-b1cc-7d1636a775f6",
        "virtualAccountIdentification": "SALES-VTA2",
        "receivedDateTime": "2025-03-27T15:30:07.505+0000"
    }
}

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

Example asynchronous notification: Create a VTA

Json

{
    "groupHeader": {
        "messageIdentification": "60c6f0ad-828b-4c63-aee0-90584707ec32",
        "creationDateTime": "2025-03-27T15:30:08.363+0000"
    },
    "originalInformationAndStatus": {
        "clientReferenceId": "LL-llwb7q",
        "requestReferenceId": "caccb5ae-97c9-44f9-b1cc-7d1636a775f6",
        "activityType": "CREATE",
        "activityDescription": "New account created",
        "initiatedBy": "API",
        "receivedDateTime": "2025-03-27T15:30:08.291+00:00",
        "completedDateTime": "2025-03-27T15:30:08.291+00:00"
    },
    "currentVirtualAccountDetail": {
        "parentVirtualAccountIdentification": "NORTH-VSA",
        "virtualAccountIdentification": "SALES-VTA2",
        "virtualAccountType": "EVTA",
        "virtualAccountState": "OPEN",
        "accountOptions": {
            "paymentRoutingNumber": {
                "paymentRoutingNumber": "XXXXXXXXXX",
                "status": "ACTIVE",
                "country": "US",
                "routingInformation": [
                    {
                        "type": "ABA",
                        "value": "XXXXXXXXXX"
                    }
                ]
            },
            "balanceLimits": {
                "minimumBalance": "-1.00",
                "maximumBalance": "10000.00"
            }
        }
    }
}