Best practice

    Using the Auto Debit product to collect payment is composed of four steps: authorization, auto debit, refund, and settlement. This section provides best practices that all involved parties can follow to integrate Auto Debit successfully.


    #Fields and definitions

    terminalType: the merchant terminal type that the customer uses. Possible values are:

    • WEB: Indicates the terminal is a PC
    • WAP: Indicates the terminal is a mobile website (H5 page)
    • APP: Indicates the terminal is a mobile app

    osType: the merchant mobile operating system, including iOS or Android

    accessToken: used for customer authorization and auto debit from a specific wallet

    refreshToken: used for refreshing the access token when the access token is about to expire

    accessTokenExpiryTime: the expiration time of the access token

    refreshTokenExpiryTime: the expiration time of the refresh token

    authState: an identifier of each customer authorization, used for anti-tamper

    authCode: used for getting the access token, which is created and returned to the merchant after customer authorization succeeds


    #Overall process

    The integration process can be illustrated by the following graphic. For the authorization phase, it is suggested to create a table that contains data about access tokens created for each account. When the access token needs to be refreshed or invalidated, the table will be updated accordingly. For the payment and refund phase, it is suggested to create a table that contains data about the transaction. The table will be updated accordingly when the payment or refund action proceeds.


    Once the authorization is completed, auto debit payment can be performed as long as the access token is valid, without the need to initiate authorization for each payment.

    general process.png

    Figure 1. Overall process of Auto Debit integration


    Details about how to authorize, make a payment, and make a refund are presented in the following sections.


    #Authorization

    During the authorization process, the merchant obtains the user's access token by calling the consult and applyToken interfaces. The access token is used by merchants to directly deduct money from the user's account during the payment phase, with no additional operations required for the user to conduct.


    #Authorization experience

    The authorization process can be initiated by merchants on a PC website, mobile website (H5 page), or mobile phone app. This video shows the authorization experience for these terminals.


    #About access token

    For access tokens that are created by consult and applyToken interfaces, the validity period of each token varies for different wallets and users. Before the access token expires, the merchant can extend the validity period of the token by using the refresh token, to prevent transactions from failing due to access token invalidation.


    It is suggested to maintain a life-cycle table that contains information about the access token, periodically retrieve the access token that is about to expire, and use the refresh token to refresh the access token.


    When a user wants to unbind an access token, the revocation process to invalidate the token can only be initiated by the merchant. The user cannot unbind the access token directly from the wallet. Therefore, the merchant must integrate the revoke interface.


    You can read the following sections to get more information about access token creation and management:


    #Access token creation

    Steps to create an access token:

    1. Call the consult interface to obtain the authorization address (authUrl) of the wallet.
    2. The merchant uses the authUrl to enter the wallet authorization page.
    3. After the user passes the authentication, the wallet is redirected to the merchant URL (authRedirectUrl) with the authcode and authstate fields.
    4. The merchant checks whether the value of the authstate field in the URL is consistent with that in the consult request.
    5. The merchant uses the authcode field in the applyToken request, to obtain the access token and refresh token.


    Note:

    In the preceding steps, authUrl and authcode can be used only once. If the authorization process fails, the merchant needs to call the interface again with an updated value for the authState field in the request. For example, the updated value for the authState field can be made by appending numbers in the end of the previous value, such as authstatexxxx_1.

    图1.png

    Figure 2. Overall process of creating an access token


    1. Call the consult interface

    After receiving the user's request to bind a wallet, the merchant needs to get the authorization address of the wallet by calling the consult interface with the following request URL:

      • Sandbox endpoint: /ams/sandbox/api/v1/authorizations/consult
      • Production endpoint: /ams/api/v1/authorizations/consult

    图2.png

    Figure 3. The process of calling the consult interface


    The following fields need to be configured properly in the request:

      • request.authRedirectUrl: this indicates the address of the merchant to be redirected to after the wallet authorization is completed. In Auto Debit, the authcode field is contained in the merchant URL. Therefore, it is necessary to ensure that the address can be used for redirection to the merchant side. The following table shows the addresses used for different terminal types:

    terminalType of merchant

    Merchants integrated with Alipay directly

    Acquirers

    WEB

    HTTPS address for a PC website of the merchant

    HTTPS address for a PC website

    WAP

    HTTPS address for a mobile web page of the merchant (H5 page)

    HTTPS address for a mobile website page (H5 page)

    APP

    A URL scheme that can be used for redirection to the merchant app

    H5 address to a URL scheme that can be used for redirection to the merchant site  

    Table 1. Addresses for different terminal types


    Notes:

        • For security reasons, the address must be an HTTPS address instead of an HTTP address.
        • For the terminal type of app, the acquirer uses an H5 address that can be redirected a URL scheme, and then the URL scheme can be redirected to the merchant site. In this way, the acquirer does not need to provide different URL schemes for different sub-merchants when calling the consult interface.


      • request.terminalType and request.osType: These represent the terminal type of the merchant that the user initiates the request. Please note that these fields does not represent the terminal type of the wallet that the merchant wants to trigger. The details about the fields are as follows:

    terminalType

    osType

    WEB

    Null

    WAP

    IOS or ANDROID

    APP

    IOS or ANDROID

    Table 2. Details about the terminal types and operation system types


    Processing of return values:

      • If no response is returned, you must call the interface again with the same fields as the previous request.
      • If a response is received, response.result represents the consultation result of the authorization status:
        • When resultStatus is U, call the interface again without changing the value of authState.
        • When resultStatus is F, check the reason for failure based on the value of resultCode.
        • When resultStatus is S, authUrl is returned in the response. The merchant page needs to be redirected to the wallet authorization page address specified by authUrl.

    Note:

    response.authUrl is the address of the wallet authorization page, only when resultStatus is S, this field is returned in the response. The addresses returned for different terminal types are in different types:

    terminalType

    authUrl

    WEB

    An address of the PC brower

    WAP

    An address of a mobile web page (H5 page)

    APP

    An address that can trigger the wallet app

    Table 3. authUrl for different terminal types of the merchant


    1. Redirect to the authorization address

    The authorization address is returned by the authUrl field in the response of the consult interface. The merchant uses the value of authUrl to enter the authorization page of the wallet. authUrl can be used only once during one authorization process. If the authorization fails, a consult request needs to be initiated again to get a new authUrl. The way to redirect to the authUrl address differs for different merchant terminal types:

    Merchant terminal type

    How to open authUrl

    WEB

    Open in browser

    WAP

    Open in browser

    APP-IOS

    openURL

    APP-ANDROID

    startActivity

    Table 4. The way to open authUrl for different terminal types


    For more information about how to open the authUrl address, see Client side integration with wallet.


    Notes:

      • For the terminal type of app, the corresponding URL needs to be able to open the digital wallet app. Therefore, the merchant needs to open the URL through the system. Do not open the link in app embedded WebView, container, or middle page.
      • For more information about the payment terminals each digital wallet supports, see Client side integration with wallet.


    1. Redirect to the merchant URL

    After passing the authentication in the wallet, the user needs to be redirected to the merchant URL (authRedirectUrl) with the authcode and authstate fields. The merchant only needs to use the authcode and authstate fields:

      1. Check whether the value of the authstate field in the URL is consistent with that in the consult request.
      2. Check whether the authCode field has a value. If the authCode field is empty, the authorization fails. If the authCode field is not empty, the value of authCode is to be used for calling the applyToken interface.


    If the user does not start the authenticate process or the authentication process fails, the user will not be redirected to the merchant URL or no authCode is contained in the redirection process. Therefore, the merchant cannot obtain the authCode field. If the merchant does not get authCode within a certain period of time (a suggested time period is 15 minutes), the authorization process needs to be abandoned. If the user needs to rebind, the consult interface is to be initiated again by the merchant.


    The authorization process from the wallet page to the merchant page has different redirection paths for different terminal types. The merchant page is specified by the authRedirectUrl field of the consult interface.

    terminalType

    Redirection to the merchant

    WEB

    From the page for QR code scanning or the authentication page to the merchant website

    WAP

    From the authentication page of the wallet to the merchant's mobile web page (H5 page)

    APP

    • For users with the wallet app installed: trigger the merchant app from the wallet app
    • For users without the wallet app installed: trigger the merchant app from the mobile browser

    Table 5. The way to redirect to merchant page for different terminal types.


    1. Call the applyToken interface

    After getting the authCode value, the applyToken interface is to be called by the backend system immediately in case authCode expires. The validity period of the authCode might be different for each wallet, and the minimum validity period of the wallet is 10 minutes. Alipay requires a minimum time of 1 minute for the authCode validity period of PMP wallets. Therefore, the merchant needs to call the applyToken interface within 1 minute after obtaining the authCode with the following request URL:

      • Sandbox endpoint: /ams/sandbox/api/v1/authorizations/applyToken
      • Production endpoint: /ams/api/v1/authorizations/applyToken

    图3.png

    Figure 4. The process of calling the applyToken interface to get an access token


    Processing of return values:

      • If no response is returned, you must call the interface again with the same fields as the previous request.
      • If a response is received, take the following actions for each case:
        • response.result indicates the result of calling the applyToken interface:
          • When result.resultStatus is S, the authorization is successful.
          • When result.resultStatus is U, call the interface again with the same fields as the previous request.
          • When result.resultStatus is F, the merchant needs to take corresponding actions according to resultCode. Because the authCode can only be used once, the merchant needs to call the consult interface again to reinitiate an authorization process.
        • response.accessToken is the access token after the authorization is completed, which is returned only when result.resultStatus is S.
        • response.accessTokenExpiryTime is the expiration time of the access token. If the merchant uses the access token to initiate payment after the access token expires, the payment is to be failed.
        • response.refreshToken is used to refresh the validity period of the access token before the accessToken expires.
        • response.refreshTokenExpiryTime is the expiration time of the refresh token. Usually, refreshTokenExpiryTime is greater than accessTokenExpiryTime to ensure that refreshToken is usable. If the merchant tries to refresh the validity period of the access token after the refresh token expiration time, there is no guarantee that every wallet will be refreshed successfully.


    #Access token refresh

    Due to risk control requirements, digital wallets in different countries have different validity periods for access tokens. The minimum validity period is one year. The following table shows the validity period of PMP wallets:

    Wallet

    Access token validity period

    Possible to refresh the token?

    Response fields of applyToken interface

    Gcash

    2 years

    Yes

    accessToken accessTokenExpiryTime refreshToken refreshTokenExpiryTime

    Dana

    10 years

    Yes

    accessToken accessTokenExpiryTime refreshToken refreshTokenExpiryTime

    TNG

    2 years

    Yes

    accessToken accessTokenExpiryTime refreshToken refreshTokenExpiryTime

    TrueMoney

    2 years

    Yes

    accessToken accessTokenExpiryTime refreshToken refreshTokenExpiryTime

    AlipayHK

    Until Jan 01, 2038

    Yes

    accessToken accessTokenExpiryTime refreshToken refreshTokenExpiryTime

    Kakaopay

    Until Aug 25, 2120

    No

    accessToken accessTokenExpiryTime

    Table 6. Access token validity period for different wallets


    The merchant needs to refresh the access token before the access token expires. We suggest refreshing the access token at least 10 days before the access token expiration so that Alipay technical support team has enough time to take corresponding actions. Therefore, use the following mechanism to determine the time to initiate the access token refresh process:

    When the current date is less than 10 days from the date specified by accessTokenExpiryTime, call the applyToken interface to refresh the validity period of the access token with the following request URL:

    • Sandbox endpoint: /ams/sandbox/api/v1/authorizations/applyToken
    • Production endpoint: /ams/api/v1/authorizations/applyToken

    For wallets with long access token validity periods, such as KakaoPay, the same rule applies. Therefore, the applyToken interface will not be called until the preset date.

    图4.png

    Figure 5. The process of refreshing the access token


    The following fields need to be configured properly in the request:

    • grantType: The value is REFRESH_TOKEN for the token refresh process.
    • refreshToken: This is a required field. The value of this field is also the value of refreshToken in the response of the applyToken interface when the applyToken interface is called for creating the access token. When using refreshToken to initiate a request, ensure to initiate a call to refresh the token before the accessToken expires.


    Processing of return values:

    • If no response is returned, you must call the interface again with the same fields as the previous request.
    • If a response is received, take the following actions for each case:
      • response.result indicates the result of calling the applyToken interface:
        • When result.resultStatus is S, the validity period of access token is refreshed successfully.
        • When result.resultStatus is U, the merchant needs to call the interface again with the same fields as the previous request.
        • When result.resultStatus is F, the merchant needs to take corresponding actions according to resultCode.
      • response.accessToken is the access token after the refresh process is completed, which is returned only when result.resultStatus is S. Use this value for the auto debit payment process.
      • response.accessTokenExpiryTime is the expiration time of the access token after the refresh process is completed.
      • response.refreshToken is used to elongate the validity period of the access token before the accessToken expires, which is returned only when result.resultStatus is S.


    Notes:

    • Because some wallets might update the value of refreshToken after calling the applyToken interface with grantType of REFRESH_TOKEN, the merchant needs to use the latest refreshToken to elongate the access token validity period.
    • Wallets with a long validity period for the access token do not provide the refreshToken and refreshTokenExpiryTime fields, such as Kakaopay.


    #Access token invalidation

    The user cannot revoke the access token in the wallet. The merchant needs to integrate the revoke interface and initiate the access token revocation process for users with the following request URL:

    • Sandbox endpoint: /ams/sandbox/api/v1/authorizations/revoke
    • Production endpoint: /ams/api/v1/authorizations/revoke

    图5.png

    Figure 6. The process of invalidating the access token


    Processing of return values:

    • If no response is returned, you must call the interface again with the same fields as the previous request.
    • If a response is received, take the following actions for each case:
      • response.result indicates the result of calling the revoke interface:
        • When result.resultStatus is S, the revocation is successful.
        • When result.resultStatus is U, the merchant needs to call the interface again with the same fields as the previous request.
        • When result.resultStatus is F, the merchant needs to take corresponding actions according to resultCode.

    Note:

    If the revocation process succeeds, the access token becomes invalid. If the access token is still used for the auto debit payment, the payment will be failed.


    #Auto debit payment

    After the user completes authorization, the merchant can directly initiate auto debit payments with the access token. There is no need to go through the authorization process again for each payment. For auto debit payments, the pay, inquiryPayment, and cancel interfaces are required to be integrated.

    代扣结果.png

    Figure 7. Process of initiating the payment, inquiry, and cancellation process


    For each transaction, a final payment result needs to be obtained by taking the following actions:

    • In the response of the pay interface, a final payment result is indicated by the resultStatus field with a value of S or F:
      • If the value is S, the payment succeeds.
      • If the value is F, the payment fails.
    • In the response of the pay interface, if the value of the resultStatus field is U, this is an intermediate state. Further actions need to be taken to get the final result of the transaction:
      • Initiate the result inquiry polling process by using the inquiryPayment interface, until the value of paymentStatus is SUCCESS, FAIL, or CANCELLED. The polling time needs to be longer than the Alipay's payment expiration time. Alipay's payment expiration time refers to the period of one minute after the order is placed, during which the user doesn't pay or the wallet doesn't respond. After Alipay's payment expiration time, the order is considered to be failed and is closed.
      • If the transaction needs to be terminated before getting the final payment result, the cancel interface can be called to cancel the transaction.


    #Call /v1/payments/pay

    Call the pay interface to initiate an auto debit with the following request URL:

    • Sandbox endpoint: /ams/sandbox/api/v1/payments/pay
    • Production endpoint: /ams/api/v1/payments/pay


    The following fields need to be configured properly in the request:

    • request.paymentMethod.paymentMethodId : represents the access token obtained after the user completes authorization.


    Processing of return values:

    • If no response is returned, call the interface again with the same fields as the previous request.
    • If a response is received, take the following actions for each case:
      • response.result.resultStatus: indicates the result of the payment:
        • S: This indicates the payment succeeds.
        • F: This indicates the payment fails. For more information about the reason for failure, see resultCode.
        • U: This indicates the payment is still in process. In this case, the inquiryPayment interface needs to be called until the value of paymentStatus is SUCCESS, FAIL, or CANCELLED.
      • response.paymentAmount: This indicates the amount of the payment, which can be used for reconciliation.
      • response.paymentCreateTime: This indicates the time when the payment was initiated.
      • response.paymentTime: This indicates the time when the payment is completed. If the payment fails, this field is not to be returned.


    The inquiryPayment interface is called to query the final status of the transaction. It is suggested to call the inquiry interface in the form of polling:

    Initiate the query at the 1st, 2nd, 4th, 8th, 16th, 32nd, and 80th seconds after the merchant gets the response of the payment interface.


    The request URL is one of the following options:

    • Sandbox endpoint: /ams/sandbox/api/v1/payments/inquiryPayment
    • Prodution endpoint: /ams/api/v1/payments/inquiryPayment


    The following field needs to be configured properly in the request:

    • request.paymentRequestId: The ID that is assigned by the merchant to identify a payment request. We recommend that you use this field to query the transaction status.


    Processing of return values:

    • If no response is returned, call the inquiryPayment interface again after a while.
    • If a response is returned, take the following actions for each case:
      • response.result: indicates whether the inquiryPayment interface is called successfully. This field doesn't indicate the payment result.
      • response.paymentStatus: indicates the payment result of the transaction. This field is returned only when response.result.resultStatus is S. The value of this field can be:
        • SUCCESS: This indicates the payment succeeds. This is a final status of the payment request.
        • FAIL: This indicates the payment fails. This is a final status of the payment request.
        • CANCELLED: This indicates the payment is cancelled. This is a final status of the payment request.
        • PROCESSING: This indicates the payment result is still in process. This is an intermediate state of the payment, therefore, the merchant needs to continue the query process, until a final status of the payment request is obtained.

    Notes:

    • The result inquiry polling time needs to be at least 1 minute longer than the Alipay's payment expiration time.
    • If the transaction needs to be terminated before getting the final payment result, the cancel interface can be called to cancel the transaction.


    The cancel interface can be called in the following cases when the merchant wants to cancel the transaction:

    • The cancel interface can be called when the payment is in process. If the inquiry process cannot get a final payment result, the transaction needs to be cancelled by calling the cancel interface. This action ensures that the transaction status consistency between the user and the merchant.
    • If the merchant needs to cancel the transaction after the payment succeeds, the cancel interface can be called within the cancellable period that is determined in the contract. The cancellation behavior doesn't cause any fee charged, while there are fees to refund a payment.


    The request URL is one of the following options:

    • Sandbox endpoint: /ams/sandbox/api/v1/payments/cancel
    • Production endpoint: /ams/api/v1/payments/cancel


    The following field needs to be configured properly in the request:

    • request.paymentRequestId: The ID that is assigned by the merchant to identify a payment request. We recommend that you use this field to cancel the transaction.


    Processing of return values:

    • If no response is returned, you must call the interface again with the same fields as the previous request.
    • If a response is returned, the value of response.result.resultStatus indicates the result of cancellation process:
      • S: This indicates that the cancellation succeeds.
      • F: This indicates that the cancellation fails. Further actions that needs to be taken are indicated by the resultCode field.
      • U: This indicates that the cancellation process is in an uncertain status. You need to call the cancel interface again. If you retry and fail for 3 times, contact Alipay technical support.


    #Refund

    For transactions that are successfully paid, the merchant can initiate a refund by calling the refund interface or manually initiate a refund through the merchant's back-end. The refundable period is determined by the contract, which is usually 12 months. The request URL is one of the following options:

    • Sandbox endpoint: /ams/sandbox/api/v1/payments/refund
    • Production endpoint: /ams/api/v1/payments/refund

    图6.png

    Figure 8. Refund process



    Processing of return values:

    • If no response is returned, you must call the interface again with the same fields as the previous request.
    • If a response is returned, the value of response.result.resultStatus indicates the refund status:
      • S: This indicates the refund succeeds.
      • U: This indicates the refund is in an uncertain status. You must call the interface again with the same fields as the original request.
      • F: This indicates that the refund fails. Further actions that needs to be taken are indicated by the resultCode field. For example, if a result code of MERCHANT_BALANCE_NOT_ENOUGH is returned, it indicates that the balance of the merchant to be settled is insufficient. That is, the balance of the merchant to be settled is less than the refund amount. Therefore, the merchant needs to wait until successful payments are generated and the balance of the merchant to be settled is greater than the refund amount of the transaction, then initiate the refund process again. When reinitiating the refund process, the value of request.refundRequestId must be updated.
    • response.refundAmount: indicates the refund amount, which can be which can be used for reconciliation.


    Note:

    The difference between the action of refund and the action of cancelling a transaction:

    • The refundable and cancellable period are specified by the contact. By default, the refundable period is 12 months and the cancellable period is 1 day.
    • Fees will be charged for the refund process, while there are no fees to cancel a transaction.
    • The refund process can be used only for a successfully paid transaction. The cancellation process is used for a transaction that does not receive a final payment result of success or failure and is used when the merchant needs to abandon the transaction.
    • The refund process supports partial refund of the transaction, while the cancellation process cancels the entire transaction.


    #About the payment amount and currency

    Currency related data fields exist for both APIs and reconciliation reports. One of them is the payment amount that is presented by the amount field. The amount field has sub fields of currency and value. And all currency fields of Alipay APIs or reports follow the same definition.


    Amount

    Field

    Description

    currency

    MANDATORY String (3)
    The 3-letter currency code that follows the ISO 4217 standard.

    value

    MANDATORY String (16)

    The amount to charge as a positive integer in the smallest currency unit. (That is, 100 cents to charge $1.00, or 100 to charge JPY ¥100, a zero-decimal currency).

    Table 2. Subfields of the amount field.


    Note:

    The actual value in the value field of the amount field is represented in the smallest unit of the currency. Alipay follows the ISO 4217 standard for the definition of the smallest unit of a currency.


    #Smallest unit for different currencies

    Currency Code

    Smallest Unit (Number of the Digits after Decimal)

    Value in the Amount

    USD

    cent (2)

    1.00 USD needs to be set as "value:100"

    PHP

    cent (2)

    1.00 PHP needs to be set as "value:100"

    IDR

    cent (2)

    1.00 IDR needs to be set as "value:100"

    KRW

    yuan (0)

    1 KRW needs to be set as "value:1"

    THB

    cent (2)

    1.00 THB needs to be set as "value: 100"

    HKD

    cent (2)

    1.00 HKD needs to be set as "value: 100"

    MYR

    cent (2)

    1.00 MYR needs to be set as "value: 100"

    CNY

    cent (2)

    1.00 CNY needs to be set as "value: 100"

    BDT

    cent (2)

    1.00 BDT needs to be set as "value: 100"

    PKR

    cent (2)

    1.00 PKR needs to be set as "value: 100"

    Table 3. Details about the currency.


    #Minimum payment or refund amount

    The minimum payment or refund amount differs for each wallet. The following table shows the details of the minimum payment or refund amount of each wallet.


    WalletDetails
    TrueMoney wallet
    • The minimum payment amount allowed for this wallet is 1 THB.
    • The minimum refund amount allowed for this wallet is 1 THB.

    Alipay HK wallet

    • For the auto debit payment, the minimum payment amount allowed for this wallet is 0.01 HKD.
    • For the auto debit payment, the minimum refund amount allowed for this wallet is 0.01 HKD.
    • For the cashier payment, the minimum payment amount allowed for this wallet is 0.1 HKD.
    • For the cashier payment, the minimum refund amount allowed for this wallet is 0.1 HKD.

    Touch'n Go wallet

    • The minimum payment amount allowed for this wallet is 0.1 MYR.
    • The minimum refund amount allowed for this wallet is 0.1 MYR.

    Gcash wallet

    • The minimum payment amount allowed for this wallet is 1 PHP.
    • The minimum refund amount allowed for this wallet is 1 PHP.

    Dana wallet

    • The minimum payment amount allowed for this wallet is 300 IDR.
    • The minimum refund amount allowed for this wallet is 300 IDR.

    bKash wallet

    • The minimum payment amount allowed for this wallet is 0.01 BDT.
    • The minimum refund amount allowed for this wallet is 0.01 BDT.

    EasyPaisa wallet

    • The minimum payment amount allowed for this wallet is 100 PKR.
    • The minimum refund amount allowed for this wallet is 100 PKR.

    KakaoPay wallet

    • The minimum payment amount allowed for this wallet is 50 KRW.
    • The minimum refund amount allowed for this wallet is 50 KRW.

    Table 5. The minimum payment or refund amount for different wallet.