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.

Flow

The payment flow

  1. When the payee is ready to checkout, they open their Alipay application.
  2. They then click the "Pay" button to generate a unique barcode.
  3. To accept payments, the merchant scans the barcode.
  4. The merchant's server then creates a charge through an API call sent to the Charge API.
  5. The merchant recieves a response. This will include the charge status, which at this stage, is marked pending.
  6. In some cases, the payee may be required to confirm the payment on their Alipay app.
  7. To retrieve the lastest charge status, the merchant makes requests to the Charge API.
  8. The charge status marked as success indicates that the amount has been sucessfully paid, and the products can be handed over.
  9. The charge status marked failed indicates that the amount has not been paid, either because;
    1. Timeout - the payee will need to generate a new barcode to recreate the order.
    2. 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

- Alipay is only available for merchants with a Thai-registered Omise account. We’ll be adding support for other countries soon.

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