Alipay+ DocsAlipay+ Docs

Understand relationships between different IDs

Multiple IDs are involved in the interaction with Alipay+. Each ID identifies a party or an object. This document describes all IDs that are used and the relationships between IDs.

What are the involved IDs?

The following figure illustrates the IDs and relationships between IDs:

image

Figure 1. Involved IDs in Payment Switch Service

Note:

The relationship between authClientId and referenceMerchantId in this figure is for Auto Debit Payment.

The following table lists the basic information about the IDs:

ID name

Length

Type

Description

acquirerId

64

String

The unique ID that is assigned by Alipay+ to identify an Acquirer

pspId

64

String

The unique ID that is assigned by Alipay+ to identify a Mobile Payment Provider

clientId

64

String

The unique ID that is assigned by Alipay+ to identify a client during the integration with Alipay+

referenceMerchantId

32

String

The unique ID that is assigned by Acquirer to identify a merchant

referenceStoreId

32

String

The unique ID that is assigned by the merchant to identify a store

authClientId

64

String

The unique identifier for AuthClient. AuthClient is the authorization object to which the user grants resource access permission.

Values of acquirerId and pspId comply with the following format and pattern:

  • Format: A 16-character combination of letters and digits
  • Pattern: 16 characters
    • One letter or digit that corresponds to the version
    • Two digits that correspond to the Partner category
    • Five letters, five digits, or five-character combination of letters and digits that correspond to the Partner code
    • Two letters, two digits, or two-character combination of letters and digits that correspond to the primary branch code of the Partner
    • Four digits that correspond to the secondary branch code of the Partner
    • Two letters, two digits, or two-character combination of letters and digits that are reserved

What are the relationships between different IDs?

The following list describes the relationships between IDs:

  • When a Partner is a Mobile Payment Provider and at the same time is also an Acquirer, pspId and acquirerId of the Partner are the same.
  • One acquireId or one pspId corresponds to one clientId.
  • One clientId can be used to integrate with multiple APIs. For example, one clientId is used to integrate with several interfaces, such as the Payment interface, the Refund interface, and the Payment Notify interface.
  • One clientId corresponds to one unique pair of keys. However, when the keys are updated, one clientId has an original pair of keys and a new pair of keys within an agreed period. After the agreed period, the keys of the original version are expired.
  • One Acquirer might have multiple merchants, therefore one acquirerId might correspond to multiple referenceMerchantId. For example, two Japanese merchants (with two referenceMerchantId of M00xxxxx0001 and M00xxxxx0002) are connected with Alipay+ through the same Acquirer (with an acquirerId of 102xxxxxxxxxxxx0001).
  • AuthClient is the authorization object to which the user grants resource access permission. For Auto Debit Payment, AuthClient is the merchant. As illustrated in the figure, one merchant might have multiple AuthClients, therefore one referenceMerchantId might correspond to multiple authClientId. For example, one Japanese merchant (with a referenceMerchantId of M00xxxxx0001) has two apps (with two authClientId of 218xxxxxxxxx1234 and 218xxxxxxxxx1235). For offline payment scenarios, AuthClient might be Alipay+. For the specific description of authClientId in different payment scenarios, see the integration document of each payment solution.
  • One merchant might have multiple stores, therefore one referenceMerchantId might correspond to multiple referenceStoreId. For example, one Japanese merchant (with a referenceMerchantId of M00xxxxx0001) has two stores (with two referenceStoreId of S00xxxx0001 and S00xxxx0002).

When are the IDs assigned?

The following list describes when the IDs are assigned:

  • For Auto Debit Payment, authClientId is assigned when the merchant completes the onboarding process. For other scenarios, see the integration documentation for details.
  • pspId, acquirerId, clientId, and referenceMerchantId are assigned when the Partner completes the onboarding process. Among which, referenceMerchantId is assigned by the Acquirer to uniquely identify a merchant.