Using Raw API
This method is the most flexible way to make a MixPay payment.
It's suitable for scenarios that can not use a browser, such as the Mobile Native App.
Constructing the accept payment view
When a customer makes a purchase, on your App check-out page, show a "Pay with Crypto" button. When the customer clicks the button, you should construct an App view like our MixPay payment page.
In this view:
When the customer clicks to choose a payment method, based on which wallet has been chosen:
When payment is created successfully, your App base the response and performs corresponding actions to collect user payments (This step will explain later).
When the customer finishes paying crypto ( depending on what cryptocurrency the customer chooses to pay, the delay varies from 5 seconds to 30mins or more), showing a "Waiting Payment Processing" hint to the customer;
It's recommended to make the Payments Results API call every two seconds.
Pay with Mixin wallet
In step 3, if the customer is selecting Pay using Mixin Wallet, your App should call accepting-payments API.
When getting the MixPay API result, your App client has to call Mixin App using URL Schema(What is URL Schema? ) to finish the payment:
As you can see, there are parameters in the Mixin URL Schema, those parameter value are matching Accepting Payments response as following:
// Mixin Param = MixPay Accepting Payments API result
Just passing the key value correspondingly, and the URL Schema will do the rest.
For more info for Mixin URL Schema, please read this article.
Pay with other payment methods
In step 3, if the customer chooses other payment methods, your App should call on-chain payment API.
At the on-chain-payments API JSON Response, there is a key call
destination; this is the Address customer has to transfer the cryptocurrency.
You can reference the following UI to construct your App View:
Note: If the payment assets are EOS, you can use the
destinationfrom the API result.
There are two kinds of expiration on creating a MixPay payment.
1. Payment expired (closed)
In online shopping flow, sometimes you have this business logic - when your order expired, you need to release the inventory.
You can provide the
expiredTimestamp parameter, to keep the MixPay payment in sync with your order expiration time.
When MixPay payment expired, the user will not be able to able to pay. (You need to construct the UI on your side.)
If you leave
expiredTimestamp parameter empty, this payment will be valid.
2. Tolerate period expired (refresh needed)
If the customer's payment asset is different than the settlement assets, let's say the payment asset is BTC and the settlement asset is ETH. MixPay will convert BTC to ETH internally for the merchants.
But due to the risk of crypto price fluctuations, for example, if the customer is finishing the payment after 24 hours, and the BTC price drops from $25000 to $22000.
So we need to set a reasonable expiration time, otherwise, we may suffer tremendous loss. This expiration time we call it "tolerate period".
"tolerate period" is defined internally. When creating a payment, will have there two fields in the response:
// Unit Timestamp for accuracy
// A little helper for setting up the countdown
When the "tolerate period" is expired, you must request the create payment API with the same parameters. MixPay will recalculate the
If a customer pays with a "tolerate period" expired payment, if is "Pay with Mixin wallet", the crypto assets will refund, and the payment result will be
payment overtime. If is "Pay using an on-chain Wallet", due to the crypto transfer's nature, we can not refund the money directly, we must get the customer's wallet address first, in this scenario, you can instruct the customer to contact our customer service.
Getting the result
At this point, customers are paying crypto using our Paylink; how can you get the paying results?
On your server side, you can loop through the payments-results API using
It's recommended to implement the Payment Callback flow, for better performance.
Multi-payment (pay less)
If the user has underpaid, we can ask them to make an additional payment to complete the order. If you are using MixPay's Checkout Page, multiple payments are already handled, and you don't need to perform any additional actions. Simply check the
data.status in the response to determine if it is equal to
However, if you are using the Raw API to build your own checkout page, you need to support multiple payments in order to improve the payments success rate.
To support multiple payments, you need to perform the following steps.
When calling the payments-results API:
- Use the
withparameter with the value
payment,transactionsin the URI to retrieve the
- Check the value of
data.payment.isFullyPaid. If it is true, the payment has been fully paid; otherwise, it is false.
- If it is true, check if
successto determine if the order is successful. If it is
pending, it means the transactions are waiting for block confirmation.
- If it is true, check if
- If the value of
data.payment.isFullyPaidis false, subtract
data.payableAmountto determine the remaining amount the user needs to pay.
Users have only 10 minutes to complete the payment (from the time MixPay receives the broadcast transaction). For multiple payments, the subsequent payment time may be reduced.
You need call the refresh onchain payment API to refresh the payment time.
Please note that each time you call the refresh onchain payment API, the payment time will be updated, and the
data.payableAmount will be also updated accordingly.
Q: If a user makes multiple payments exceeding the order amount, will the payment be successful?
A: Yes, it will be successful. In this case, check if
yes. The amount to be refunded is
data.surplusAmount. Please refer to the MixPay Checkout Page for the specific refund process.
Q: Can other payment methods (Mixin, Binance) support multiple payments? A: No. Only on-chain transfers support multiple payments.