alipay.intl.oauth.auth.prepareForRedirect

You can use this interface to redirect users to the URL that is specified by the authsiteurl field and allow users to enter payment password. In this case, AlipayHK generates a one-time-passcode Authcode that will be appended in the alipay.intl.oauth.auth.redirectAuthResultPage URL.

URL sample:

https://www.merchant.com/authResult.html?client_id=2014101500013658&auth_site=ALIPAY_HK&auth_code=ca34ea491e7146cc87d25fca24c4cD11&merchantAgreementId=e8qdwl9casxor13&state=4657DDUER323DK

After user fiinished authorization within AlipayHK app, AlipayHK will open a H5 page with following parameters send to merchantRedirectUrl for merchant to apply payment token.

No

Name

Description

Type

Required

Remarks

Sample

1

state

Merchant dynamic value for the state from api request to authenticate a redirection from the auth site.

string

Y

4657DDUER323DK

2

auth_site

The site which can authorize the user.

string

Y

Fixed value

ALIPAY_HK

3

merchantAgreementId

Merchant aggreement Id provide from api request.

string

Y

e8qdwl9casxor13

4

authCode

One time passcode return from Alipay

string

Y

Use for alipay.intl.oauth.auth.applyToken Api

28100413kpBklrvUk33YgGgC9yS2o679

5

client_id

Auth merchant ID.

string

Y

2160400000002012

Request Parameters

Header

No

Name

Description

Type

Length

Required

Remarks

Sample

1

version

API version

string

8

Y

As per the respective API reference

2.0.0

2

function

API interface

string

128

Y

According to specifications defined by each business domain

alipay.intl.oauth.auth.prepareForRedirect

3

clientId

Client ID

string

32

Y

Provided by AlipayHK, used to identify partner and application system

4Q5XPV2N361Y0600

4

reqTime

Request time

datetime

/

Y

DateTime with timezone, which follows the ISO-8601 standard.
Refer to: RFC 3339 Section 5.6

2001-07-04T12:08:56+05:30

5

reqMsgId

Request message ID

string

64

Y

Each request will be assigned with a unique id (uuid).
The reqMsgId identify an unique system request, it is not used to identity an unique business request.

1234567asdfasdf1123fda

6

reserve

Reserved for future implementation

string

256

N

Object with Key/Value

Cannot be null value

{}

Body

No

Name

Description

Type

Length

Required

Remarks

Sample

1

authMerchantId

Auth merchant ID. The auth merchant can be authorized by the user to access user resources.

string

64

Y

2160400000002012

2

authSite

The site which can authorize the user.

enum

64

Y

Fixed value

ALIPAY_HK

3

scopes

The scopes of the authorization.

list<string>

256

Y

Fixed value

["AUTH_AGREEMENTPAY"]

4

terminalType

Terminal type

enum

32

Y

Indicates the source terminal type and how the redirect will happen

WEB

5

merchantRedirectUrl

Merchant redirect url. It can be passed in each call, or configure it once on AlipayHK side.

string

512

Y

https://www.alipay.com/

6

state

When provided, this parameter would be posted back in the redirection to the redirectUrl. This is a mechanism to prevent the CRSF attack. Merchant is suggested to generate a dynamic value for the state, so that it could be used to authenticate a redirection from the auth site.

string

256

Y

4657DDUER323DK

7

agreementPayAuthInfo

Agreement pay authorization information. If scope is AUTH_AGREEMENTPAY, agreementPayAuthInfo is mandatary.

AgreementPayAuthInfo

/

Y

{
"merchantAgreementId":"e8qdwl9casxor13"
}

8

extendInfo

Reserved for extended info

string

2048

Y

Object with Key/Value

Object must contain agreementMark object

{"agreementMark":"137352934538","billNo":"A1234"}

AgreementPayAuthInfo

No

Name

Description

Type

Length

Required

Remarks

Sample

1

merchantAgreementId

The external agreement id from the merchant.

string

32

M

e8qdwl9casxor13

2

merchantUserId

The user id in merchant system.

string

64

O

userId001

3

validPeriod

The current agreement signing validation period, calculated from the sign request time.
This parameter is composed by integer number and time period unit. Time period unit supported:
d: days
m: months

string

8

O

15m

Request Sample

copy
{
  "request":
  {
    "head":
    {
      "version":"2.0.0",
      "function":"alipay.intl.oauth.auth.prepareForRedirect",
      "clientId":"4Q5XPV2N361Y0600",
      "reqTime":"2001-07-04T12:08:56+05:30",
      "reqMsgId":"1234567asdfasdf1123fda",
      "reserve":"{}"
    },
    "body":
    {
      "authMerchantId":"2160400000002012",
      "authSite":"ALIPAY_HK",
      "scopes":
      [
        "AUTH_AGREEMENTPAY"
      ],
      "terminalType":"WEB",
      "state":"4657DDUER323DK",
      "merchantRedirectUrl":"https://www.alipay.com/",
      "agreementPayAuthInfo":{
        "merchantAgreementId":"e8qdwl9casxor13",
        "merchantUserId":"userId001"
      },
      "extendInfo":"{\"agreementMark\":\"137352934538\"}"
    }
  },
  "signature": "jo4HAHQqjOomsCYtgqk7uinBmNqfOPuaM54soS2bWYfdZh/gZVF4I8VDVJBTRMuZ0RTAhloQv4eR90itWgbGY+4zGB3AZp795/wKy4VUY4atpeW7NiAn4drMk7lct/bAHU33lzfi93da4lkvKr96CBgrSgIk8pDW0VmDzXYIDXFQpNadWCqGSyHkoBnMNaNQ2Br0ONZmSR21cHYvWPzSEgR9H9+lVu2xoEQSXqPUkImMkMKcYtZMADyFXN9fL5j42saj0N17jel8wjMlDBh43jEgXga+opaYOS0TLniIpSHsHLYB32KPayADZeYtPRs2rWjJVwr+I0CdZyURIp9yuQ=="
}

Response Parameter

Header

No

Name

Description

Type

Length

Required

Remarks

Sample

1

version

API version

string

8

Y

As per the respective API reference

2.0.0

2

function

API interface

string

128

Y

According to specifications defined by each business domain

alipay.intl.function

3

clientId

Client ID

string

32

Y

Provided by AlipayHK, used to identify partner and application system

4Q5XPV2N361Y0600

4

respTime

Response time

datetime

/

Y

DateTime with timezone, which follows the ISO-8601 standard.
Refer to: RFC 3339 Section 5.6

2001-07-04T12:08:56+05:30

5

reqMsgId

Request message ID

string

64

Y

Each request will be assigned with a unique id (uuid).

1234567asdfasdf1123fda

6

reserve

Reserved for future implementation

string

256

O

Key/Value

{}

Body

ResultInfo

No

Name

Description

Type

Length

Required

Remarks

Sample

1

resultStatus

Result status

string

2

Y

S

2

resultCodeId

Result code id

string

8

Y

00000000

3

resultCode

Result code

string

64

Y

SUCCESS

4

resultMsg

Result message

string

256

O

Success

Response sample

copy
{
  "response": {
    "body": {
      "authSiteUrl": "http://unitradeprod-platform.dl.alipaydev.com/p/h5_pre/hk-gka-sign/www/index.html#/sign?merchantRedirectUrl=https%3A%2F%2Fsbs-mobops.sandbox-payment.com%2Fdebug%2Ftc%2Fatd_result.html&merchantProductCode=MC400401000000000024&productCode=UR400401000000000025&eventCode=40130004&sceneCode=SIGN_AGREEMENT&externalAgreementNo=d60f45a9b5b74ba184013de1d21dc85a&scopes=AUTH_AGREEMENTPAY&authSite=ALIPAY_HK&state=5fc9dfee-d392-45bd-b087-c1217cec6d3e&isvClientId=&bizId=1212be49b1b8466233801e9fea88ebf0",
      "resultInfo": {
        "resultCode": "SUCCESS",
        "resultCodeId": "00000000",
        "resultMsg": "Success",
        "resultStatus": "S"
      }
    },
    "head": {
      "clientId": "4Q5XSH6SSG02T006",
      "function": "alipay.intl.oauth.auth.prepareForRedirect",
      "reqMsgId": "b3645cc2-fe57-431a-a7ab-e705cbd1808c",
      "respTime": "2019-01-30T00:07:38-08:00",
      "version": "2.0.0"
    }
  },
  "signature": "lDc+s1dbVdAhBnEzZ44uZthx82fFXFJl49qHqg+qucBeIxdWxgvVJPCnmPAqOEi7lCELPM66dGWQvPfwxwywaU4DpV3muzymUsd8cneKJe9YGVKdt3yEt3pxfuJbGhT83ybpq/GET0LlWvHY7VZY6XYv3QrSs/S1UhBiJqW0bCUrTof6G6QSFg7m4HUUN8n0g1wL/xvnNSdCDoUakHrdcMdKcPkxRZDTRIs7UVVo6oWhKITZXb3xVJtsoKE9GfpG4lnKV8OxZieNrTZ1Xy0a/cpeJKQBKNp1r4s9osn0u7fpryOtl9mMSMC4QtpQ/uBnODGe2gpaxaS4OtKIs68Z7w=="
}

Business Error code

Functional Logic Result Code

No

ResultCodeId

ResultCode

ResultStatus

Remarks

1

00000013

NO_INTERFACE_DEF

F

API is not defined

2

00000901

UNKNOWN_EXCEPTION

U

Unknown exception

3

00000004

PARAM_ILLEGAL

F

Illegal parameters

4

00000007

INVALID_SIGNATURE

F

Signature is invalid