quick_start_en.md

Quick Start Guide

中文

Table of Contents

• Client Setup
  • Ruby
  • Ruby on Rails
• Create Payment
  • Desktop
  • Mobile
  • QR Code
  • Installment Plan
  • Verify Callback
  • Query Payment Status
• Stop Payment
  • Close Payment
  • Cancel Payment
• Refund Payment
  • Initiate Refund
  • Query Refund Status
• Fund Transfer
  • Transfer Fund to Customer
  • Query Fund Transfer

Client Setup

All examples in the quick start guide assume you have properly setup the client.

Ruby

# put your Alipay credentials here
API_URL: 'https://openapi.alipaydev.com/gateway.do'
APP_ID: '2016000000000000'
APP_PRIVATE_KEY: "-----BEGIN RSA PRIVATE KEY-----\nxkbt...4Wt7tl\n-----END RSA PRIVATE KEY-----\n"
ALIPAY_PUBLIC_KEY: "-----BEGIN PUBLIC KEY-----\nTq43T5...OVUAQb3R\n-----END PUBLIC KEY-----\n"

# set up a client to talk to the Alipay API
@client = Alipay::Client.new(
  url: API_URL,
  app_id: APP_ID,
  app_private_key: APP_PRIVATE_KEY,
  alipay_public_key: ALIPAY_PUBLIC_KEY
)

Ruby on Rails

You can save your Alipay credentials as environment variables or set them up using initializer.

This guide will demonstrate setting up the Alipay client with the dotenv-rails gem.

In your Gemfile

# Gemfile
gem 'alipay', '~> 0.15.0'
gem 'dotenv-rails', '~> 2.2', '>= 2.2.1'

Then run

$ bundle install

Create an .env file

# .env
APP_ID=2016000000000000
ALIPAY_API=https://openapi.alipaydev.com/gateway.do
APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nxkbt...4Wt7tl\n-----END RSA PRIVATE KEY-----\n"
ALIPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nTq43T5...OVUAQb3R\n-----END PUBLIC KEY-----\n"

In your Ruby on Rails application, you can create an Alipay client instance like this:

@client = Alipay::Client.new(
  url: ENV['ALIPAY_API'],
  app_id: ENV['APP_ID'],
  app_private_key: ENV['APP_PRIVATE_KEY'],
  alipay_public_key: ENV['ALIPAY_PUBLIC_KEY']
)

Create Payment

Desktop

API Method

alipay.trade.page.pay

This API method is for creating payment transaction that is suitable for customers using various desktop (PC) environment.

Client Method

Alipay::Client.page_execute_url

This client method will generate a payment URL for redirecting customers to.

Example

@client.page_execute_url(
  method: 'alipay.trade.page.pay',
  return_url: 'https://mystore.com/orders/20160401000000/return',
  notify_url: 'https://mystore.com/orders/20160401000000/notify',
  biz_content: JSON.generate({
   out_trade_no: '20160401000000',
   product_code: 'FAST_INSTANT_TRADE_PAY',
   total_amount: '0.01',
   subject: 'Example #123'
  }, ascii_only: true)
)
# => 'https://openapi.alipaydev.com/gateway.do?app_id=2016...'

Notable Parameters

• return_url is where Alipay will redirect customers to after a successful payment is made. The redirect will be sent via a GET request. This is an optional parameter.
• notify_url is where Alipay will send async callbacks to via POST request after a successful payment. This is an optional parameter.
• out_trade_no is a unique string set by you. It is expected to be in reference to a model ID in your application. Although it is not a strict requirement.
• total_amount should be in decimal form with a maximum scale of 2. For example 5123.99 will be ￥5,123.99 in text form. 5123.999 is not a valid parameter.

For a complete list of the available parameters, please refer to the API documentation.

Mobile

API Method

alipay.trade.wap.pay

This API method is for creating payment transaction for customers on a mobile device. It has the ability to transfer the payment process over to the native Alipay application if the application is installed on the customer's device. If not, the customer will be redirected to a mobile HTML version of the payment page.

Client Method

Alipay::Client.page_execute_url

This method will generate a payment URL for redirecting customers to.

Example

@client.page_execute_url(
  method: 'alipay.trade.wap.pay',
  return_url: 'https://mystore.com/orders/20160401000000/return',
  notify_url: 'https://mystore.com/orders/20160401000000/notify',
  biz_content: JSON.generate({
   out_trade_no: '20160401000000',
   product_code: 'QUICK_WAP_WAY',
   total_amount: '0.01',
   subject: 'Example: 456'
   quit_url: 'https://mystore.com/orders/20160401000000/'
  }, ascii_only: true)
)
# => 'https://openapi.alipaydev.com/gateway.do?app_id=2016...'

Notebale Parameters

• quit_url is where Alipay will redirect customer to if the customer have completed the payment or have exited the payment process. This redirect only applies to the mobile html verison. This is an optional parameter.

For a complete list of the available parameters, please refer to the API documentation.

QR Code

API Method

alipay.trade.precreate

This API method generates a payment URL that can be transformed into a QR code for customers to scan. A callback will be issued to the defined notify_url if payment is successful.

Client Method

Alipay::Client.execute

Example

# Create a QR code based payment
response = @client.execute(
  method: 'alipay.trade.precreate',
  notify_url: 'https://mystore.com/orders/20160401000000/notify',
  biz_content: JSON.generate({
    out_trade_no: '20160401000000',
    total_amount: '50.00',
    subject: 'QR Code Test'
  }, ascii_only: true)
)
# => '{\"alipay_trade_precreate_response\":{\"code\"...'

# Get payment url to render as QR code for customer
qr_code = JSON.parse(response)["alipay_trade_precreate_response"]["qr_code"]
# => 'https://qr.alipay.com/abcdefggfedcba'

For a complete list of the available parameters, please refer to the API documentation.

Installment Plan

API Methods

alipay.trade.page.pay  (Desktop / PC)
alipay.trade.wap.pay  (Mobile)
alipay.trade.precreate  (QR Code)

Client Method

Alipay::Client.page_execute_url  (Desktop / PC / Mobile)
Alipay::Client.execute  (QR Code)

Example

Scenario: Customer pre-select a six-installment payment plan before going through the payment process at Alipay.

@client.page_execute_url(
  method: 'alipay.trade.page.pay',
  return_url: 'https://mystore.com/orders/20160401000000/return',
  notify_url: 'https://mystore.com/orders/20160401000000/notify',
  biz_content: JSON.generate({
   out_trade_no: '20160401000000',
   product_code: 'FAST_INSTANT_TRADE_PAY',
   total_amount: '0.01',
   subject: 'Example #654',
   enable_pay_channels: 'balance,pcreditpayInstallment',
   extend_params: {
     hb_fq_num: '6'',
     hb_fq_seller_percent: '0'
   }
  }, ascii_only: true)
)

Scenario: Customer select an installment plan or their choice at Alipay's payment page.

@client.page_execute_url(
  method: 'alipay.trade.page.pay',
  return_url: 'https://mystore.com/orders/20160401000000/return',
  notify_url: 'https://mystore.com/orders/20160401000000/notify',
  biz_content: JSON.generate({
   out_trade_no: '20160401000000',
   product_code: 'FAST_INSTANT_TRADE_PAY',
   total_amount: '0.01',
   subject: 'Example #654',
   enable_pay_channels: 'balance,pcreditpayInstallment',
  }, ascii_only: true)
)

Notebale Parameters

• enable_pay_channels defines the funding methods that the customer can use to pay for your order. pcreditpayInstallment is the value to enable installment plans. Mutiple values can be enabled by sperating the values by , like the example above.
• hb_fq_num defines the number of installments. Valid values are 3, 6, or 12.
• hb_fq_seller_percent defines the percentage of credit installment fee the seller is responsiable for. Valid value is 0 where the customer bare all the fees. Another valid value is 100 where you bare all the fees. However it only becomes valid if you have a special contract signed with Alipay.

For a complete list of the available parameters, please refer to the API documentation.

Verify Callback

Client Method

Alipay::Client.verify?

This client method will verify the validity of response params send by Alipay using Alipay's public key.

Example

params = {
  out_trade_no: '20160401000000',
  trade_status: 'TRADE_SUCCESS'
  sign_type: 'RSA2',
  sign: '...'
}
@client.verify?(params)
# => true / false

Verify GET return_url

Alipay will send your customer via GET request to your specified return_url, if it was previously defined during the payment creation process. Here is an example of how to verify response params from Alipay in your controller.

@client.verify?(request.query_parameters)
# => true / false

Verify POST notify_url

Alipay will send POST request to your specified notify_url, if it was previously defined during the payment creation process. Your controller action should response 'success' in plain text or Alipay will keep on sending POST requests in increasing intervals.

if @client.verify?(request.request_parameters)
  render plain: 'success'
end

Query Payment Status

API Method

alipay.trade.query

This API method is for querying payment status after the payment is created. It suitable for situations when callbacks fail or when the created payment did not set callback parameters.

Client Method

Alipay::Client.execute

Example

response = @client.execute(
  method: 'alipay.trade.query',
  biz_content: JSON.generate({
    trade_no: '2013112611001004680073956707',
  }, ascii_only: true)
)
# => '{\"alipay_trade_query_response\":{\"code\"...'

# Get payment status
result_status = JSON.parse(response)["alipay_trade_query_response"]["trade_status"]
# => 'TRADE_SUCCESS'

Notable Parameters

• trade_no is the payment identification string provided by Alipay via callback after the payment is created. If you do not have this on hand, you can provide the out_trade_no instead.

For a complete list of the available parameters, please refer to the API documentation.

Stop Payment

Close Payment

API Method

alipay.trade.close

This API method is for closing inactive payment if you don't want to wait for Alipay to close out the payment at its default expiration time.

Client Method

Alipay::Client.execute

Example

response = @client.execute(
  method: 'alipay.trade.close',
  notify_url: 'https://mystore.com/orders/20160401000000/notify',
  biz_content: JSON.generate({
    trade_no: '2013112611001004680073956707',
  }, ascii_only: true)
)
# => '{\"alipay_trade_close_response\":{\"code\"...'

# Get request result
result_code = JSON.parse(response)["alipay_trade_close_response"]["code"]
# => '10000'

Notable Parameters

• trade_no is the payment identification that Alipay returned to you after the payment was pre-created. If you do not have this parameter on hand, you can stub in the 'out_trade_no' that you used using the payment creation process.

For a complete list of the available parameters, please refer to the API documentation.

Cancel Payment

API Method

alipay.trade.cancel

This API method is for canceling stuck payment or payment that errors out due to either Alipay or your own application. If the customer has successfully made the payment. A refund will be made. If customers had not pay yet, the payment transaction will be close. You can check if a refund had been made by getting the action value from the request response.

Client Method

Alipay::Client.execute

Example

response = @client.execute(
  method: 'alipay.trade.cancel',
  biz_content: JSON.generate({
    out_trade_no: '20160401000000',
  }, ascii_only: true)
)
# => '{\"alipay_trade_cancel_response\":{\"code\"...'

# Get cancellation result
result_action = JSON.parse(response)["alipay_trade_cancel_response"]["action"]
# => 'close'

Notable Parameters

• out_trade_no is a unique string that you provided during the payment creation process. You must provide either out_trade_no or trade_no in order for the API call to be successful.

For a complete list of the available parameters, please refer to the API documentation.

Refund Payment

Initiate Refund

API Method

alipay.trade.refund

This API method is for initiating refunds to customers. Only made this API call if the payment has not passed the refund period defined by Alipay. Multiple or partial refunds are also available through this API.

Client Method

Alipay::Client.execute

Example

Secenario: Customer request refund on a ￥10.12 item on a ￥210.85 order(payment).

response = @client.execute(
  method: 'alipay.trade.refund',
  biz_content: JSON.generate({
    out_trade_no: '6c50789a0610',
    out_request_no: '6c50789a0610-1',
    refund_amount: '10.12'
  }, ascii_only: true)
)
# => '{\"alipay_trade_refund_response\":{\"code\"...'

# Get result
result_code = JSON.parse(response)["alipay_trade_refund_response"]["code"]
# => '10000'

result_fund_change = JSON.parse(response)["alipay_trade_refund_response"]["fund_change"]
# => 'Y'

Notable Parameters

• out_request_no is an conditional optional parameter. It is required when you make a partial refund or plan to make multiple refunds. It serves as identification for the refund transaction. It is optional when you refund the entire payment amount.
• refund_amount is the amount you wish to refund to the customer. It can be lower than the original payment amount. However, if you have previously issued partial refunds on a payment, the sum of refund_amount cannot exceed the original payment amount.

For a complete list of the available parameters, please refer to the API documentation.

Query Refund Status

API Method

alipay.trade.fastpay.refund.query

This API method is for querying refund status.

Client Method

Alipay::Client.execute

Example

response = @client.execute(
  method: 'alipay.trade.fastpay.refund.query',
  biz_content: JSON.generate({
    out_trade_no: '6c50789a0610',
    out_request_no: '6c50789a0610-1'
  }, ascii_only: true)
)
# => '{\"alipay_trade_fastpay_refund_query_response\":{\"code\"...'

# Get refund amount
result_refund_amount = JSON.parse(response)["alipay_trade_fastpay_refund_query_response"]["refund_amount"]
# => '10.12'

Notable Parameters

• out_request_no is the identifying string provided by you provided when you initiated the refund. If you did not provide this parameter when the refund was initiated, use the out_trade_no as your out_request_no.

For a complete list of the available parameters, please refer to the API documentation.

Fund Transfer

Transfer Fund to Customer

API Method

alipay.fund.trans.toaccount.transfer

This API method is for creating a fund transfer to customers from your Alipay account.

Client Method

Alipay::Client.execute

Example

response = @client.execute(
  method: 'alipay.fund.trans.toaccount.transfer',
  biz_content: JSON.generate({
    out_biz_no: '3142321423432',
    payee_type: 'ALIPAY_LOGONID',
    payee_account: '[email protected]',
    amount: '12.23'
  }, ascii_only: true)
)
# => '{\"alipay_fund_trans_toaccount_transfer_response\":{\"code\"...'

# Get order ID
result_order_id = JSON.parse(response)["alipay_fund_trans_toaccount_transfer_response"]["order_id"]
# => '20160627110070001502260006780837'

Notable Parameters

• out_biz_no is a unique identifying string provided by you for reference purposes.
• payee_type is for defining the type of payee_account that is provided. Valid values are ALIPAY_USERID for customer's Alipay user ID starting with 2088 and ALIPAY_LOGONID for customer cellular number or email address.
• payee_account is the customer Alipay ID, email or cellular number. It must match the payee_type provided.
• amount is the amount you wish to transfer to the customer. (e.g. ￥123.50 is 123.50)

For a complete list of the available parameters, please refer to the API documentation.

Query Fund Transfer

API Method

alipay.fund.trans.order.query

This API method is for querying fund transfer status.

Client Method

Alipay::Client.execute

Example

response = @client.execute(
  method: 'alipay.fund.trans.order.query',
  biz_content: JSON.generate({
    out_biz_no: '3142321423432',
  }, ascii_only: true)
)
# => '{\"alipay_fund_trans_order_query_response\":{\"code\"...'

# Get refund_status
refund_status = JSON.parse(response)["alipay_fund_trans_order_query_response"]["status"]
# => 'SUCCESS'

# Get expected refund date
refund_status = JSON.parse(response)["alipay_fund_trans_order_query_response"]["arrival_time_end"]
# => '2018-01-01 08:08:08'

Notable Parameters

• 'order_id' is the order id provided by Alipay when the transfer request was created. If you do not have this on hand, you can stub in out_biz_no instead.

For a complete list of the available parameters, please refer to the API documentation.