1. FAQ
VM_API
English
  • 简体中文
  • English
  • Integration Guide
  • Environment Configuration
  • Global Error Codes
  • Transaction Type Description
  • Card Status Description
  • VM Card operation V1 (only for accounts with a merchant public key configured before 2026-10-30)
    • Webhook Signature Verification
    • Get Account Balance
      POST
    • Get Card Product Code
      POST
    • Apply for Card
      POST
    • Card Details
      POST
    • Modify Card Limit(For credit line cards only)
      POST
    • Freeze/Unfreeze Card
      POST
    • Card Top-up(For prepaid cards only)
      POST
    • Card Refund(For prepaid cards only)
      POST
    • Transaction Records
      POST
    • Delete Card
      POST
    • Card List
      POST
    • Card Flow
      POST
  • VM Card operation V2 (available to all accounts, recommended)
    • Get Account Balance
      POST
    • Get Card Product Code
      POST
    • Apply for Card
      POST
    • Card Details
      POST
    • Modify Card Limit(For credit line cards only)
      POST
    • Freeze/Unfreeze Card
      POST
    • Card Top-up(For prepaid cards only)
      POST
    • Card Refund(For prepaid cards only)
      POST
    • Transaction Records
      POST
    • Delete Card
      POST
    • Card List
      POST
    • Card Flow
      POST
  • Notification
    • WebHook
    • Card 3DS Notification
  • Change Log
    • Change Log
  • FAQ
    • FAQ
  • Get accessToken
    GET
  • 数据模型
    • 示例数据模型
      • Pet
      • Category
      • Tag
  1. FAQ

FAQ

VMCard Open API Technical FAQ#

Document Notes#

This document summarizes common technical questions about integrating and using the VMCard Open API, including fees and billing, authentication and encryption, Access Token, request de-duplication, card management, transaction queries, Webhooks, and Sandbox vs. Production. It is intended as a reference for API users during development, testing and production integration.
Specific API capabilities, card products and account permissions are subject to the actual configuration in the VMCard console and the official API documentation.

1. Fees and Billing Rules#

1.1 Top-up Fee#

Q: Is the top-up fee charged when funds are deposited into the VM main account, or when /rechargeCard is called to top up a prepaid card?
A: The top-up fee is charged when funds are deposited into the VM main account. No fee is charged when calling /rechargeCard to top up a prepaid card.
Q: If account funding and card top-up are two separate steps, are they charged separately?
A: No. No fee is charged for the card top-up step.
Q: What are the fee base, amount precision, rounding rule and minimum fee?
A: The fee is calculated at the top-up rate configured in the console, rounded to two decimal places, with no minimum fee.
Q: When /refundCard returns the card balance to the account, is the top-up fee already charged refunded?
A: No. /refundCard only returns the card balance to the VM main account and does not refund any account funding fee already charged.

1.2 Card Issuance Fee#

Q: Which product_code or BIN does the card issuance fee apply to?
A: Subject to the card fee rates configured in the business console.
Q: Is a fee charged if card issuance fails?
A: No.
Q: Is a fee charged when a duplicate request is blocked?
A: No card issuance fee is charged if no card is actually created.
Q: Do different regions, card networks and card products have different issuance prices?
A: Yes. Subject to the card fee rates configured in the business console.

1.3 Other Fees#

Current unified billing rules:
Fee TypeBilling Rule
Authorization or failed transaction feeCard groups VC102/VC110/VC113: 0.20 USD per transaction; card group VC105: 0.30 USD per transaction.
Merchant refund feeA 10% merchant refund fee is charged on all card BINs and deducted from the main account.
Decline or dispute feeA 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 feeNot charged.
Card balance return feeNot charged.
Account withdrawal or fund transfer-out feeWhen the VM main account balance is withdrawn to an external wallet, 4% of the withdrawal amount + 3 is charged.

2. Authentication and Payload Encryption#

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 data is a plaintext JSON object. v2 users can skip this section.

2.1 Actual Request Format (v1 only)#

The integration guide requires v1 users to encrypt business parameters with the VM public key and submit them in the following format:
{
  "content": "RSA ciphertext"
}
Q: For v1, which APIs in the Sandbox and Production environments require an encrypted content payload?
A: For v1, every card API with a business request body must use the {"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.
Q: Can any business API accept plaintext JSON directly?
A: Not in v1. In v2, all APIs accept plaintext JSON directly.
Q: Is data always encrypted in a successful response?
A: Always encrypted in v1. Not encrypted in v2; a plaintext JSON object is returned directly.
Q: Are parameter, authentication, or decryption error responses returned as plaintext or ciphertext?
A: Error responses are returned as plaintext.
Q: Can complete Sandbox cURL and actual response examples be provided for /getAccountBalance, /createCard, /cardDetail, /rechargeCard and /refundCard?
A: The relevant examples are available in the API documentation.

2.2 Long RSA Payload Processing (v1 only)#

Q: How are long payloads handled with a 4096-bit RSA key and PKCS#1 v1.5?
A:
The maximum plaintext block size is 501 bytes.
Each ciphertext block is 512 bytes.
Long payloads are encrypted or decrypted block by block in source order and concatenated in the same order.
Encryption sequence: JSON UTF-8 bytes → RSA/PKCS#1 v1.5 encryption → Base64 encoding → Hex encoding.
Decryption sequence: Hex decoding → Base64 decoding → RSA/PKCS#1 v1.5 decryption → UTF-8 JSON.
JSON is serialized with json.dumps(data) and then UTF-8 encoded.
After decryption, parse the JSON as a UTF-8 string.
The fixed test vectors in the documentation may be used for integration testing.
For the official sample code, refer to the Python example in the API documentation.

2.3 VM Public Key and Key Rotation (v1 only)#

Q: How is the VM public key officially obtained and how is its fingerprint verified?
A: Through the controlled channel designated by VMCard.
Q: How are users notified when the VM public key is updated?
A: The VM public key is updated as needed, and API users are notified in advance.
Q: Can the API user public key be rotated without interruption?
A: Yes, switching takes effect within minutes.
Q: Can the old and new API user public keys be valid in parallel for a period of time?
A: No.

3. Access Token#

/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.
QuestionAnswer
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.

4. Request De-duplication and Final-Result Queries#

The VMCard Open API supports request de-duplication via X-Client-Request-Id.

4.1 Request ID Rules#

X-Client-Request-Id applies to all APIs, including card issuance, top-up, balance return, limit modification and card deletion.
Rules:
Maximum length is 64 characters.
Letters, digits, and -, _, ., : are allowed.
Uniqueness is determined by the combination of AppId + ClientRequestId.
Request IDs are currently stored permanently.
A repeated Request ID returns Duplicate Client Request Id, whether or not the parameters are the same.
A duplicate request does not return the business result of the first request.
When two identical Request IDs arrive concurrently, only one is allowed into business processing; the others return Duplicate Client Request Id.
A Request ID takes effect after the request passes authentication and decryption and enters the VM API logging pipeline.

4.2 Request ID and Business Results#

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.
Request ID registration and the subsequent business data write are not in the same database transaction, so callers should not rely on the Request ID alone to determine the final business result.
There is currently no unified operation status query API.
If the client does not receive a response or the result is uncertain, query the final status according to the specific business:
Card issuance: /getCardList or /cardDetail
Card top-up and balance return: /getCardFlow
Card transactions: /cardTransaction
For write APIs that change funds or card status, if a request times out, the network is interrupted, or the response is unclear, first query the final business status before deciding whether to retry.

4.3 Fund Flow Information#

For fund operations such as card top-up and balance return, the related fund flows can be queried via /getCardFlow.
InformationCurrent Status
Unique operation flow ID/getCardFlow returns flow_id, which can be used for fund flow reconciliation and de-duplication.
Operation statusSubject to the status actually returned by /getCardFlow.
Requested amount and actual amountSubject to the fields actually returned by the relevant API.
FeesFee flows are not currently returned separately by /getCardFlow.
Balance before and after the operationThe account balance after the flow is completed is currently returned.
Creation time and update timeSubject to the fields actually returned by the relevant API.

5. Card Products, Card Types and Balances#

5.1 Product Information#

/getProductCode currently returns:
BIN
Product code
Card type
Card network
Issuing region
Remaining number of cards that can be issued
ItemCurrent Rule
Issuance fee and top-up fee/getProductCode does not currently return fee fields.
/createCard amount rangeamount >= 1; save cards also require amount <= 50000.
/rechargeCard amount range10 <= amount <= 50000.
/refundCard amount rangeamount >= 0.
3DS, AVS and subscription payment capabilitySubject to the product details in the console.
Supported or restricted countries, merchants and MCCsSubject to VMCard business notices and console configuration.
Card validity and product listing/delistingSubject to the actual product status in the console and VMCard notices.

5.2 save and share#

Important: The VMCard Open API does not currently offer share / credit line card products.
The content below about share, wallet_balance and /updateCardLimit only 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.
Q: When calling /createCard for a save card, does amount represent the initial top-up amount?
A: Yes.
Q: Which fund pools do balance and wallet_balance correspond to?
A:
balance: main account balance, corresponding to the prepaid card fund pool.
wallet_balance: wallet balance, corresponding to the share / credit line card fund pool.
share / credit line card products are not currently available.
Q: What currency are the two balance fields in?
A: Both are in USD and represent the current available balance of the corresponding fund pool.
Q: When /updateCardLimit modifies amount, how does it actually affect the credit wallet?
A: This API is designed for share cards; the amount passed in becomes the new total limit.
Since share / credit line card products are not currently available, this capability is not currently open to API users.

5.3 Address and Cardholder Fields#

Q: Can card_address be omitted entirely in /createCard?
A: Yes.
Q: If card_address is passed, is address_line_two required?
A: No. An empty string may be submitted when there is no content.
Q: What are the format requirements for name, country, state, postal code, area code, mobile number and email?
A:
first_name and last_name are required and must not be empty.
card_address as a whole is optional.
If card_address is passed, all inner fields except address_line_two are required.
Address fields only support letters, digits, spaces and hyphens (-).
Address fields do not support Chinese characters or special symbols such as commas, periods, # and @.
Area code, mobile number and email are optional, with no additional format restrictions at present.

5.4 Spending Limits#

Q: What are the current single-transaction and daily spending limits for cards?
A:
Single-transaction limit: 10,000 USD.
Daily transaction limit: 100,000 USD.

6. Prepaid Card Top-up and Balance Return#

Q: Where are funds deducted from and returned to for /rechargeCard and /refundCard?
A:
/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.
Q: Are partial top-ups and partial balance returns supported?
A: Top-ups and balance returns are supported for the specified amount.
Current /rechargeCard amount range:
10 <= amount <= 50000
Current /refundCard amount rule:
amount >= 0
Q: Are top-up and balance return completed synchronously, or can they enter PENDING?
A: The APIs are currently processed synchronously.
Q: What does it mean when the API returns the string "true"?
A: "true" means the API has been processed successfully and synchronously.
The actual card balance and account balance are subject to the data returned by query APIs such as /cardDetail and /getCardFlow.
Q: Can flow_id be queried for fund operations?
A: Yes. Related fund flows can be queried via /getCardFlow, and each fund flow contains a unique flow_id.
Q: When a card has authorizations pending settlement, how is the maximum returnable balance calculated?
A: The returnable amount for /refundCard is based on the card's current available balance.
The amount of an authorization pending settlement has usually been frozen or held by the card network or channel, so the available balance returned by the channel is reduced accordingly. The VM API will not deduct that amount again.
Q: What do the main fields in /getCardFlow mean?
A:
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.
Q: Is getCardFlow.flow_id globally unique and never reused?
A: Yes.
Q: Do card fund flows include fees and their currency?
A: /getCardFlow currently does not include separate fee flows, nor does it return a fee currency field.

7. Transaction Records and Reconciliation#

7.1 Transaction Relationships#

Q: Can auth_id link Authorization, Settlement, Reversal and Refund?
A: Not guaranteed.
The 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.
Q: Does each transaction event have an independent and immutable event ID?
A: There is currently no independent unified event ID.
Q: Can one authorization be partially settled or settled multiple times?
A: Yes.
Q: Can one purchase be partially refunded or refunded multiple times?
A: Yes.
Q: Are ARN, RRN, STAN or other network reference numbers currently provided?
A: Not at present.

7.2 Queries and Pagination#

For /cardTransaction, the current rules are:
ItemAnswer
Field filtered by start_time and end_timeFiltered by auth_time.
Time range boundariesStart and end times are inclusive.
Time zone of time fieldsThe storage time zone of auth_time depends on the time zone of the data returned by each channel.
Default sort orderDescending by auth_time.
Pagination stabilityoffset/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 retentionpage_size is at most 1000; the query time span is not currently limited, and historical data is currently retained long-term.
Incremental queriesIncremental queries by update time, cursor or independent event ID are not currently supported.

7.3 Amounts, Currencies and Precision#

Q: What do auth_amount / auth_currency and settle_amount / settle_currency mean?
A:
auth_amount: authorized amount.
auth_currency: authorization currency.
settle_amount: settlement amount.
settle_currency: settlement currency.
All returned amounts are absolute values.
Q: Are refund and authorization reversal amounts positive or negative?
A: Positive.
Callers should determine the direction of funds by the transaction type, not by the sign of the amount.
Q: How many decimal places are supported for amounts and what is the rounding rule?
A:
The API does not limit the number of decimal places of input amounts.
Business processing and storage uniformly keep two decimal places.
Standard rounding (round half up) is used.
1.234 is processed as 1.23.
1.235 is processed as 1.24.
It is recommended that callers submit amounts with two decimal places.
Q: How can financial details or a full transaction export be obtained?
A: Financial details can be exported from the VMCard console.
For other reconciliation needs, please contact VMCard technical support.

8. Webhooks and 3DS Notifications#

8.1 Webhook Source and Security Verification#

Current support for ordinary transaction Webhooks and 3DS notifications:
Verification CapabilityCurrent Status
HMAC or public-key signatureSupported. 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 SecretOnly the callback URL is currently configured; no independent Callback Secret is provided.
timestamp + nonce replay protectionNot currently supported.
Independent event_id or delivery_idNot currently provided.
mTLSNot currently used.
Production fixed outbound IP8.219.3.65.
If the Production Webhook outbound IP changes, VMCard will notify API users in advance to update their configuration.

8.2 Webhook Success Response#

The Webhook receiver is recommended to return:
HTTP 200 OK
Transaction-flow Webhooks should also return:
{
  "msg": "ok"
}
The following may be treated as delivery failures:
HTTP status code is not 2xx.
Network connection failure.
Request timeout.
For transaction-flow Webhooks, the returned msg is not ok.
The response format does not meet the current success criteria.

8.3 Webhook Delivery and Retries#

Current rules for transaction-flow Webhooks:
The request timeout is 30 seconds.
Currently at most 3 attempts in total.
HTTP 4xx / 5xx, network errors, connection errors, request timeouts, or responses that do not meet the success requirements are treated as delivery failures.
No fixed retry interval is currently configured.
Actual retry timing is affected by queue scheduling and worker load.
A fixed retry interval or a strict maximum delivery time is not guaranteed.
Webhooks are not guaranteed to be delivered strictly in the order in which transactions occurred.
Callers should be able to handle duplicate notifications.
Other asynchronous callback requests of the VM API:
The request timeout is 30 seconds.
The current queue configuration may differ from that of transaction-flow Webhooks.
Specific delivery rules are subject to the description of the corresponding API.

8.4 3DS#

ItemCurrent Status
challenge_id or transaction_idNot included in the current callback.
Independent event IDNot currently provided.
OTP generation time and expiry timeNot returned in the callback.
Notification count or attempt countNot included in the payload.
OTP replay protection fieldNot currently provided.
Webhook query or manual resend APINot 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.

9. Success Codes, Error Codes and Rate Limits#

9.1 Determining Success#

Q: How do I determine whether a VMCard API request succeeded?
A:
code = 0
means the business request succeeded.
code != 0
means the business request failed.
Determine the specific error reason from the returned code and error message.

9.2 Common Error Codes#

Q: What error codes correspond to an invalid Token, an expired Token and an incorrect App Secret?
A:
Authorization is empty, the Token is invalid or the Token has expired: 400003
Incorrect App Secret: 400007
Q: What do 400004 and 400007 mean?
A:
400004: Permission not granted (No Permission)
400007: Incorrect App Secret

9.3 Retry Principles#

Q: Which errors usually confirm that the request has not entered business processing?
A: For example:
Authorization Is Empty
Invalid Token
Invalid AppId
Params Content Error
Request decryption failure
For write operations such as card issuance, top-up, balance return and card deletion, if a network timeout, card service exception occurs, or the client does not receive a response, do not resubmit directly.
First confirm the final business result via the corresponding query API.

9.4 Rate Limits#

Sandbox and Production currently use the same rate-limit rules:
At most 100 calls per minute for the same API under the same subject.
At most 86,400 calls per 24 hours for the same API under the same subject.
The per-minute limit uses a sliding window of the last 60 seconds.
The daily limit uses a sliding window of the last 24 hours.
The maximum number of concurrent connections is 1000.
Retry-After is not currently returned when rate limiting is triggered.
Business APIs are rate-limited by:
AppId + API Endpoint
/getAccessToken is rate-limited by:
Source IP + Request URL

10. Freezing, Deletion and Outstanding Transactions#

10.1 Card Status#

Q: What does each VMCard card status mean?
A:
ACTIVE: 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.
If the issuer freezes the card because of consecutive incorrect CVV or expiry date entries, the card may show as CANCELLED, which is usually lifted automatically after 3 to 5 days.

10.2 Transactions After Freezing#

Q: Can Settlement, Refund or Reversal still occur after a card is frozen?
A: Yes.
Freezing or deleting a card only blocks new Authorizations.
For Authorizations that were approved before freezing or deletion and have not been settled or fully reversed, the merchant may still submit Settlement later.
Refund and Reversal may also continue to occur after the card is frozen.

10.3 Late Settlement#

Q: How is a late Settlement debited?
A:
A late Settlement is first deducted from the card balance.
If the card balance is insufficient, it is deducted from the main account.
If the main account balance is insufficient, the console may show a negative balance.

10.4 Card Deletion#

Q: Is /deleteCard irreversible?
A: Yes.
Once a card enters DELETED status, it cannot be restored.
Q: Can a card be deleted when it has a balance or authorizations pending settlement?
A: Yes.
When a card is deleted, the system first returns the card balance and then deletes the card.
The automatic balance return and card deletion are in the same transaction.
If the automatic return fails, the whole deletion fails and the card remains in its original status.
Q: Where do funds go when a merchant refund occurs after the card is deleted?
A:
If the card is still active: the refund goes to the card.
If the card has been deleted: the refund goes to the main account.
Q: Can a late Settlement still occur after the card is deleted?
A: Yes.
For Authorizations that were approved before deletion and have not been settled or fully reversed, the merchant may still submit Settlement later.
Therefore, callers should not interpret "the card has been deleted" as meaning that all historical authorizations have ended.

11. Sandbox and Production#

The VMCard Open API currently provides two environments:
Sandbox
Production
No separate UAT environment is currently provided.
Sandbox is used for API integration development and pre-production testing.
Sandbox and Production use the same business request format.
v2: In both environments, plaintext JSON is submitted directly and the response data is a plaintext JSON object. No IP whitelist or public/private keys are required.
v1: Every card API with a business request body must submit:
{
  "content": "RSA ciphertext"
}
This applies to:
/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.
v1 business APIs do not accept plaintext JSON directly.
In v1, data in a successful response is encrypted.
Parameter, authentication, or decryption error responses are plaintext.
The v1 RSA rules are as follows:
Key size: 4096 bits.
Padding: PKCS#1 v1.5.
Maximum plaintext block size: 501 bytes.
Ciphertext block size: 512 bytes.
Long payloads are encrypted or decrypted block by block in source order and concatenated in order.
Encryption sequence: JSON UTF-8 bytes → RSA encryption → Base64 encoding → Hex encoding.
Decryption sequence: Hex decoding → Base64 decoding → RSA decryption → UTF-8 JSON.
JSON is serialized with json.dumps(data) and then UTF-8 encoded.

12. Time Fields#

Q: Does /cardTransaction.auth_time include a Timezone or UTC Offset?
A: It does not currently include a Timezone or UTC Offset field.
auth_time is the time the transaction was stored after being processed by each channel, and its time zone may vary by channel.
If callers need a unified time zone for internal reconciliation, they should normalize it on their side according to their own reconciliation rules.

13. Transaction Relationship Fields#

Q: Are a provider parent transaction ID, Settlement / Refund parent-child fields, or other stable transaction relationship keys currently provided?
A: Not at present.
The existing external fields cannot reliably link Authorization, Settlement, Reversal and Refund into a complete transaction lifecycle.

14. Minimum Retained Balance for /refundCard#

This section only applies to the currently available save / prepaid card products.
VMCard does not currently offer share / credit line card products.
Minimum retained balances when calling /refundCard for different prepaid card products:
ProductCard Network and Issuing CountryBINMinimum Retained Balance
VC110Visa, United States43612077, 43612078, 43612079, 43612080, 43612081, 40041641, 400242000.10 USD
VC113Mastercard, United States5378720.10 USD
VC102Mastercard, United States555671, 544015, 525962Can be refunded to 0.00 USD
Sandbox and Production currently use the same rules.
When calling /refundCard, ensure that the card balance after the return meets the minimum retained balance of the corresponding product.

15. Hosted Reveal and Card Data Display#

Q: Does VMCard provide Hosted Reveal, iframe, one-time display tokens or other hosted card data reveal capabilities?
A: The following capabilities are not currently provided:
A VMCard-hosted page displaying full card data.
An embeddable iframe.
One-time or short-lived card data display tokens.
One-time or short-lived card data display links.
Any other VMCard-hosted method of revealing full card data.

16. Data Channel and Transaction Type of Merchant Refunds#

Q: Through which API are merchant-initiated refunds returned?
A:
Merchant-initiated refunds are mainly returned via /cardTransaction.
The same merchant refund is not also returned as a /getCardFlow fund flow.
Meaning of each type:
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.

17. Merchant Refund Association and Amount Semantics#

Q: How is a refund record associated with the original purchase?
A: Currently it can only be confirmed that the refund record and the original purchase belong to the same card.
The existing external fields cannot reliably associate a refund record with a specific original purchase.
Q: Is the refund amount positive or negative?
A: Returned as a positive number.
Callers should determine the direction of funds by the transaction type, not by the sign of the amount.
Q: How do I determine that a merchant refund has been completed?
A: Both of the following must be met:
type = "Refund"
status = "COMPLETE"

18. Webhook Merchant Refund Notification#

After the transaction Webhook is configured, merchant refund records that have been stored and triggered for forwarding are notified asynchronously to the same Webhook URL.
The refund event type is:
type = "Refund"
Webhook payload fields:
ParameterTypeDescription
auth_idStringTransaction ID
card_idStringCard ID
vm_card_idStringVM card ID
auth_timeStringTransaction authorization time
auth_amountDoubleAuthorized amount
auth_currencyStringAuthorization currency
settle_amountDoubleSettlement amount
settle_currencyStringSettlement currency
statusStringTransaction status
typeStringTransaction type
merchant_nameStringMerchant name
create_timeStringCreation time
descriptionStringTransaction details or failure information

19. Sandbox Merchant Refund Testing#

Q: How can merchant refunds be simulated in the Sandbox environment?
A: The VMCard Open API does not currently provide a separate merchant refund simulation API.
For merchant refund integration testing, please contact VMCard technical support.
修改于 2026-11-04 08:32:00
上一页
Change Log
下一页
Get accessToken
Built with