Alipay

Accepting payments through Alipay, one of China's most popular online payment method gives you access to over 450 million registered Chinese consumers. Omise handles payments between the merchant and Alipay allowing you to accept payments without having to setup an Alipay account or registering for a Chinese bank account.

The payment flow

When your customers chooses Alipay as their preferred payment method at checkout, they go through a redirect payment flow. What this means is that they are redirected from the merchant’s website to Alipay’s secure checkout page where they authorize and confirm the payment. Upon completion, the customer is automatically redirected back to the merchant’s website.

Payment Flow1 Payment Flow2

On Alipay’s checkout page, the payment amount is pre-filled for your customer. All they’ve got to do is review and confirm. The currency displayed to your customer will be in the merchant account’s currency (current currency support: THB) and will be automatically converted to CNY by Alipay when it's processed. You’ll receive funds in your Omise account in your account’s currency.

Creating a charge by using Payment Source

Creating an offsite Alipay charge is almost identical to creating an internet banking charge; you need to create source object by using the source api.

The following code demonstrates how to create source.

curl https://api.omise.co/sources \
  -X POST \
  -u skey_test_59rnqoboimgxvjk894d: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "type=alipay"

JSON Response

{
  "object": "source",
  "id": "src_test_59tz6ut89klcihx52ss",
  "type": "alipay",
  "flow": "redirect",
  "amount": 100000,
  "currency": "thb"
}

*Note that when creating source object, you can use either Secret Key or Public Key.

You will then get the result of creating source, the most important attribute is the id which will be used next. Lets assume you got src_test_59tz6ut89klcihx52ss as an id.

Here is a cURL snippet for creating an Alipay charge:

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_59rnqoboimgxvjk894d: \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "source=src_test_59tz6ut89klcihx52ss" \
  -d "return_uri=http://example.com/orders/1235813/complete"

return_uri - is the URI where the customer is redirected back to upon charge completion.

An example of JSON response is shown below.

{
  "object": "charge",
  "id": "chrg_test_59tz85445qe6oj0illy",
  "livemode": false,
  "location": "/charges/chrg_test_59tz85445qe6oj0illy",
  "amount": 100000,
  "currency": "thb",
  "description": null,
  "metadata": {},
  "status": "pending",
  "capture": true,
  "authorized": false,
  "reversed": false,
  "paid": false,
  "transaction": null,
  "refunded": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2017-11-02T07:14:14Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": null,
    "location": "/charges/chrg_test_59tz85445qe6oj0illy/refunds",
    "data": []
  },
  "return_uri": "https://omise.co",
  "reference": "ofsp_test_59tz8545ixmxqjq4vjt",
  "authorize_uri": "http://pay.omise.co/offsites/ofsp_test_59tz8545ixmxqjq4vjt/pay",
  "failure_code": null,
  "failure_message": null,
  "card": null,
  "customer": null,
  "ip": null,
  "dispute": null,
  "created": "2017-11-02T07:14:14Z",
  "source": {
    "object": "source",
    "id": "src_test_59tz6ut89klcihx52ss",
    "type": "alipay",
    "flow": "redirect",
    "amount": 100000,
    "currency": "thb"
  }
}

To proceed to the Alipay checkout page, you’ll need to redirect the customer to the authorize_uri.

*Note: In test mode, copy the URL returned in the authorize_uri and paste it to your browser to proceed with testing.

You can always check the status of the charge by retrieving the charge as described in the Charges API.

  • If both authorized and paid are true, the charge succeeded.
  • If both authorized and paid are false, the charge failed. For detailed explanation on the reason the charge failed, check the failure_code and failure_message in the Charge object.
  • There is no scenario where authorized and paid are different values.

Refund

You can create a full or partial refund through our refund API or from the charge page on your dashboard.

Note: Alipay charges can only be refunded within 3 months of the transaction date.

Webhooks

Rather than relying on the redirection back to the return_uri , we suggest you make use of our Webhook API . Whenever a transaction is completed, a webhook is sent to the URL that is specified in the dashboard with the event name charge.complete

Charge Status

Status Description
successful The payee has successfully made payment (authorized = true and paid = true)
pending Awaiting action from the payee
expired The payee did not pay within 24 hours
failed The charge failed. You can check the reason from the failure_code and failure_message in the charge result.

Failure codes

Code Description
bad_request The amount must be less than or equal to 4900000 (thb subunits)
bad_request Currency is currently not supported
bad_request type is currently not supported
bad_request invalid source
bad_request return_uri is required
not_found source source_id was not found

Creating a charge by adding attribute source[type]

curl https://api.omise.co/charges \
  -X POST \
  -u skey_test_59rnqoboimgxvjk894d: \
  -d "description=Charge for order 3947" \
  -d "amount=100000" \
  -d "currency=thb" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source[type]=alipay”

By the way, charge can also create by adding attribute source[type] but we recommend to create charge by using payment source api.

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.