# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# 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](/docs/treasury/jp-morgan-wallet/capabilities/accounts/overview).

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.

1. You submit an API request to create a VSA or 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 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](#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](/api/treasury/jp-morgan-wallet/doc#/operations/createAccountAsync).

#### 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.

```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.

```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.

```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](#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](/api/treasury/jp-morgan-wallet/doc#/operations/createAccountAsync).

#### 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](#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](#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)](#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)](#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](#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.

```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.

```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.

```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"
            }
        }
    }
}
```