Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solution

EasySafePay (Android)

This article introduces the integration solution to support accepting payments from a desktop browser or mobile browser. After integration, you can access various payment methods like digital wallets, bank cards, and bank transfers.

User experience

The following screenshots show the user experience of wallet and bank transfer. During the first-time payments, buyers can enable password-free payment for subsequent payments. The entire payment process for subsequent payments will be performed on your website or application.

Wallet

With the entire payment process remaining within your website or application, buyers are allowed to pay and enable password-free payments during their first-time payments and make subsequent payments without the need to enter the payment password.

First-time payment using wallet

During the first-time payments, the buyer completes the authorization process to pay and enable subsequent password-free payments.

Android.webp

Bank transfer

For bank transfer payment methods, the following graphics show the user experience for the first-time and subsequent payments.

First-time payment using bank transfer

During the first-time payments, users need to input the payment password and verification number.

image.png

Payment flow

First-time payment

When a buyer selects a payment method provided by Antom, you need to collect essential information including the payment request ID, order amount, payment method, order description, payment redirect page URL, and payment result notification URL. Susequently, call the createPaymentSession API to place orders and call relevant methods in the Antom SDK to facilitate the payment process.

Easy Pay 首次支付流程图@3x.png

  1. The buyer lands on the checkout page.
  2. Create the createPaymentSession request
    After the buyer selects a payment method and submits the order, you can obtain the payment session by calling the createPaymentSession interface.
  3. Invoke the client SDK
    On the client side, invoke the SDK through the payment session. The SDK will collects payment elements, displays code information, redirects, invokes, and guides the buyer to complete the payment based on the payment method's characteristics.
  4. Get thauthorization result
  • Asynchronous Notification: When the authorization is successful, Antom sends you the asynchronous notification through the notifyAuthorization API.
  • Synchronous Inquiry: Call the inquiryPayment interface to check the authorization status.
  1. Get the payment result
    Obtain the payment result by using one of the following two methods:
  • Asynchronous Notification: Specify the paymentNotifyUrl in the createPaymentSession interface to set the address for receiving asynchronous notifications. When the payment is successful or expires, Antom will use notifyPayment to send asynchronous notifications to you.
  • Synchronous Inquiry: Call the inquiryPayment interface to check the payment status.

Integration steps

You can obtain the buyer's authorization and conduct the EasySafePay by completing the following integration steps:

  1. Create a payment session
  2. Invoke the SDK
  3. Obtain authorization or payment result

Step 1: Create a payment session Server-side

When a buyer selects a payment method provided by Antom, you need to collect essential information including the payment request ID, order amount, payment method, order description, payment redirect page URL, and payment result notification URL. Susequently, call the createPaymentSession API to create a payment session by completing these steps:

  1. Install an API library
  2. Initialize the request instance
  3. Call the createPaymentSession API

Note: Antom provides server-side API libraries for multiple languages. The following codes use Java as an example. You need to install Java 6 or higher.

Install an API library

You can find the latest version on GitHub.

copy
<dependency>
  <groupId>com.alipay.global.sdk</groupId>
  <artifactId>global-open-sdk-java</artifactId>
  <version>2.0.21</version>
</dependency>

Initialize the request instance

Create a singleton resource to make a request to Antom.

copy
import com.alipay.global.api.AlipayClient;
import com.alipay.global.api.DefaultAlipayClient;

String merchantPrivateKey = "YOUR PRIVATE KEY";
String alipayPublicKey = "ALIPAY PUBLIC KEY";
AlipayClient defaultAlipayClient = new DefaultAlipayClient(EndPointConstants.SG,
                merchantPrivateKey, alipayPublicKey);

Create a payment session

First-time payment

Call the createPaymentSession API to create a payment session by specifying the following parameters:

Parameter name

Required

Description

paymentRedirectUrl

The merchant page URL that the buyer is redirected to after the payment is completed.

authState

The unique identifier assigned by you to initiate the authorization, which is used to obtain tokens for subsequent secret-free payments. This parameter must be passed only for the first payment, you do not need to pass this parameter for subsequent payments.

paymentNotifyUrl

Payment result notification address. This address must be HTTPS.

paymentSessionExpiryTime

Timeout for payment session. Default is 1 hour, can be set to a timeout within 1 hour, the format of the value follows the ISO 8601 standard. For example, 2019-11-27T12:01:01+08:00.

userLoginId

The buyer's wallet side login account, which can be the buyer's email address or phone number.

order.buyer: referenceBuyerId/buyerPhoneNo/buyerEmail

Pass in buyer information for risk decisions. Pass in referenceBuyerId, buyerPhoneNo, buyerEmail One of these parameters is sufficient.

Parameters listed above are not comprehensive. See the createPaymentSession (EasySafePay) API for a complete list of parameters and any additional requirements for specific payment methods.

The following sample code shows how to call the createPaymentSession API:

copy
AlipayPaymentSessionRequest alipayPaymentSessionRequest = new AlipayPaymentSessionRequest();
alipayPaymentSessionRequest.setClientId(clientId);
alipayPaymentSessionRequest.setPath("/ams/sandbox/api/v1/payments/createPaymentSession");
alipayPaymentSessionRequest.setProductCode(ProductCodeType.AGREEMENT_PAYMENT);
alipayPaymentSessionRequest.setProductScene(ProductSceneConstants.EASY_PAY);

// replace to your paymentRequestId
alipayPaymentSessionRequest.setPaymentRequestId("paymentRequestId001");

Amount amount = new Amount();
// set amount
amount.setCurrency("CNY");
amount.setValue("100");
alipayPaymentSessionRequest.setPaymentAmount(amount);

//set settlement currency
SettlementStrategy settlementStrategy = new SettlementStrategy();
settlementStrategy.setSettlementCurrency("USD");
alipayPaymentSessionRequest.setSettlementStrategy(settlementStrategy);

// set agreementInfo
AgreementInfo agreementInfo = new AgreementInfo();
agreementInfo.setAuthState("authState001");
agreementInfo.setUserLoginId("userLoginId001");
alipayPaymentSessionRequest.setAgreementInfo(agreementInfo);

// set paymentMethod
PaymentMethod paymentMethod = new PaymentMethod();
paymentMethod.setPaymentMethodType("ALIPAY_CN");

// set order Info
Order order = new Order();
order.setReferenceOrderId("referenceOrderId001");
order.setOrderDescription("orderDescription001");
order.setOrderAmount(amount);
Buyer buyer = new Buyer();
buyer.setReferenceBuyerId("referenceBuyerId001");
order.setBuyer(buyer);
order.setOrderAmount(amount);
alipayPaymentSessionRequest.setOrder(order);

// replace to your redirect url
alipayPaymentSessionRequest.setPaymentNotifyUrl("https://www.yourNotifyUrl");
alipayPaymentSessionRequest.setPaymentRedirectUrl("https://www.yourMerchantWeb.com");

AlipayPaymentSessionResponse alipayPaymentSessionResponse = defaultAlipayClient
        .execute(alipayPaymentSessionRequest);

The following code shows a sample of the request message:

copy
{
    "settlementStrategy": {
        "settlementCurrency": "USD"
    },
    "productCode": "AGREEMENT_PAYMENT",
    "productScene": "EASY_PAY",
    "paymentNotifyUrl": "https://www.yourNotifyUrl",
    "paymentRequestId": "paymentRequestId001",
    "paymentRedirectUrl": "https://www.yourMerchantWeb.com",
    "paymentMethod": {
        "paymentMethodType": "ALIPAY_CN"
    },
    "agreementInfo": {
        "authState": "authState001",
        "userLoginId":"userLoginId001"
    },
    "paymentAmount": {
        "currency": "CNY",
        "value": "100"
    },
    "order": {
        "orderAmount": {
            "currency": "CNY",
            "value": "100"
        },
        "referenceOrderId": "referenceOrderId001",
        "orderDescription": "orderDescription001",
        "buyer":{
          "referenceBuyerId":"referenceBuyerId001"
        }
        
    }
}

The following code shows a sample of the response, which contains the following parameters:

  • paymentSessionData: the payment session data, which needs to be forwarded to your client.
  • paymentSessionExpiryTime: the expiration time of the payment session.
copy
{
  "paymentSessionData": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Kvvmsdk+akdLvoShW5avHX8e8J15P8uNVEf/PcCMyXg==&&SG&&111",
  "paymentSessionExpiryTime": "2023-04-06T03:28:49+08:00",
  "paymentSessionId": "UNvjVWnWPXJA4BgW+vfjsQj7PbOraafHY19X+6EqMz6Ikyj9FPVUOpv+DjiIZqMe",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

Common questions

Q: Can I use Chinese characters in the value of the request parameters?

A: To avoid incompatibility of a certain payment method, do not use Chinese characters for fields in the request.

Q: How to set the URL to receive the payment notification?

A: Specify paymentNotifyUrl in the createPaymentSession API to receive the asynchronous notification about the payment result (notifyPayment), or configure the receiving URL in Antom Dashboard. If the URL is specified in both the request and Antom Dashboard, the value specified in the request takes precedence.

Step 2: Invoke the SDK Client-side

Install

Version Requirements: target at least Android 4.4 (API level 19) or higher.

To integrate the SDK package, please refer to Integrate the SDK Package.

Instantiate the SDK

Create an SDK instance and specify basic configurations. Creating a configuration object includes the following methods:

Parameter name

Required

Description

setLocale

Used to specify the language information. Select the appropriate value based on the region of the payment method. Valid values for this parameter are listed as follows. If a value not in the following list is used, the local language is used instead.

  • en_US: English
  • in_ID: Indonesian
  • th_TH: Thai
  • ms_MY: Malay
  • tl_PH: Filipino
  • ko_KR: Korean
  • vi_VN: Vietnamese
  • zh_HK: Traditional Chinese

setOption

Used to specify whether to use the default loading pattern and the sandbox environment. Valid values are:

  • "sandbox", "true": Sandbox environment
  • "sandbox", "false": Production environment
  • "showLoading", "true": Use the default loading pattern.
  • "showLoading", "false": Do not use the default loading pattern.
  • "windowGravity","LANDSCAPE_CENTER": Center the window in landscape mode.
  • "windowGravity","LANDSCAPE_RIGHT": Align the window to the right in landscape mode.

The following sample code shows how to instantiate the SDK:

copy
// Step 1: Create the AMSEasyPayConfiguration type.
AMSEasyPayConfiguration configuration = new AMSEasyPayConfiguration();
configuration.setLocale(new Locale("en", "US"));
// Specify showLoading as true (default value) to use the default loading pattern. Specify it as false to customize the loading animation based on onEventCallback.
configuration.setOption("showLoading", "true");
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
configuration.setOption("sandbox", "true");
// Set the callback to monitor payment events on the checkout page.
configuration.setOnCheckoutListener(new OnCheckoutListener() {
    @Override
    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
        if("SDK_PAYMENT_CANCEL".equals(eventCode)){
            // Add interactive prompts.
        }
        Toast.makeText(activity, "eventCode=" + eventCode + " message=" + message, Toast.LENGTH_SHORT).show();
    }
});

// Instantiate AMSEasyPay. Create a new AMSEasyPay component before each createPaymentSession API request.
AMSEasyPay checkout = new AMSEasyPay.Builder(activity, configuration).build();

Invoke the SDK

Call createComponent:

Parameter name

Required

Description

sessionData

Create a configuration object by using the sessionData parameter: Use the complete data of the value of paymentSessionData obtained in the response of the createPaymentSession (EasySafePay) API as the value of this parameter.

Call onDestroy to free SDK component resources in the following situations:

  • When the buyer exits the checkout page, free the component resources created in the createPaymentSession API.
  • When the buyer initiates multiple payments, free the component resources created in the previous createPaymentSession API.

The following sample code shows how to invoke the SDK:

copy
checkout.createComponent(activity, sessionData);

//Free SDK component resources
checkout.onDestroy();

Step 3: Obtain authorization or payment result Server-side

For first-time payments, you can obtain both the authorization and payment results, while for subsequent payments, only the payment result is available.

You can obtain the authorization or payment result by one of the following methods:

  • Receive the asynchronous notification
  • Inquire about the result

Receive the asynchronous notification

Obtain the authorization result

When the authorization is successful, Antom sends you the asynchronous notification through the notifyAuthorization API. When you receive the notification, you must return a response as instructed in Requirements. Meanwhile, you must update the authorization status of the buyer in your system and display the buyer's desensitized account obtained from the notification on your authorization management page.

The following code shows a sample of the notification request:

copy
{
  "accessToken": "2810123456789012345678901234567890",
  "authState": "AUTHSTATE_SAMPLE_1234567890",
  "authorizationNotifyType": "TOKEN_CREATED",
  "userLoginId": "852-52***184",
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success.",
    "resultStatus": "S"
  }
}

How to verify the signature of the notification and make a response to the notification, see Sign a request and verify the signature.

Common questions

Q: When will the payment result notification be sent?

A: It depends on whether the payment is completed:

  • If the payment is successfully completed, Antom will usually send you an asynchronous notification within 3 to 5 seconds. For some payment methods like OTC, the notification might take a bit longer.
  • If the payment is not completed, Antom needs to close the order first before sending an asynchronous notification. The time it takes for different payment methods to close the order varies, usually defaulting to 14 minutes.

Q: Will the asynchronous notification be re-sent?

A: Yes, the asynchronous notification will be re-sent automatically within 24 hours for the following cases:

  • If you didn't receive the asynchronous notification due to network reasons;
  • If you receive an asynchronous notification from Antom, but you didn't make a response to the notification in the Sample code format.

The notification can be resent up to 8 times or until a correct response is received to terminate delivery. The sending intervals are as follows: 0 minutes, 2 minutes, 10 minutes, 10 minutes, 1 hour, 2 hours, 6 hours, and 15 hours.

Q: When responding to asynchronous notification, do I need to add a digital signature?

A: If you receive an asynchronous notification from Antom, you are required to return the response in the Sample code format, but you do not need to countersign the response.

Q: What are the key parameters in the payment result notification that I need to use?

A: Pay attention to the following key parameters:

  • result: indicates the payment result of the order.
  • paymentRequestId: indicates the payment request number you generated for consult, cancel, and reconciliation.
  • paymentId: indicates the payment order number generated by Antom used for refund and reconciliation.
  • paymentAmount: indicates the payment amount.

Q: What are the key parameters in the authorization result notification that I need to use?

A: Pay attention to the following key parameters:

  • result: represents the payment result of the order.
  • authState: the vaulting request ID generated by the merchant.
  • accessToken: the auto debit ID generated by Antom used for subsequent payment.
  • userLoginId: the user's desensitized account number.

Inquire about the payment result

You can call the inquiryPayment API to initiate a query on the result of an order.

Parameter name

Required

Description

paymentRequestId

The payment request ID generated by you.

The parameter is not a full set of parameters, please refer to the inquiryPayment API for full set of parameters and additional requirements for certain payment methods.

The following sample code shows how to call the inquiryPayment API:

copy

AlipayClient defaultAlipayClient = new DefaultAlipayClient(EndPointConstants.SG,
                merchantPrivateKey, alipayPublicKey);

AlipayPayQueryRequest alipayPayQueryRequest = new AlipayPayQueryRequest();
alipayPayQueryRequest.setClientId(CLIENT_ID);
alipayPayQueryRequest.setPath("/ams/sandbox/api/v1/payments/inquiryPayment");

AlipayPayQueryResponse alipayPayQueryResponse;
    try {
        alipayPayQueryResponse = defaultAlipayClient.execute(alipayPayQueryRequest);
    } catch (AlipayApiException e) {
       String errorMsg = e.getMessage();
            // handle error condition
    }

The following code shows a sample of the request message:

copy
{
  "paymentRequestId": "2019060811401080010018882020035****"
}

The following code shows a sample of the response message:

copy
{
  "result": {
    "resultCode": "SUCCESS",
    "resultStatus": "S",
    "resultMessage": "Success"
  },
  "paymentStatus": "SUCCESS",
  "paymentRequestId": "pay_1089760038715669_10277574507XXXX",
  "paymentId": "2019060811401080010018882020035XXXX",
  "paymentAmount": {
    "value": "4200",
    "currency": "SGD"
  },
  "paymentCreateTime": "2019-06-01T12:01:01+08:30",
  "paymentTime": "2019-06-01T12:01:01+08:30",
  "transactions": null
}

Common questions

Q: How often should I call the inquiryPayment API?

A: Call the inquiryPayment API constantly with an interval of 2 seconds until the final payment result is obtained or an asynchronous payment result notification is received.

Q: What are the key parameters in the notification that I need to use?

A: Pay attention to these key parameters:

  • result: represents the result of this inquiryPayment API call, the result of the order needs to be judged according to paymentStatus:
    • SUCCESS and FAIL represent the final result;
    • PROCESSING represents the processing.
  • paymentAmount: indicates the payment amount.

Sample codes

Complete sample code for using the client SDK:

copy
// Step 1: Create the AMSEasyPayConfiguration type.
AMSEasyPayConfiguration configuration = new AMSEasyPayConfiguration();
configuration.setLocale(new Locale("en", "US"));
// Specify showLoading as true (default value) to use the default loading pattern. Specify it as false to customize the loading animation based on onEventCallback.
configuration.setOption("showLoading", "true");
// Set the sandbox environment. If you leave it empty, the production environment is used by default.
configuration.setOption("sandbox", "true");
// Center the window in landscape mode, or align it to the right if not set.
configuration.setOption("windowGravity", "LANDSCAPE_CENTER");
// Set the callback to monitor payment events on the checkout page.
configuration.setOnCheckoutListener(new OnCheckoutListener() {
    @Override
    public void onEventCallback(String eventCode, AMSEventResult eventResult) {
        if("SDK_PAYMENT_CANCEL".equals(eventCode)){
            // Add interactive prompts.
        }
        Toast.makeText(activity, "eventCode=" + eventCode + " message=" + message, Toast.LENGTH_SHORT).show();
    }
});
// Instantiate AMSEasyPay. Create a new AMSEasyPay component before each createPaymentSession API request.
AMSEasyPay checkout = new AMSEasyPay.Builder(activity, configuration).build();

// Step 2: Call createPaymentSession API.
String sessionData = createSessionData()

// Step 3: Initialize the payment and pass the sessionData to the front-end component.
checkout.createComponent(activity,sessionData);

//Step 4: Call onDestroy() method when the buyer exits the merchant page.
checkout.onDestroy(activity,sessionData);

Event codes

You might see two types of event codes:

  • Status codes: Returned by onEventCallback during the component's runtime lifecycle.
  • Error codes: Returned by onEventCallback or onError during the component initialization phase.

Type

Code

Description

Further action

Status codes

SDK_START_OF_LOADING

The loading animation starts to be shown when the component is created. When configured to hide loading and use a custom animation, the custom animation can be rendered at this time.

No further action.

SDK_END_OF_LOADING

The loading animation ends when the component is created. When configured to hide loading and use custom animation, the animation can be hidden at this time.

No further action.

SDK_CALL_URL_ERROR

  • This event code represents one of the following situations in the event information:
    • Failed to redirect to merchant page.
    • Failed to redirect to the 3D challenge page.
    • The paymentRedirectUrl parameter is not specified or is not correctly specified when calling the createPaymentSession request.

In the Web or WAP scenario, redirecting links is usually not abnormal. It is recommended that you verify the redirected link. In the app scenario, if this exception frequently occurs, contact Antom Technical Support to troubleshoot redirection or calling issues.

No further action.

Error codes

SDK_INTERNAL_ERROR

SDK internal error.Contact Antom Technical Support.

SDK_CREATEPAYMENT_PARAMETER_ERROR

mountComponent method specified parameter abnormally.Check if the parameters are correct and reinitialize the component.

SDK_INIT_PARAMETER_ERROR

AMSEasyPay method specified parameter abnormally.Check if the parameters are correct and re-instantiate the SDK.

SDK_CREATECOMPONENT_ERROR

Component initialization exception.Contact Antom Technical Support.

SDK_SUBMIT_NETWORK_ERROR

Interface call failed due to network reasons. It may occur in submit method submission.Try to submit it again.