Payin via Virtual Account

Overview

Assign a bank account number (e.g., IBAN, ACH routing number) to a given customer to receive repeatable fiat deposits which are automatically converted to the defined CryptoCurrency and optionally withdrawn to a customer's DestinationAddress using the Bank deposit to onchain address endpoint. For more details on this product, see the Payin via Virtual Account Product page.

1. Set Up the Environment

Register Your Interest

Authenticate & Request Signing

For guidance on generating and configuring your API keys, see the Authentication page.

Generate your Sandbox API key via the Business Dashboard.
Include your API key in the X-Api-Key header of all requests.
Request Signing is optional in Sandbox and required in Production. It is important to setup Request Signing before migrating to Production, to do this see the Request Signing page.

Configure Webhooks

For guidance on webhook subscriptions and configuration, see the Configuration page.

Optionally whitelist NOAH's Webhook IP addresses, detailed on the Whitelisting section.
Create a webhook subscription for the following event types, the details required to ingest the webhooks are also available on their respective pages.
- FiatDeposit - see FiatDeposit Event.
- Transaction - see Transaction Event.

tip

Throughout the Bank Onramp Workflow, you will receive three webhook events:

FiatDeposit - to notify you when the customer has sent a fiat payment to their assigned bank account number.
Cryptocurrency purchase Transaction event type - to notify you when the fiat has been converted to your chosen CryptoCurrency and credited to your NOAH Account.
Cryptocurrency withdrawal Transaction - to notify you when the funds have been withdrawn to your customer's DestinationAddress.

2. Create a Customer

Create a customer, if not already created, via the PUT Customers endpoint.

curl -L -X PUT 'https://api.sandbox.noah.com/v1/customers/:CustomerID' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
--data-raw '{
  "Type": "Individual",
  "FullName": {
    "FirstName": "string",
    "LastName": "string",
    "MiddleName": "string"
  },
  "DateOfBirth": "2024-04-16",
  "Email": "user@example.com",
  "PhoneNumber": "string",
  "Identities": [
    {
      "IssuingCountry": "DE",
      "IDNumber": "string",
      "IssuedDate": "2024-04-16",
      "ExpiryDate": "2024-04-16",
      "IDType": "Passport"
    }
  ],
  "PrimaryResidence": {
    "Street": "string",
    "Street2": "string",
    "City": "string",
    "PostCode": "string",
    "State": "string",
    "Country": "DE"
  }
}'

For details, see the PUT Customers endpoint.

tip

When integrating under the Reliance Model, you must ensure that any customer executing a transaction has a valid and complete KYC Status in your system.
Ensure your CustomerID is stored against the compliance profile of the same customer, to reference when creating transactions.

3. Call the Workflow Endpoint

Call the Bank Onramp Workflow endpoint, passing the following data:

CustomerID: pertaining to the customer initiating the Onramp.
Transaction Details: including the FiatCurrency, CryptoCurrency, withdrawal Network and DestinationAddress

PolygonTestAmoy Example

curl -L -X PUT 'https://api.sandbox.noah.com/v1/customers/:CustomerID' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
--data-raw '{
  "CustomerID": "321434324",
  "FiatCurrency": "EUR",
  "CryptoCurrency": "USDC_TEST",
  "Network": "PolygonTestAmoy",
  "DestinationAddress": {
    "Address": "0x370206496048f4eDbe60e3AcBD4CFEC50B2433bd"
  }
}'

SolanaDevnet Example

curl -L -X PUT 'https://api.sandbox.noah.com/v1/customers/:CustomerID' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <X-Api-Key>' \
--data-raw '{
  "CustomerID": "6482917350",
  "FiatCurrency": "EUR",
  "CryptoCurrency": "USDC_TEST",
  "Network": "SolanaDevnet",
  "DestinationAddress": {
    "Address": "ANVUJaJoVaJZELtV2AvRp7V5qPV1B84o29zAwDhPj1c2"
  }
}'

tip

In the Sandbox environment, you have Testnet networks available to you, as can be seen above for PolygonTestAmoy and SolanaDevnet, while note also that NOAH subsidises the Network fees on Polygon and Solana.
Testnet faucets typically only drip small amounts of tokens to prevent abuse, which severely limits testing scenarios involving larger transactions or complex workflows. By deploying the USDC_TEST cryptocurrency, as used in the examples above, NOAH removes these constraints and enables developers to conduct comprehensive testing with realistic transaction volumes, stress test applications properly, and simulate real-world scenarios without constantly waiting for faucet refills.

You will receive a 200 response to indicate that the bank account number has been assigned to the customer and is prepared to accept a fiat deposit. In the example below, all numbers are replaced by zeroes.

{
    "AccountHolderName": "NOAH Savings UAB",
    "AccountNumber": "DE00000000000000000000",
    "BankAddress": {
        "City": "Munich",
        "Country": "DE",
        "PostCode": "00000",
        "State": "BY",
        "Street": "Maximilianstrasse 00"
    },
    "BankCode": "SXPYDEHHXXX",
    "BankName": "BANKING CIRCLE S.A.",
    "PaymentMethodID": "Bank/Sepa/EUR/SXPYDEHHXXX/DE0000000000000000000/000000000",
    "PaymentMethodType": "BankSepa"
}

4. Receive the Webhook Events

Receive the FiatDeposit Webhook

You will receive a FiatDeposit event type when a customer performs a fiat Deposit into their assigned bank account number. See FiatDeposit Event.

tip

Simulate a Fiat Deposit (Sandbox Only)

In the Sandbox environment you can simulate a fiat deposit, to trigger the remaining webhooks and transactions.

Use the PaymentMethodID retrieved from Step 4. to call the Simulate fiat Deposit endpoint.
This will trigger a FiatDeposit event, and the automated workflow will continue to the cryptocurrency purchase step.

Receive the Transaction Webhooks

You will receive a Transaction event when NOAH completes the fiat to Crypto exchange. See Transaction Event.
You will receive a second Transaction event when NOAH completes the Crypto Withdrawal to the customer's DestinationAddress.

Guardrails

Your customers may use their individually assigned Virtual Accounts for use cases that comply with the Guardrails below.

EUR Virtual Accounts

Receive First-Party Deposits from

The customer’s own bank, fintech app, or brokerage account.

Receive Third-Party Deposits from

Registered businesses sending EUR from a domestic business account
A close friend or family member’s bank account

Limits

Single-transaction limit: 15 000 EUR — any transaction that exceeds this limit triggers an Enhanced Due Diligence (EDD) review.
Monthly aggregated limit: 30 000 EUR — the transaction that pushes a customer over this volume triggers an EDD review.

USD Virtual Accounts

Non-US-Resident Customers

Receive First-Party Deposits from

The customer’s bank, fintech app, or brokerage account.

Receive Third-Party Deposits from

Registered businesses sending USD from a domestic business account
A family member’s bank account where the customer shares a surname
Non-family members up to 5 000 USD — any transaction that exceeds this limit triggers an EDD review

US-Resident Customers

Receive First-Party Deposits from

The customer’s bank, fintech app, or brokerage account.

Receive Third-Party Deposits from

Registered businesses sending USD from a domestic business account

Limits (apply to all USD Virtual Accounts)

Single-transaction limit: 10 000 USD — any transaction that exceeds this limit triggers an EDD review.
Monthly aggregated limit: 20 000 USD — the transaction that pushes a customer over this volume triggers an EDD review.

Enhanced Due Diligence (EDD) Process

When an EDD review is triggered, NOAH’s Compliance team will request documentation according to the KYC model your business uses.

Model	Who receives the Request for Information (RFI)	Information requested
Reliance Model	Your compliance team	• Proof of Source of Funds (SoF) • Full KYC pack • Purpose of the transaction
Standard Model	Your customer (via the email address on file)	• Proof of Source of Funds (SoF) • Purpose of the transaction

Deposits requiring EDD are frozen at the FiatDeposit step until the requested information is received. Once EDD is completed, funds are unfrozen, converted to the defined cryptocurrency, and withdrawn to the customer’s DestinationAddress. If the documents are not provided within 10 days of the RFI, the transaction will be rejected and the funds automatically refunded.

Important Note

NOAH reserves the right, at its sole discretion, to:

Request further information and/or documentation for any payment made by a third party; and
Amend and/or update these Guardrails from time to time.

Overview​

Register Your Interest​

Authenticate & Request Signing​

Configure Webhooks​

PolygonTestAmoy Example​

SolanaDevnet Example​

Receive the FiatDeposit Webhook​

Simulate a Fiat Deposit (Sandbox Only)​

Receive the Transaction Webhooks​

Guardrails​

EUR Virtual Accounts​

Receive First-Party Deposits from​

Receive Third-Party Deposits from​

Limits​

USD Virtual Accounts​

Non-US-Resident Customers​

Receive First-Party Deposits from​

Receive Third-Party Deposits from​

US-Resident Customers​

Receive First-Party Deposits from​

Receive Third-Party Deposits from​

Limits (apply to all USD Virtual Accounts)​

Enhanced Due Diligence (EDD) Process​

Important Note​

Overview

Register Your Interest

Authenticate & Request Signing

Configure Webhooks

PolygonTestAmoy Example

SolanaDevnet Example

Receive the FiatDeposit Webhook

Simulate a Fiat Deposit (Sandbox Only)

Receive the Transaction Webhooks

Guardrails

EUR Virtual Accounts

Receive First-Party Deposits from

Receive Third-Party Deposits from

Limits

USD Virtual Accounts

Non-US-Resident Customers

Receive First-Party Deposits from

Receive Third-Party Deposits from

US-Resident Customers

Receive First-Party Deposits from

Receive Third-Party Deposits from

Limits (apply to all USD Virtual Accounts)

Enhanced Due Diligence (EDD) Process

Important Note