Alipay (In-store)
Through a simplified integration process, you can enhance your Point of Sale system (POS) to connect with Omise, and start accepting payments from Alipay users in your store through the Barcode Alipay API
The following flow diagram covers the series of system interactions that occur between the customer, the merchant, Omise and Alipay in a typical offline Alipay transaction.
The payment flow
- When the payee is ready to checkout, they open their Alipay application.
- They then click the "Pay" button to generate a unique barcode.
- To accept payments, the merchant scans the barcode.
- The merchant's server then creates a charge through an API call sent to the Charge API.
- The merchant recieves a response. This will include the charge status, which at this stage, is marked
pending
. - In some cases, the payee may be required to confirm the payment on their Alipay app.
- To retrieve the lastest charge status, the merchant makes requests to the Charge API.
- The charge status marked as
success
indicates that the amount has been sucessfully paid, and the products can be handed over. - The charge status marked
failed
indicates that the amount has not been paid, either because;- Timeout - the payee will need to generate a new barcode to recreate the order.
- Insufficient funds - the payee is advised to choose an alternative payment method or top up their Alipay account.
* A webhook (POST) will be sent to the merchant's server with the latest update of the charge status (either success
or failed
)
Creating a charge
Just like how you would normally create a credit card charge, to create an Alipay charge you also use the Charge API. There are 2 ways of creating a charge.
1. Create a payment source, then create a charge using the source.
1.1. Create a payment source by making a POST
request to /sources
curl https://api.omise.co/sources \
-X POST \
-u skey_xxxxxxxxxxxxxx: \
-d "description=barcode alipay charge" \
-d "amount=2225" \
-d "currency=thb" \
-d "type=barcode_alipay" \
-d "barcode=1234567890" \
-d "store_id=store_1" \
-d "store_name=store 1" \
-d "terminal_id=POS-01"
example of API response
{
"object": "source",
"id": "src_test_5atzxwlghyr2jydh33h",
"livemode": false,
"location": "/sources/src_test_5atzxwlghyr2jydh33h",
"type": "barcode_alipay",
"flow": "offline",
"amount": 2225,
"currency": "thb",
"barcode": "1234567890",
"store_id": "store_1",
"store_name": "store 1",
"terminal_id": "POS-01"
}
1.2 Create a charge using the source id from the previous step (for example, src_test_5atzxwlghyr2jydh33h
)
curl https://api.omise.co/charges \
-X POST \
-u skey_xxxxxxxxxxxxxx: \
-d "description=barcode alipay charge" \
-d "amount=2225" \
-d "currency=thb" \
-d "source=src_test_5atzxwlghyr2jydh33h"
2. Create a charge in single call
{
"amount": "2225",
"currency": "thb",
"description": "a barcode alipay charge",
"source": {
"type": "barcode_alipay",
"barcode": "1234567890",
"store_id": "store_1",
"store_name": "store 1",
"terminal_id": "POS-01"
},
"metadata": {
"invoice_id": "inv-1234567890"
}
}
Regardless of the method you decide to use to create a charge, the result returned will be the same.
{
"object": "charge",
"id": "chrg_test_5au1dtnsoc7noi31yab",
"livemode": false,
"location": "/charges/chrg_test_5au1dtnsoc7noi31yab",
"amount": 2225,
"currency": "thb",
"description": "a barcode alipay charge",
"metadata": {
"invoice_id": "inv-1234567890"
},
"status": "pending",
"capture": true,
"authorized": false,
"reversed": false,
"paid": false,
"transaction": null,
"refunded": 0,
"refunds": {
"object": "list",
"from": "1970-01-01T00:00:00Z",
"to": "2018-02-02T11:53:15Z",
"offset": 0,
"limit": 20,
"total": 0,
"order": null,
"location": "/charges/chrg_test_5au1dtnsoc7noi31yab/refunds",
"data": []
},
"return_uri": null,
"reference": null,
"authorize_uri": null,
"failure_code": null,
"failure_message": null,
"card": null,
"customer": null,
"ip": null,
"dispute": null,
"created": "2018-02-02T11:53:15Z",
"source": {
"object": "source",
"id": "src_test_5atzxwlghyr2jydh33h",
"references": {
"expires_at": "2018-02-03T11:53:15Z"
},
"type": "barcode_alipay",
"flow": "offline",
"amount": 2225,
"currency": "thb"
}
}
Checking the charge status
As mentioned earlier, the status of a newly created charge will always show as pending
. To check for the latest status, you need to periodically make the GET
request to the Charge API.
We will send a webhook (POST
) with the latest charge details to the merchant's server as soon as the charge status is changed (either to success
or failed
).
Read more about webhooks.
Refunds
Alipay charges can be refunded in both partial or full amount within 12 months of the transaction date.
Failure codes
Code | Description |
---|---|
insufficient_balance |
There is insufficient balance in the payee's Alipay account |
timeout |
The payee did not approve the payment in time |
failed_processing |
Payment failed to process due to other reasons |
payment_rejected |
Payment was rejected by Alipay |
Note
- For users with a live account, please send an email to support@omise.co You’ll need to review Terms & Conditions before testing the API.