> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.redpincompany.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.redpincompany.com/_mcp/server.

# Request a virtual account

POST https://sandbox.currenciesdirect.com/v1/customers/{customer_id}/virtual-accounts
Content-Type: application/json

Virtual accounts are unique, bank routing instructions which are assigned to an individual customer (can be a personal customer or a business customer). Virtual Accounts will be available in a number of currencies. Please contact your Account Manager or Implementation Manager for more information. Virtual accounts can be requested for registered and active customers.

This will initiate the process of creating a virtual account for the customer.

**Using the Response:**
The response includes a `unique_identifier` that you can use to retrieve the virtual account details. After creating a virtual account, use the `unique_identifier` from the response with the `unique-ref` query parameter in the [View a virtual account](/api-reference/customers/api-integration/virtual-accounts/get-virtual-account-by-vban#request.query.unique-ref) endpoint to get the complete virtual account details.

**Example:**

```bash
# Step 1: Create virtual account
POST /v1/customers/{customer_id}/virtual-accounts
Request Body:
{
  "currency": "EUR",
  "vban_country": "USA"
}
Response: { "unique_identifier": "6d23072a-ac3e-4146-9b83-7ad384d65707" }

# Step 2: Get virtual account details using unique_identifier
GET /v1/customers/{customer_id}/virtual-accounts?unique-ref=6d23072a-ac3e-4146-9b83-7ad384d65707
```

**Authentication:** [Bearer token required](/api-guide/getting-started/authentication#oauth-20-authentication)

Reference: https://docs.redpincompany.com/api-reference/customers/api-integration/virtual-accounts/request-virtual-account

## Authentication

- `Authorization` header (bearer token, required) — OAuth 2.0 Bearer token authentication. This API uses OAuth 2.0 Client Credentials flow. Please refer to the [Authentication](/api-guide/getting-started/authentication#oauth-20-authentication) section for detailed information on how to obtain and use your OAuth credentials.

## Servers

- `https://sandbox.currenciesdirect.com` (Sandbox, default)
- `https://api.redpincompany.com` (Production)

## Request

### Path parameters

- `customer_id` (string, required) — Unique Customer Identifier

### Body (application/json)

This endpoint expects a VirtualAccountRequest.

- `currency` (string, required) — Three-letter currency code as per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217).
- `vban_country` (string, optional) — Three-letter country code as per [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3). Mandatory for EUR & GBP virtual accounts.

## Response

### 201

Ok. A virtual account creation process has been initiated.

- `unique_identifier` (string, required) — Unique identifier to identify this virtual account in future. Use this identifier with the `unique-ref` query parameter in the [View a virtual account](/api-reference/customers/api-integration/virtual-accounts/get-virtual-account-by-vban#request.query.unique-ref) endpoint to retrieve the complete virtual account details including account number, bank details, and status. **Usage Example:** ```bash GET /v1/customers/{customer_id}/virtual-accounts?unique-ref={unique_identifier} ```

## Errors

### 400 Bad Request Error

Bad request - invalid parameters

- `code` (string, required)
- `description` (string, required) — Human-readable error description
- `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication
  - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR`
- `field` (string, optional)
- `details` (map from string to any, optional) — Additional details about the error
- `timestamp` (datetime, optional)

### 401 Unauthorized Error

Unauthorized - invalid authorization header

- `code` (string, required)
- `description` (string, required) — Human-readable error description
- `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication
  - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR`
- `field` (string, optional)
- `details` (map from string to any, optional) — Additional details about the error
- `timestamp` (datetime, optional)

### 404 Not Found Error

Customer not found

- `code` (string, required)
- `description` (string, required) — Human-readable error description
- `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication
  - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR`
- `field` (string, optional)
- `details` (map from string to any, optional) — Additional details about the error
- `timestamp` (datetime, optional)

### 500 Internal Server Error

Internal Server Error

- `code` (string, required)
- `description` (string, required) — Human-readable error description
- `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication
  - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR`
- `field` (string, optional)
- `details` (map from string to any, optional) — Additional details about the error
- `timestamp` (datetime, optional)

## Examples

**Request**

```json
{
  "currency": "EUR",
  "vban_country": "USA"
}
```

**Response**

```json
{
  "unique_identifier": "6d23072a-ac3e-4146-9b83-7ad384d65707"
}
```

**SDK Code**

```shell cURL
curl -X POST https://sandbox.currenciesdirect.com/v1/customers/{customerId}/virtual-accounts \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

```

```python Request a virtual account
import requests

url = "https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/virtual-accounts"

payload = {
    "currency": "EUR",
    "vban_country": "USA"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Request a virtual account
const url = 'https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/virtual-accounts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"currency":"EUR","vban_country":"USA"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Request a virtual account
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/virtual-accounts"

	payload := strings.NewReader("{\n  \"currency\": \"EUR\",\n  \"vban_country\": \"USA\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Request a virtual account
require 'uri'
require 'net/http'

url = URI("https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/virtual-accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"currency\": \"EUR\",\n  \"vban_country\": \"USA\"\n}"

response = http.request(request)
puts response.read_body
```

```java Request a virtual account
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/virtual-accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"currency\": \"EUR\",\n  \"vban_country\": \"USA\"\n}")
  .asString();
```

```php Request a virtual account
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/virtual-accounts', [
  'body' => '{
  "currency": "EUR",
  "vban_country": "USA"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Request a virtual account
using RestSharp;

var client = new RestClient("https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/virtual-accounts");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"currency\": \"EUR\",\n  \"vban_country\": \"USA\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Request a virtual account
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "currency": "EUR",
  "vban_country": "USA"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox.currenciesdirect.com/v1/customers/cust_123456789/virtual-accounts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```