--- title: "Issue Virtual Account to Wallet" source_url: https://docs.rapyd.net/en/issue-virtual-account-to-wallet.html lang: en --- # Issue Virtual Account to Wallet Issue a virtual account to an existing wallet. Any bank can transfer money to a wallet using a virtual account number. A virtual account is for one or more currencies. There is no limit to the number of virtual accounts you can issue to a wallet. You can issue multiple virtual accounts in a single currency. When funds are transferred to a virtual account, the funds appear in the wallet’s currency account for the currency of the transfer. You can convert transferred funds to certain currencies. This method triggers [Virtual Account Status Webhook](https://docs.rapyd.net/en/virtual-account-status-webhook.md "Virtual Account Status Webhook"). This webhook is sent whenever the virtual account status changes. > **Note:** > > - This endpoint replaces the deprecated endpoint - `POST /v1/issuing/bankaccounts` > - Rapyd no longer supports the deprecated endpoint. > - The code samples include successful requests (200) and bad requests (400). > > - For error messages that appear due to bad requests (400), see: > > - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors") > - [Virtual Account Errors](https://docs.rapyd.net/en/virtual-account-errors.md "Virtual Account Errors") > - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors"). **Prerequisites** - You must create a wallet. See [Create Wallet](https://docs.rapyd.net/en/create-wallet.md "Create Wallet"). - The identity of the wallet owner must be verified. See [Rapyd Verify](https://docs.rapyd.net/en/rapyd-verify-386565.md "Rapyd Verify"). ### Parameters ### Request Header Parameters - - access_key - Unique access key provided by Rapyd for each authorized user. See [Developers](https://docs.rapyd.net/en/developers.md "Developers"). - - Content-Type - Indicates that the data appears in JSON format. Set to **application/json**. - - idempotency - A unique key that prevents the platform from creating the same object twice. See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency"). - - salt - Random string. Recommended length: 8-16 characters. - - signature - Signature calculated for each request individually. See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures"). - - timestamp - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds). ### Request Body Parameters - - country - Country for the virtual account. Two-letter ISO 3166-1 ALPHA-2 code for the country. To determine the code for a country, see [List Countries](https://docs.rapyd.net/en/list-countries.md "List Countries"). - - currency - Currency for the virtual account. Three-letter ISO 4217 code. See [List Capabilities of Virtual Accounts](https://docs.rapyd.net/en/list-capabilities-of-virtual-accounts.md "List Capabilities of Virtual Accounts"). - - description - Description of the virtual account, as defined by the client. - - ewallet - ID of the Rapyd Wallet that the virtual account is attached to. String starting with **ewallet_**. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - requested_currency - Currency received by the virtual account after conversion. Uppercase. One of the following: - **AUD** - Australian Dollar - **EUR** - Euro - **GBP** - Pound Sterling - **HKD** - Hong Kong Dollar - **SGD** - Singapore Dollar - **USD** - US Dollar When not specified, the funds appear in the wallet’s currency account for the currency of the transaction. ### Response Parameters - - bank_account - Details about the virtual account, including the following fields: - - aba - 9-digit ABA routing number of the virtual account. - - aba_routing_number - 9-digit ABA routing number of the virtual account. - - account_holder - Name of the virtual account holder. - - account_no - The actual account number that was assigned to the virtual account when it was created. - - account_number - The actual account number that was assigned to the virtual account when it was created. - - address - Street address of the branch of the bank that issued the virtual account number. - - beneficiary_name - Name of the owner of the Rapyd Wallet that the virtual account number was issued to. - - bic - [Bank Identifier Code (BIC)](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_bic "Bank Identifier Code") of the virtual account. - - branch_code - Number of the bank branch. - - city - City of the branch of the bank that issued the virtual account number. - - country - Two-letter ISO 3166-1 ALPHA-2 code of the country of the virtual account. - - country_iso - Two-letter ISO 3166-1 ALPHA-2 code of the country of the virtual account. - - iban - [International bank account number (IBAN)](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_iban "International Bank Account Number") of the virtual account. - - payment_type - Method of transferring funds to and from the virtual account. - - sort_code - A six-digit bank identification number. Relevant to certain country-currency combinations. - - currency - Currency for the virtual account. Three-letter ISO 4217 code. - - description - Description of the transaction, as defined by the client. - - ewallet - ID of the Rapyd Wallet that the virtual account is attached to. String starting with **ewallet_**. - - funding_instructions - Reserved. - - id - ID of the virtual account number object. String starting with **issuing_**. - - merchant_reference_id - Identifier defined by the client for reference purposes. Limit: 45 characters. - - metadata - A JSON object defined by the client. See [Metadata](https://docs.rapyd.net/en/metadata.md "Metadata"). - - requested_currency - Currency received by the virtual account after conversion. One of the following: - **AUD** - Australian Dollar - **EUR** - Euro - **GBP** - Pound Sterling - **HKD** - Hong Kong Dollar - **SGD** - Singapore Dollar - **USD** - US Dollar - - status - Indicates the status of the virtual account. - **ACT** - Active. - **CLO** - Closed. - **ERR** - Error. - **PEN** - Pending. - **REJ** - Rejected. - - transactions - List that describes individual transactions in the wallet that were done via the virtual account number. Each object has the following fields: - - id - ID of the transaction. String starting with **isutran_**. - - amount - The amount credited to the virtual account, in units of the currency defined in `currency`. - - created_at - Timestamp for the transaction, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). - - currency - The currency credited to the virtual account. Three-letter ISO 4217 code. - **Transactions without FX** - The currency sent by the sender. - **FX transactions** - Determined by `requested_currency` in the virtual account. - - fx_rate - Currency conversion rate for the transaction. - - original_amount - The amount sent by the sender to the virtual account, in units of the currency defined in `original_currency`. - - original_currency - The currency sent by the sender to the virtual account. Three-letter ISO 4217 code. ### Code Samples - - .NET - ```csharp using System; using System.Text.Json; namespace RapydApiRequestSample { class Program { static void Main(string[] args) { try { var metadata = new { merchant_defined = true }; var requestObj = new { country = "DE", currency = "EUR", description = "Issue virtual account number to wallet", ewallet = "ewallet_cfb416d9108161347d98acf17f3fd3e8", merchant_reference_id = "abcd_09870987", metadata }; string request = JsonSerializer.Serialize(requestObj); string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/virtual_accounts", request); Console.WriteLine(result); } catch (Exception e) { Console.WriteLine("Error completing request: " + e.Message); } } } } ``` - - JavaScript - ```javascript const makeRequest = require('../../../../Utilities/JS/utilities').makeRequest; async function main() { try { const body = { currency: 'EUR', country: 'DE', description: 'Issue virtual account number to wallet', ewallet: 'ewallet_cfb416d9108161347d98acf17f3fd3e8', merchant_reference_id: 'abcd_09870987', metadata: { merchant_defined: 'true', } }; const result = await makeRequest('POST', '/v1/virtual_accounts', body); console.log(result); } catch (error) { console.error('Error completing request', error); }c ``` - - PHP - ```php "EUR", "country" => "DE", "description" => "Issue virtual account number to wallet", "ewallet" => "ewallet_cfb416d9108161347d98acf17f3fd3e8", "merchant_reference_id" => "abcd_09870987", "metadata" => array( "merchant_defined" => true ) ]; try { $object = make_request('post', '/v1/virtual_accounts', $body); var_dump($object); } catch(Exception $e) { echo "Error: $e"; } ?> ``` - - Python - ```python from pprint import pprint from utilities import make_request body = { "currency": "EUR", "country": "DE", "description": "Issue virtual account number to wallet", "ewallet": "ewallet_cfb416d9108161347d98acf17f3fd3e8", "merchant_reference_id": "abcd_09870987", "metadata": { "merchant_defined": True } } results = make_request(method='post', path=f'/v1/virtual_accounts', body=body) pprint(results)rom pprint import pprint from utilities import make_request invoice_item = { "currency": "USD", "customer": "cus_b3b8ad0174f4c415c663b35bcf542192", "metadata": { "merchant_defined": True }, "amount": 10 } result = make_request(method='post', path='/v1/invoice_items', body=invoice_item) pprint(result) ``` - /v1/virtual_accounts - Issue Virtual Account Number to Wallet - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/virtual_accounts' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "currency": "EUR", "country": "DE", "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "e743b79d-584d-42ef-bb93-865133c0a73d" }, "data": { "id": "issuing_d11d404c919519c66ac61e14389f766a", "merchant_reference_id": "issuing_d11d404c919519c66ac61e14389f766a", "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861", "bank_account": { "beneficiary_name": "CashDash UK Limited", "address": "Northwest House, 119 Marylebone Road NW1 5PU", "country_iso": "DE", "iban": "DE07202208000092780641", "bic": "SXPYDEHH" }, "metadata": {}, "status": "ACT", "description": null, "funding_instructions": null, "currency": "EUR", "requested_currency": null, "transactions": [] } } ``` - Issue Virtual Account Number - Requested Currency - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/virtual_accounts' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "currency": "EUR", "country": "DE", "ewallet": "ewallet_31fb2dbbaf6519461ee4fbe1062220d3", "requested_currency": "USD" }' ``` - ```json { "status": { "error_code": "", "status": "SUCCESS", "message": "", "response_code": "", "operation_id": "87412c51-8aef-450a-8a48-fb00ef50c3c8" }, "data": { "id": "issuing_44d4ced27e293bfc8464792b3329df94", "merchant_reference_id": "issuing_44d4ced27e293bfc8464792b3329df94", "ewallet": "ewallet_31fb2dbbaf6519461ee4fbe1062220d3", "bank_account": { "beneficiary_name": "CashDash UK Limited", "address": "Northwest House, 119 Marylebone Road NW1 5PU", "country_iso": "DE", "iban": "DE07202208000092780641", "bic": "SXPYDEHH" }, "metadata": {}, "status": "ACT", "description": null, "funding_instructions": null, "currency": "EUR", "requested_currency": "USD", "transactions": [] } } ``` - Bad Request - Currency Mismatch - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/virtual_accounts' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "currency": "PHP", "country": "ZA", "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861" }' ``` - ```json { "status": { "error_code": "ERROR_ISSUING_BANK_ACCOUNT_COUNTRY_CURRENCY_MISMATCH", "status": "ERROR", "message": "The request tried to issue a virtual account number to a wallet, but the currency is not supported for the country provided. The request was rejected. Corrective action: Contact Client Support.", "response_code": "ERROR_ISSUING_BANK_ACCOUNT_COUNTRY_CURRENCY_MISMATCH", "operation_id": "af127d8a-d389-4e4d-a41b-5c6f2ebc292a" } } ``` - Bad Request - Requested Currency Not Valid - ```curl curl -X post 'https://sandboxapi.rapyd.net/v1/virtual_accounts' \ -H 'access_key: your-access-key-here' \ -H 'Content-Type: application/json' \ -H 'idempotency: your-idempotency-parameter-here' \ -H 'salt: your-random-string-here' \ -H 'signature: your-calculated-signature-here' \ -H 'timestamp: your-unix-timestamp-here' \ --data-raw '{ "currency": "EUR", "requested_currency": "PHP", "country": "DE", "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861" }' ``` - ```json { "status": { "error_code": "ERROR_UNSUPPORTED_REQUESTED_CURRENCY", "status": "ERROR", "message": "Unsupported requested currency.", "response_code": "ERROR_UNSUPPORTED_REQUESTED_CURRENCY", "operation_id": "d2f1838d-8919-45a7-95f5-ddb6c4914547" } } ```