Frequently Asked Question
This Frequently Asked Question (FAQ) list provides detailed answers to common questions about Lean.x payment gateway and its various features. This comprehensive list covers everything from API token management and callback
Is the API token static, or do we need to validate it with each request using the https://api.leanx.dev/api/v1/merchant/validate endpoint?
Answer : The API token is static; you do not need to validate it with every request.
Is the token in the callback the same as the one in the original request?
Answer : Yes, the token in the callback is identical to the one in the request.
Can users alter the payment amount during a transaction? For instance, if they initially request RM10, can they pay RM15 instead?
Answer : No, users cannot change the payment amount during the transaction.
Does Lean.x have a IP whitelist feature?
Answer : Yes, we have a IP whitelist feature for production accounts. However, this is not applied to sandbox accounts.
Do you validate user details like email, phone number, and full name for payments? Should we ensure that users provide accurate information?
Answer : It is recommended to collect accurate user data, although we only validate the email format.
Is there a row limit for the merchant/transaction-list API?
Answer : Yes, the maximum row limit per API call is 100, but you can set a lower limit if needed.
Do we need to update the list of payment services regularly, or can we save the channels we use?
Answer : You can save the list of payment services we provide, but updating it daily is recommended.
Is it necessary to send the customer’s name when creating a payout invoice?
Answer : Yes, the customer’s name must be included in the recipient_name parameter when creating a payout invoice.
Can we retrieve the API token from the dashboard? I’m using the one from the API, but it’s returning an "INVALID_TOKEN" error.
Answer : Yes, you can retrieve the auth_token from the dashboard. Log in to our portal (Sandbox: https://portal.leanx.dev | Production: https://portal.leanx.io), navigate to the API section, and add a new API key. Once enabled, you can retrieve the auth_token.
Where are the Hash Key and UUID used? Are they required for any requests?
Answer : The Hash Key is used to decrypt callback data, while the UUID is unique to your account and used for record-keeping purposes.
What is the minimum balance required in payout fund pool?
Answer : Merchants are required to maintain a minimum balance of RM2 at all times to perform payout activities. For example, if a merchant intends to pay out RM100 to a bank account, the minimum balance should be RM102.
This RM2 minimum balance will be refunded to the merchant upon account deactivation.
Is there a way to check payment status by ID, or can we only request data by date?
Answer : Yes, we have an API called Transaction Status that allows you to check payment status.
Should we always use check-verification-bank before creating a payout?
Answer : It depends on your process. You can validate the bank account during the first request and save the account number or verify it before each payout.
What should we do if the user’s name doesn’t match during a payout? Should we decline the payout?
Answer : Banks may not provide the full name of the recipient. For example, Maybank only provides 20 characters, and Bank Islam might add prefixes like "Cik," "Puan," or "Encik." You can allow the payout if there is an 80% match between the names. The similarity percentage can be adjusted based on your requirements.
What’s the difference between B2B FPX and B2C FPX? Are there different rates and payment flows, and can we integrate both?
Answer : B2C FPX is for personal bank accounts (e.g., M2U), while B2B FPX is for business bank accounts (e.g., M2U BIZ). The rates differ, but you can integrate both.
Do we need to create a new collection over time, or can we use one collection indefinitely? What do you recommend?
Answer : You can use one collection indefinitely, as there’s no limit on bill payment creation. If you manage bills, we recommend using one collection to group all transactions.
What does the talk_to_server_before parameter indicate?
Answer : This parameter indicates the time when the API responded to the client.
Is account verification considered a financial request? Will it trigger any financial transactions?
Answer : Account verification is not a financial request, so no financial transactions will be triggered.
Is the callback sent only once, or will it be resent if not delivered? Should we respond with 200 OK?
The callback is sent only for successful transactions. We expect a 200 OK HTTP response; otherwise, the callback will be resent up to 3 times. The response content does not need to follow any specific structure.
Can we receive a failed callback for payouts if user data is incorrect? Can you provide an example in the test environment?
Answer : Yes, similar to collections, the callback for payouts is only sent for successful transactions. You can use the https://docs.leanx.io/api-docs/payout/payout-status API for status checking. Example account numbers for failed and pending scenarios in the test environment are 1111111111 (FAILED) and 1212121212 (PENDING).
Can you provide an example of a failed response? In the test environment, payouts are always successful.
Answer : Use the provided test account numbers (1111111111 for FAILED, 1212121212 for PENDING) to simulate failed and pending payout scenarios.
For one Merchant ID (MID), is there only one virtual_pool_reference, and are all payouts withdrawn from it?
Answer : Yes, each merchant has one virtual_pool_reference for payouts, and all payouts are withdrawn from this pool.
Is income from collection transferred manually to make payouts, or does it go directly to the payout pool?
Answer : By default, income is transferred to the merchant's bank account. However, we offer an option to settle directly into the payout pool, which can be set up before going live.
What happens if we attempt a payout with insufficient funds? Is the decline final, or will it retry when the balance is topped up?
Answer : If there are insufficient funds, the payout will fail, and the decline is final. You will need to make another payout request.
Is the UUID included in the token field for every response, including both payouts and deposits?
Answer : Yes, the UUID is the same for both deposit and payout responses.
In the callback for payouts, we receive output.amount and output.payout_payment.item.payout_payment_amount. Are these fields always the same? Should we match output.amount only?
Answer : Yes, both fields represent the same value, which is the remaining prefund amount for payout purposes.
In the /merchant/get-payout-transaction-by-id endpoint, is the amount field a float, while in callbacks it’s a string?
Answer : Yes, the response amount is in float format, while in callbacks, it’s a string due to JWT encryption/decryption. The decrypted value will always be in string format.
How long does it take for the payment to be sent out after a request is made? Is it real-time? Is any approval required?
Answer : Payments are sent out in real-time without requiring approval.
How does the money flow work? Do we need to top up money from our bank account to Lean.x, or can Lean.x deduct money directly from our account?
How can I get the credentials? Should I use the sandbox credentials for integration first?
Answer : You will need to register at https://onboard.leanx.io. Once your registration is successful, you will receive sandbox credentials from the dashboard after your first login.
Last updated