Troubleshooting FAQ
This FAQ section is designed to assist users in troubleshooting common issues they might encounter while interacting with our API. It provides guidance on resolving specific problems related to API functionality, ensuring a smoother experience.
Q: What is the “Card Memo” field made for (e.g., in the endpoint Change Card's Nickname (Card Memo) /api/v1/cards/card/nickname/change)?
A: The “Card Memo” field is intended purely for your convenience. It functions as a small note or reminder about something important related to your debit card, which can aid in card identification. This feature is non-functional in terms of transaction processing and does not impact the operational status of the card.
Q: What is the difference between available balance, pending balance, and reserved balance in the endpoint Get Balance Details of a Card (/api/v1/cards/card/balance)?
A:
- available: This is the total amount of funds that are currently usable for transactions. It reflects the actual money available on your card.
- pending_balance: Also referred to as reserved balance, this represents funds that are on hold for pending transactions. These funds have been deducted from the available balance but are not yet completely processed or cleared.
Q: What are Decline Fees?
A: Decline fees are charges applied when a transaction is attempted but fails to process successfully. These fees may be levied for various reasons, including insufficient funds, entering incorrect personal details, or attempting transactions that do not comply with the card's terms.
Q: Can decline fees be charged from a closed card?
A: Yes. To prevent any charges, ensure the card is completely unlinked from any merchants or recurring payment setups once the card is closed.
Q: API keys are not establishing a successful connection between the client’s system and ours. What should I do?
A: If you're experiencing issues, it's possible that your API keys have expired or are invalid. To update or obtain a new token, please use the endpoint Login and Obtain Access Token (/api/v2/auth/login). Renewing your API key will help re-establish connectivity and restore access to the API's functions.
Q: What are reversed transactions?
A: Reversed transactions refer to those transactions that have been negated after initial authorization. This could happen for various reasons, such as merchant cancellations or user disputes. When a transaction is reversed, the funds are returned to the cardholder's account as if the transaction had never occurred. You can retrieve information about reversed transactions for a specific card or across all cards within a user's account by using the /api/v1/cards/transactions/reversed endpoint. This endpoint provides a detailed list of transactions with the status 'REVERSED', ensuring you can track and manage reversals effectively.
Q: Why is previous_tx used, and what does it entail?
A: The previous_tx field in our transaction data model plays a critical role, especially in tracking and auditing transaction histories. It is used to reference the previous state or the original transaction before any changes were made, such as reversals or adjustments. This is particularly useful in scenarios involving a transaction status that changes from 'PENDING AUTHORIZATION' to 'REVERSAL' or 'SUCCESS'. The previous_tx helps in maintaining a traceable link back to the original transaction, which authorized the payment. This linkage is crucial for resolving disputes, auditing, and validating the sequence of transaction activities.
Q: Does an additional path, such as "/close_withdrawal", will be appended to the set URL for receiving callbacks, for example, card closure callbacks?
A: Yes, according to the described setup in the documentation, if you establish a base URL to receive callbacks for specific events, such as card closure, the system will append a specified path to this base URL. For instance, if you set your base URL as https://test.com/close-card-callback, the callback for card closure will indeed be sent to https://test.com/close-card-callback/close_withdrawal.
Q: What happens to the funds when a card is closed?
A: When a card is closed, the funds remaining on the card are transferred to the wallet balance. However, this process occurs asynchronously. The average time between the action of closing the card or reducing its limit and the receipt of the callback is about 10 minutes.
Q: In which response field can I find the amount transferred from the card balance to the wallet during closure?
A: The amount transferred will typically be detailed in the response of the webhook or callback that is triggered by the closure or withdrawal operation: /api/v1/developers/close_withdrawal/. Ensure that your system is set up to receive and process these callbacks to handle the incoming data appropriately.
Q: How are callbacks managed for the return of funds upon card closure or limit reduction?
A: We have webhooks that are triggered upon the successful return of funds following a card closure or a withdrawal operation (which involves reducing the card's limit). You should have implemented handling for these callbacks on your end. The specific endpoint to add for receiving these notifications is /api/v1/developers/close_withdrawal/. This setup ensures that you are promptly informed about the status of the funds and can manage them accordingly in your system.
Q: I want to obtain details about an activity from /api/v1/transactions/activity/all, but there is no transaction_id field available. What should I use instead?
A: To obtain detailed information about a specific transaction from the activity list accessed through /api/v1/transactions/activity/all, you should use the original_id field instead of transaction_id. Use this original_id as the value for transaction_id in your query. For example, you would make a request to /api/v1/transactions/detail?transaction_id=original_id where original_id is replaced by the actual ID you wish to query.
Q: Why does the /api/v1/cards/topup operation always return a response status of 200, even if the top-up is not successful for some cards?
A: The /api/v1/cards/topup endpoint is designed to handle batch operations involving multiple cards simultaneously. Due to this, our API always returns a response status of 200, indicating that your top-up request has been received and processed, regardless of the individual outcomes for each card.
In the response, you will find a list of objects, each corresponding to a specific card included in the top-up operation. If the top-up for a particular card is unsuccessful, the object for that card will contain an error message instead of updated balance information. This means that while the overall API response status is 200, the actual outcome of the top-up operation for each card needs to be determined by checking for updated balance information or error messages within the response body.
Q: Can we provide a generated user ID for identification purposes, instead of using your internal base ID?
A: Yes, you can provide a generated ID for the end user, which can be your own ID or one from a third-party company if you are proxying our API to them. This ID is crucial for us to match and analyze activities linked to the specific user. For instance, we can provide reports saying, "Activity A, B, C has been detected on the cards of your user user_12345."
Q: What are the fields external_user_id and api_users_chain in the method for creating a card (/api/v1/cards/card/add)?
A: There are two new fields introduced in the card creation API method:
- external_user_id - This is the ID of the end user (either from your company or a third party if you are acting as a proxy). This field allows the API to identify the user associated with the new card distinctly.
- api_users_chain - This field is a list of API clients involved in the transaction. By default, it includes your company. If you are proxying our API to a third party, the list should follow with that third party, and so on. This helps in tracking which clients have interacted with the API concerning the user, providing a clear chain of interaction which is useful for auditing and compliance.
By using these fields, you ensure that every card transaction or operation can be accurately traced back to the correct end user, enhancing the capability to perform detailed activity reviews and maintain high security and compliance standards.
Q: What happens if there are insufficient funds on a card to cover the transaction fees?
A: If there are insufficient funds on the card to cover the commission fees associated with a transaction, the fees will be deducted from the wallet associated with the card. This ensures that all necessary fees are paid even if the card balance is not sufficient.
Q: What is the typical timeframe for a merchant to capture an authorization?
A: Once an authorization is approved, merchants typically capture the monetary amount of the transaction within 24 hours. However, there are instances where this process may extend up to 7 days depending on the merchant's operations and the nature of the transaction.
Q: Are there exceptions to the 7-day rule for capturing authorizations?
A: Yes, there are exceptions based on the merchant category. While most merchants are required to capture an authorization within 7 days, certain categories like hotels, airlines, and car rental companies are permitted up to 30 days to capture an authorization. This extended period is due to the nature of their services, which often involve advanced booking and scheduling that necessitates a longer timeframe for capturing payments.