VA Deposit Fee Calculation Guide

When external funds are deposited into your DogPay Virtual Account (VA), the system charges a deposit fee. This fee is not a fixed number; it is dynamically determined by three conditions: Account Type, Clearing Network, and Sender Name Match.

📘

Prerequisite: Where to query fee rates?

Before conducting any calculations, you need to call the Get entity fees endpoint to query the current fee rate configuration in the system.

Parameter field logic:

1. Specify business category (feeTypes): The fixed business code for deposit handling fees is va005_funding_fee. Please pass this into the feeTypes field (for more business codes, refer to the Fee Code Dictionary).
2. Filter specific conditions (condition): This is an optional field. If you do not pass condition in the request, the endpoint will return all fee configurations under the va005_funding_fee category by default. If you pass a specific "fee key" listed in the tables below (such as va_005_cross_percent), the endpoint will precisely filter and return the fee value for that specific condition.

Core Calculation Formula ⚙️

DogPay's deposit fee adopts a combination model of "Percentage Fee + Fixed Fee per Transaction".

Regardless of how the funds are transferred, the final Total Fee calculation formula is always:

Total Deposit Fee = (Total Deposit Amount × Percentage Fee Value) + Fixed Fee Value

How to Choose the Correct "Condition Key (condition)"? 📋

There are many condition keys in the system. Which one should you use? It depends on the following three conditions:

1. Account Type: Are you opening an account for a Business or an Individual?
2. Clearing Network:
   • SWIFT: This is for international cross-border transfers (referred to as cross in the system).
   • ACH / WIRE: This is for local US transfers (referred to as local in the system).
3. Homonymous vs. Non-homonymous:
   • Homonymous (POBO): The name on the sender's bank account matches the name on your DogPay Virtual Account. In this case, use the key with the _pobo suffix.
     • Example: Your DogPay VA name is ABC LLC, and the incoming funds are also sent from an external bank account named ABC LLC.
   • Non-homonymous (Standard): The sender's name is different from the Virtual Account's name. In this case, directly use the standard key without any suffix.
     • Example: Your DogPay VA name is ABC LLC, but the incoming funds are sent by a client named John Doe or XYZ Corp.

Below are the specific keys you need to pass to the condition field based on different scenarios.

1. Business Account (Business VA) Fee Keys

🚧

Business Local Network

For business accounts, although ACH and WIRE both belong to local transfers and share the same "Percentage Key", the WIRE network possesses its own exclusive and independent fixed fee key: va_005_local_cnt_wire.

2. Individual Account (Individual VA) Fee Keys

❗

Individual Account Billing

ACH and WIRE for individual accounts are completely bundled together at the system level. They not only share the same "Percentage Key", but also the same "Fixed Fee Key", with no exclusive key for WIRE.

Practical Demonstration: Calculating Two Deposits 💡

To give you a clearer understanding, let's look at two specific examples:

Scenario 1: Non-homonymous (Standard) + SWIFT Suppose one of your Business clients receives a deposit of 10,000 USD. The transfer uses the SWIFT network, and the sender is "Zhang San," which differs from the business name and is therefore Non-homonymous.

1. Call the get fee rates endpoint and set feeTypes = va005_funding_fee.
2. You can choose not to pass condition to pull the full list and filter locally, or set condition to va_005_cross_percent and va_005_cross_cnt respectively to initiate precise queries.
3. Assume the API returns: a percentage of 0.1% and a fixed fee of 15 USD.
4. Apply the formula: (10,000 USD × 0.1%) + 15 USD = 25 USD.

Scenario 2: Homonymous (POBO) + WIRE Suppose the same Business client transfers 5,000 USD to themselves using an external bank account with a matching name (Homonymous) via the WIRE network.

1. Call the get fee rates endpoint and set feeTypes = va005_funding_fee.
2. Perform a precise query or locate the two keys va_005_local_percent_pobo and the WIRE-exclusive va_005_local_cnt_wire in the full list.
3. Assume the API returns: a percentage of 0.05% and a fixed fee of 10 USD.
4. Apply the formula: (5,000 USD × 0.05%) + 10 USD = 12.5 USD.

Deposit Crediting and Webhook Notifications 🔔

When external funds are deposited, the system will send you a Webhook event notification. You can refer to the VA Transaction Events documentation to parse the pushed data.

In the JSON data received, you will see the following key amount fields, and their relationship is as follows:

• totalAmount: The total amount of this transaction (i.e., the original amount sent externally).
• settleAmount: The settlement amount, which is always equal to the totalAmount.
• fee: The separately deducted handling fee (which is the value we just calculated using the formula).

❗

Actual Credited Amount & Insufficient Funds

The actual money added to the user's Virtual Account balance is the net amount after deducting the fee. The calculation method is: Actual Credited Amount = settleAmount - fee.

Extreme Case: What if the fee is higher than the deposited amount? When the deposit amount is insufficient to cover the handling fee (i.e., fee > settleAmount), during the system review phase, this deposit will be marked as failed or switched to offline processing. Rest assured, even if processed offline, the system will still send a Webhook notification to you via the update event, ensuring you can synchronize the latest status.