Associate external billing account

An existing, authenticated user associates their service billing account to their User ID (or “user profile” within your client application).

Initial Request

Your client calls the Process Start API to initialize the Process:

**POST https://\{your.url\}/process/start/accountAssociation.AssociateAccount.v1.0**
<no body>

Response: prompt for account identifier

Storefront Gateway responds with a request for the a mobile number to identify the external accoun:

**RESPONSE - body**
{
    "processId": "ec90ed2c-eca9-42de-9fbc-a81506c5d1e8",
    "processName": "accountAssociation.AssociateAccount.v2.0",
    "stepName": "IdentifierPrompt",
    "lastStep": false,
    "parameters": {
       "identifier": "string"
    }
}

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`stepName`	Name of the specific step that the Process is currently on.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`parameters`	Object that specifies the info this Process requires to continue its task.
`identifier`	Item that uniquely identifies the external account. Currently, this Process only accepts a mobile number. Support for email address and external account number are roadmapped for a near-future release.

Next Request: account identifier

The user provides their mobile number, and the client passes that to Storefront Gateway in a Process Step API request:

**PUT https://\{your.url\}/process/step**
{
    "processId": "ec90ed2c-eca9-42de-9fbc-a81506c5d1e8",
    "parameters": {
          "identifier": 5272096291,
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Object that contains the data that was requested in the previous Process response.
`accountKeys`	Object that contains the mobile number to identify the account in the BSS/OSS.

Response: issue OTP, return PKAT

Storefront Gateway queries the external account system with the user-supplied identifier. If the external system returns an account, Storefront Gateway then generates an action token and delivers it to the mobile number for ownership verification. This Process returns a PKAT in its final response, and then ends:

**RESPONSE - body**
{
    "processId": "ec90ed2c-eca9-42de-9fbc-a81506c5d1e8",
    "processName": "accountAssociation.AssociateAccount.v2.0",
    "lastStep": true,
    "output": {
       "pkat": "fe738030-e997-43e7-baad-fe7a386d91fd"    
    }
}

Note: Any Process step that sends a Storefront Gateway action token also returns a corresponding Proof Key for Action Tokens (PKATs)(Proof Key for Action token) to the client application. In order to enable OTP verification on the UI, the client must retain the PKAT returned by the final Process step. The Proof Key for Action Tokens (PKATs), along with the user-supplied OTP, is required for the GET /session/token?customToken={OTP}&pkat={pkat} API to invoke the Complete Account Association Process.

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`output`	Object that contains data that the client can consume, retain, and use for additional operations.
`pkat`	Unique Proof Key for Action Token that corresponds to an existing action token. See Action Tokens for more details.The client will need to supply this PKAT, along with the user-supplied OTP, in the next request in order to complete the account association.

Final Request

The user retrieves the OTP from their SMS, and supplies it to the client application. The client then calls the Session Token API, and supplies both the OTP and PKAT in the request URL:

**REQUEST - GET /session/token?customToken=123456&amp;pkat=fe738030-e997-43e7-baad-fe7a386d91fd**

<no body>

If both the OTP and PKAT are valid, this API invokes the Complete Account Association Process.

Response: Process complete

The Process performs creates the Storefront Gateway Account entity (and any Storefront Gateway Subscription and Storefront Gateway Feature entities, based on the integration and mapping between Storefront Gateway and the external system), and associates it to the user’s profile (i.e., to their corresponding User entity). Additionally, Storefront Gateway will associate the Account/Subscriptions/Features hierarchy to a Storefront Gateway Group. The following conditions apply:

If the user already has a Group (of which they are the Primary): Storefront Gateway associates the A/S/F hierarchy to the Group.
If the user does not yet have any Group: Storefront Gateway automatically creates a Group, assigns this user as the Group Primary, and associates the A/S/F hierarchy to the Group.

The Process then returns a 200 HTTPS status, and ends:

**RESPONSE - body**
{
    "processId": "c0fe9d0e-ad72-4663-becd-abee28ad33d3",
    "processName": "accountAssociation.AssociateAccount.v2.0",
    "lastStep": true
}

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
Parent topic:Associate Billing Account to User Process

Home

Introduction

For Merchants

For Resellers

Partner Ecosystem Management

Commerce Engine

Storefront Experience

APIs

Initial Request

Response: prompt for account identifier

Next Request: account identifier

Response: issue OTP, return PKAT

Final Request

Response: Process complete

​Initial Request

​Response: prompt for account identifier

​Next Request: account identifier

​Response: issue OTP, return PKAT

​Final Request

​Response: Process complete

Initial Request

Response: prompt for account identifier

Next Request: account identifier

Response: issue OTP, return PKAT

Final Request

Response: Process complete