Rapyd Docs and API Reference

Virtual Account Numbers

Accept Payments Locally. | Enterprise

Suggest Edits

Create a virtual account number to efficiently collect cross border payments from your customers. Rapyd’s virtual account numbers are multi-use in nature so customers can use the same number to send repeated payments over a long period of time.

When a virtual account number is created it is linked to a wallet account and each wallet can have multiple virtual accounts. This structure makes it easier to identify incoming payments and to group numerous payments into a single wallet which can simplify reconciliation. Virtual account numbers are active as long as the wallet account is active.

Rapyd currently supports vIBANs in Europe and local bank account formats in other markets that do not use the IBAN standard.

When creating your virtual account number, be sure to generate it with the country code you expect your customers to send payment to, considering that a payer may have international charges depending on their location and their own bank's policies.

Please refer to the table below for country codes and the currencies supported in each market.

Country CodeSupported Currencies
USUSD
GBGBP
DEEUR *
DKAED, AUD, CAD, CHF, CZK, DKK, HKD, HRK, HUF, ILS, JPY, MXN, NOK, NZD, PLN, RON, SAR, SEK, SGD, TRY, USD, ZAR
MXMXN
SGSGD, USD, AUD, CAD, CHF, EUR, GBP, HKD, JPY, NOK, NZD, SEK
AUAUD, USD
NZNZD, USD
IDIDR

*Receive EUR transfers across 36 countries within the SEPA region

Note: You do not need to be in the country specified in order to create a virtual account number utilizing that country code.

For example, a customer owns a wallet as described in Creating a Rapyd Wallet. The customer wants their wallet to have a virtual account number so that they can transfer money directly into the wallet. The customer provides information requested by your website or mobile application, and he receives a bank account number for their wallet.

936936

Virtual Account Number Workflows

1. Issuing a Virtual Account Number to a Wallet

20642064
  1. A customer on your website or mobile app requests a virtual bank account number for the customer's wallet, and provides the required information.
  2. The back end asks Rapyd to issue a virtual bank account number to the wallet.
  3. Rapyd issues the virtual bank account number and returns a confirmation to your back end.
  4. You display the bank account number to the customer.

2. Receiving Funds into the Virtual Account Number

The same customer wants to make a new payment through the Virtual Account.

25822582
  1. You call List Virtual Accounts by Rapyd Wallet.
  2. Rapyd returns the Virtual Account Number details.
  3. You present to the Virtual Account Number including account ID to the customer.
  4. The customer sends funds to the Virtual Account Number Details.
  5. Rapyd sends you a webhook notification of the deposited funds.

How It Works

👍

Prerequisites

To run the examples of this use case, you must create the following ID in your own sandbox:

Issuing a Virtual Account Number to the Wallet

You ask Rapyd to issue a Virtual Account number to the customer's wallet.

For that, you'll use Issue Virtual Account Number to Wallet with the following parameters:

Body ParameterDescription
ewalletEnter the wallet 'id' that you received when you created the wallet in your sandbox. For purposes of this use case lesson, we are using ewallet_45c238c0d8882467128318e6a4977eed, which is the wallet ID we created in our sandbox.
countryEnter GB as the country code for Great Britain, where the customer lives.
currencyEnter GBP as the currency code for Pounds.
descriptionEnter Issuing virtual account number to wallet as a comment.

Issue Virtual Account Number to Wallet Request

You ask Rapyd to issue the Virtual Account number to the wallet.

// Request URL: POST https://sandboxapi.rapyd.net/v1/issuing/bankaccounts

// Message body:
{
  "currency": "GBP",
  "country": "GB",
  "description": "Issuing bank account number to wallet",
  "ewallet": "ewallet_45c238c0d8882467128318e6a4977eed"
}

using System;
using System.Text.Json;

namespace RapydApiRequestSample
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                var requestObj = new
                {
                    country = "SK",
                    currency = "EUR",
                    description = "Issuing bank account number to wallet",
                    ewallet = "ewallet_45c238c0d8882467128318e6a4977eed"
                 };

                string request = JsonSerializer.Serialize(requestObj);

                string result = RapydApiRequestSample.Utilities.MakeRequest("POST", "/v1/issuing/bankaccounts", request);
                Console.WriteLine(result);
            }
            catch (Exception e)
            {
                Console.WriteLine("Error completing request: " + e.Message);
            }
        }
    }
}

const makeRequest = require('<path-to-your-utility-file>/utilities').makeRequest;

async function main() {
  try {
    const body = {
      currency: 'EUR',
      country: 'SK',
      description: 'Issuing bank account number to wallet',
      ewallet: 'ewallet_45c238c0d8882467128318e6a4977eed'
    };
    const result = await makeRequest('POST', '/v1/issuing/bankaccounts', body);

    console.log(result);
  } catch (error) {
    console.error('Error completing request', error);
  }
}

<?php
$path = $_SERVER['DOCUMENT_ROOT'];
$path .= "/<path-to-your-utility-file>/utilities.php";
include($path);

$body = [
    'currency' => 'EUR',
    'country' => 'SK',
    'description' => 'Issuing bank account number to wallet',
    'ewallet' => 'ewallet_45c238c0d8882467128318e6a4977eed'
];

try {
    $object = make_request('post', '/v1/issuing/bankaccounts', $body);
    var_dump($object);
} catch (Exception $e) {
    echo "Error: $e";
}
?>

from pprint import pprint

from utilities import make_request

body = {
    "currency": "EUR",
    "country": "SK",
    "description": "Issuing bank account number to wallet",
    "ewallet": "ewallet_45c238c0d8882467128318e6a4977eed",
}

results = make_request(method='post', path=f'/v1/issuing/bankaccounts', body=body)
pprint(results)

Issue Virtual Account Number to Wallet Response

Let's take a look at the response. Issue Virtual Account Number to Wallet describes the fields in the response.

{
    "status": {
        "error_code": "",
        "status": "SUCCESS",
        "message": "",
        "response_code": "",
        "operation_id": "6ccb0572-93ad-4dbf-b419-76b14876c29d"
    },
    "data": {
        "id": "issuing_64c7c4c32189fa8689ec9fe050aff3d9",
        "merchant_reference_id": "issuing_64c7c4c32189fa8689ec9fe050aff3d9",
        "ewallet": "ewallet_45c238c0d8882467128318e6a4977eed",
        "bank_account": {
            "Iban": "GB3645888045987523520112"
        },

        // ...  
          
        "status": "ACT",
        "description": "Issuing bank account number to wallet",
        "currency": "GBP",
        "transactions": []
    }
}

The data section of this response shows:

  • The Rapyd ID of the wallet's bank account number is issuing_9bbf12953cbaa15b7c2a51584e3d4145. Since the request did not specify a reference ID, this number is also used for merchant_reference_id. When you run this example in your own sandbox, you will get a different ID.
  • ewallet is the ID of the customer's wallet.
  • The bank_account in this case has an IBAN with the number GB3376599444263666923298.
  • The currency is GBP.
  • The status is ACT. This means that the bank account number is active.

Your website shows the customer a confirmation and the bank account number.

Issue Virtual Account Number for Rapyd Wallet (Singapore)

More examples are included below for additional countries, Singapore and and Denmark. 

{
   "currency": "SGD",
   "country": "SG",
   "description": "Issue bank account number to wallet",
   "ewallet": "ewallet_3d03be4b6ed60a217fb1faa7c01ae2ca",
   "merchant_reference_id": "bankaccountnumber12345543",
   "metadata": {
       "merchant_defined": true
   }
}

{
   "currency": "SGD",
   "country": "DK",
   "description": "Issue bank account number to wallet",
   "ewallet": "ewallet_3d03be4b6ed60a217fb1faa7c01ae2ca",
   "merchant_reference_id": "bankaccountnumber12345543",
   "metadata": {
       "merchant_defined": true
   }
}

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "63e2bb39-8087-4d94-9d7d-89070efc701a"
   },
   "data": {
       "id": "issuing_96671e3831b29f9af01202a47c872203",
       "merchant_reference_id": "bankaccountnumber12345543",
       "ewallet": "ewallet_3d03be4b6ed60a217fb1faa7c01ae2ca",
       "bank_account": {
           "beneficiary_name": "Rapyd Holdings Pte Ltd",
           "address": "12 Marina Boulevard, DBS Asia Central, Marina Bay Financial Center Tower 3",
           "country_iso": "SG",
           "bank": "DBS Bank",
           "zip": "018892",
           "country": "Singapore",
           "account_number": "8850780138613670",
           "bic": "DBSSSGSGXXX"
       },
       "metadata": {
           "merchant_defined": true
       },
       "status": "ACT",
       "description": "Issue test bank account",
       "funding_instructions": null,
       "currency": "SGD",
       "transactions": []
   }
}

{
   "status": {
       "error_code": "",
       "status": "SUCCESS",
       "message": "",
       "response_code": "",
       "operation_id": "7db8425e-64a2-49bd-bcc0-dab00fba9cc5"
   },
   "data": {
       "id": "issuing_cf1359c4812a4f3f01db92a76b583b79",
       "merchant_reference_id": "bankaccountnumber12345543",
       "ewallet": "ewallet_3d03be4b6ed60a217fb1faa7c01ae2ca",
       "bank_account": {
           "beneficiary_name": "CashDash UK Limited",
           "address": "Northwest House, 119 Marylebone Road NW1 5PU",
           "country_iso": "DK",
           "iban": "DK4289000092780662",
           "bic": "SXPYDKKK"
       },
       "metadata": {
           "merchant_defined": true
       },
       "status": "ACT",
       "description": "Issue test bank account",
       "funding_instructions": null,
       "currency": "SGD",
       "transactions": []
   }
}

The data section of this response shows:

  • The Rapyd ID of the wallet's Virtual Account number in Singapore is issuing_96671e3831b29f9af01202a47c872203.
  • The Rapyd ID of the wallet's Virtual Account number in Denmark is issuing_cf1359c4812a4f3f01db92a76b583b79.
  • The merchant_reference_id is also bankaccountnumber12345543 When you run this example in your own sandbox, you will get a different ID.
  • ewallet is the ID of the customer's wallet.
  • The bank account in Singapore is an account_number 8850780138613670.
  • The bank account in Denmark has an IBAN with the number DK4289000092780662.
  • Both accounts have a BIC assigned to them. DBSSSGSGXXX (Singapore) or SXPYDKKK (Denmark).
  • The currency is SGD.
  • The status is ACT. This means that the bank account number is active.

Updated about a month ago

Virtual Account Numbers

Accept Payments Locally. | Enterprise

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.