/rechargeCard is called to top up a prepaid card?/rechargeCard to top up a prepaid card./refundCard returns the card balance to the account, is the top-up fee already charged refunded?/refundCard only returns the card balance to the VM main account and does not refund any account funding fee already charged.product_code or BIN does the card issuance fee apply to?| Fee Type | Billing Rule |
|---|---|
| Authorization or failed transaction fee | Card groups VC102/VC110/VC113: 0.20 USD per transaction; card group VC105: 0.30 USD per transaction. |
| Merchant refund fee | A 10% merchant refund fee is charged on all card BINs and deducted from the main account. |
| Decline or dispute fee | A declined transaction is treated as a failed transaction, with the same fee as the authorization or failed transaction fee; a chargeback transaction is charged 35 USD each. |
| Cross-border transaction fee and FX conversion fee | Not charged. |
| Card balance return fee | Not charged. |
| Account withdrawal or fund transfer-out fee | When the VM main account balance is withdrawn to an external wallet, 4% of the withdrawal amount + 3 is charged. |
Sections 2.1–2.3 apply to v1 only. v2 requires no IP whitelist and no public/private key configuration; requests are submitted as plaintext JSON and the response datais a plaintext JSON object. v2 users can skip this section.
{
"content": "RSA ciphertext"
}content payload?{"content":"RSA ciphertext"} format, including:/createCard/cardDetail/freezeCard/deleteCard/rechargeCard/refundCard/cardTransaction/updateCardLimit/getCardList/getCardFlow/getProductCode and /getAccountBalance have no business request body and may be called with an empty body.data always encrypted in a successful response?/getAccountBalance, /createCard, /cardDetail, /rechargeCard and /refundCard?json.dumps(data) and then UTF-8 encoded./getAccessToken (/v2/getAccessToken for v2) currently uses app_id and app_secret to obtain a Token. The rules are the same for v1 and v2.| Question | Answer |
|---|---|
Should the Authorization header contain the Token directly, or Bearer <token>? | Fill in the Token directly, without the Bearer format. |
Is expired_time a Unix timestamp in seconds? | Yes. |
| What is the default Token validity period? | 7200 seconds. |
| Is it recommended to obtain a new Token before expiry? | It is recommended to obtain one at least 600 seconds in advance. |
| How should the old Token be handled after obtaining a new one? | Switch to the latest Token immediately after obtaining it. |
| What is the revocation and rotation process for the App Secret and Token? | To rotate the App Secret or Token, please contact VMCard technical support. |
Can app_secret be submitted in a POST body or by another method? | No. /getAccessToken is currently a GET route and obtains a Token through the app_id and app_secret parameters. |
X-Client-Request-Id.X-Client-Request-Id applies to all APIs, including card issuance, top-up, balance return, limit modification and card deletion.-, _, ., : are allowed.AppId + ClientRequestId.Duplicate Client Request Id, whether or not the parameters are the same.Duplicate Client Request Id.X-Client-Request-Id is used for request de-duplication, but it is not currently a stable association field for final business data such as Card Flow and Transaction./getCardList or /cardDetail/getCardFlow/cardTransaction/getCardFlow.| Information | Current Status |
|---|---|
| Unique operation flow ID | /getCardFlow returns flow_id, which can be used for fund flow reconciliation and de-duplication. |
| Operation status | Subject to the status actually returned by /getCardFlow. |
| Requested amount and actual amount | Subject to the fields actually returned by the relevant API. |
| Fees | Fee flows are not currently returned separately by /getCardFlow. |
| Balance before and after the operation | The account balance after the flow is completed is currently returned. |
| Creation time and update time | Subject to the fields actually returned by the relevant API. |
/getProductCode currently returns:| Item | Current Rule |
|---|---|
| Issuance fee and top-up fee | /getProductCode does not currently return fee fields. |
/createCard amount range | amount >= 1; save cards also require amount <= 50000. |
/rechargeCard amount range | 10 <= amount <= 50000. |
/refundCard amount range | amount >= 0. |
| 3DS, AVS and subscription payment capability | Subject to the product details in the console. |
| Supported or restricted countries, merchants and MCCs | Subject to VMCard business notices and console configuration. |
| Card validity and product listing/delisting | Subject to the actual product status in the console and VMCard notices. |
Important: The VMCard Open API does not currently offer share / credit line card products. The content below about share,wallet_balanceand/updateCardLimitonly explains the existing API fields and capability definitions. It does not mean that API users can currently activate or use credit line cards.The card products and product permissions actually available are subject to what is actually enabled in the VMCard console.
/createCard for a save card, does amount represent the initial top-up amount?balance and wallet_balance correspond to?balance: main account balance, corresponding to the prepaid card fund pool.wallet_balance: wallet balance, corresponding to the share / credit line card fund pool./updateCardLimit modifies amount, how does it actually affect the credit wallet?amount passed in becomes the new total limit.card_address be omitted entirely in /createCard?card_address is passed, is address_line_two required?first_name and last_name are required and must not be empty.card_address as a whole is optional.card_address is passed, all inner fields except address_line_two are required.-).# and @./rechargeCard and /refundCard?/rechargeCard: deducted from the main account balance and added to the prepaid card balance./refundCard: returned from the prepaid card balance to the main account balance.amount./rechargeCard amount range:10 <= amount <= 50000/refundCard amount rule:amount >= 0PENDING?"true"?"true" means the API has been processed successfully and synchronously./cardDetail and /getCardFlow.flow_id be queried for fund operations?/getCardFlow, and each fund flow contains a unique flow_id./refundCard is based on the card's current available balance./getCardFlow mean?flow_id: fund flow ID.amount: flow amount.reality_amount: actual processed amount.account_balance: account balance after the flow is completed.ref, code: extended fields of the fund flow.getCardFlow.flow_id globally unique and never reused?/getCardFlow currently does not include separate fee flows, nor does it return a fee currency field.auth_id link Authorization, Settlement, Reversal and Refund?auth_id currently returned is a transaction record ID generated by VMCard. It identifies a single returned record, but cannot be reliably used as a unified ID across the entire lifecycle of Authorization, Settlement, Reversal and Refund./cardTransaction, the current rules are:| Item | Answer |
|---|---|
Field filtered by start_time and end_time | Filtered by auth_time. |
| Time range boundaries | Start and end times are inclusive. |
| Time zone of time fields | The storage time zone of auth_time depends on the time zone of the data returned by each channel. |
| Default sort order | Descending by auth_time. |
| Pagination stability | offset/limit pagination is currently used; if new records are added during the query, pagination results are not guaranteed to be fully stable. |
| Maximum query span and data retention | page_size is at most 1000; the query time span is not currently limited, and historical data is currently retained long-term. |
| Incremental queries | Incremental queries by update time, cursor or independent event ID are not currently supported. |
auth_amount / auth_currency and settle_amount / settle_currency mean?auth_amount: authorized amount.auth_currency: authorization currency.settle_amount: settlement amount.settle_currency: settlement currency.type, not by the sign of the amount.1.234 is processed as 1.23.1.235 is processed as 1.24.| Verification Capability | Current Status |
|---|---|
| HMAC or public-key signature | Supported. Since 2026-08-26, each push carries an RSA-SHA256 signature in the X-VM-SIGN request header; see "Webhook Signature Verification" for how to verify it. |
| Callback Secret | Only the callback URL is currently configured; no independent Callback Secret is provided. |
timestamp + nonce replay protection | Not currently supported. |
Independent event_id or delivery_id | Not currently provided. |
| mTLS | Not currently used. |
| Production fixed outbound IP | 8.219.3.65. |
HTTP 200 OK{
"msg": "ok"
}msg is not ok.| Item | Current Status |
|---|---|
challenge_id or transaction_id | Not included in the current callback. |
| Independent event ID | Not currently provided. |
| OTP generation time and expiry time | Not returned in the callback. |
| Notification count or attempt count | Not included in the payload. |
| OTP replay protection field | Not currently provided. |
| Webhook query or manual resend API | Not currently provided. |
3DS is disabled by default on all card BINs currently available in the VMCard system, so no 3DS notifications will be generated at this stage. If 3DS is enabled for related products in the future, VMCard will notify API users in advance.
code = 0code != 0code and error message.Authorization is empty, the Token is invalid or the Token has expired: 400003400007400004 and 400007 mean?400004: Permission not granted (No Permission)400007: Incorrect App SecretAuthorization Is EmptyInvalid TokenInvalid AppIdParams Content ErrorRetry-After is not currently returned when rate limiting is triggered.AppId + API Endpoint/getAccessToken is rate-limited by:Source IP + Request URLACTIVE: The card is active.CANCELLED: The card is frozen or disabled and can be restored by submitting ACTIVE again.DELETED: The card has been deleted and cannot be restored.DELETED is used when VMCard risk control actively closes a card.CANCELLED, which is usually lifted automatically after 3 to 5 days./deleteCard irreversible?DELETED status, it cannot be restored.data is a plaintext JSON object. No IP whitelist or public/private keys are required.{
"content": "RSA ciphertext"
}/createCard/cardDetail/freezeCard/deleteCard/rechargeCard/refundCard/cardTransaction/updateCardLimit/getCardList/getCardFlow/getProductCode and /getAccountBalance have no business request body and may be called with an empty body.data in a successful response is encrypted.json.dumps(data) and then UTF-8 encoded./cardTransaction.auth_time include a Timezone or UTC Offset?auth_time is the time the transaction was stored after being processed by each channel, and its time zone may vary by channel./refundCardThis section only applies to the currently available save / prepaid card products. VMCard does not currently offer share / credit line card products.
/refundCard for different prepaid card products:| Product | Card Network and Issuing Country | BIN | Minimum Retained Balance |
|---|---|---|---|
| VC110 | Visa, United States | 43612077, 43612078, 43612079, 43612080, 43612081, 40041641, 40024200 | 0.10 USD |
| VC113 | Mastercard, United States | 537872 | 0.10 USD |
| VC102 | Mastercard, United States | 555671, 544015, 525962 | Can be refunded to 0.00 USD |
/refundCard, ensure that the card balance after the return meets the minimum retained balance of the corresponding product./cardTransaction./getCardFlow fund flow.type = "card recharge" in /getCardFlow: funds transferred from the platform account to the card.type = "card refund" in /getCardFlow: card balance returned to the platform account.type = "Refund" in /cardTransaction: merchant refund of a purchase.type = "Reversal" in /cardTransaction: authorization reversal.type, not by the sign of the amount.type = "Refund"
status = "COMPLETE"type = "Refund"| Parameter | Type | Description |
|---|---|---|
auth_id | String | Transaction ID |
card_id | String | Card ID |
vm_card_id | String | VM card ID |
auth_time | String | Transaction authorization time |
auth_amount | Double | Authorized amount |
auth_currency | String | Authorization currency |
settle_amount | Double | Settlement amount |
settle_currency | String | Settlement currency |
status | String | Transaction status |
type | String | Transaction type |
merchant_name | String | Merchant name |
create_time | String | Creation time |
description | String | Transaction details or failure information |