TNGD Mini Program Development PlatformTNGD Mini Program Development PlatformDOCS

/v1/authorizations/prepare

POST /v1/authorizations/prepare

The prepareAPI is used to prepare a contract at wallet.

Note: A contract which takes place at wallet.

1) merchant/partner initiates prepare request to wallet through Prepare Interface.

2) Wallet will handle different contract scenarios base on the parameters in request.

Currently, prepare API supports following scenarios:

  • Auto Debit: In this scenario, merchant/partner will call this prepare API to prepare contract, and wallet will return authorization URL to merchant/partner, and then redirect to this authorization page. So user can agree to authorize.

Message structure

Request

Property

Data type

Required

Description

authClientId

String

Yes

client Id issued by TNGD

Max. length: 128 characters.

partnerReqId

String

Yes

unique identifier of the prepare request provided by client

Max. length: 128 characters.

partnerId

String

Yes

partner Id, to be provided by TNGD as part of onboarding process

Max. length: 32 characters.

authClientDisplayName

String

Yes

Authorization page partner's display name

Max. length: 128 characters.

authRedirectUrl

String

Yes

Partner's redirection callback URL

Max. length: 1024 characters.

authLogoUrl

String

Yes

Partner's offical logo to display on the auth page

Max. length: 1024 characters.

scope

Array

Yes

List of scopes to be requested for authentication request. Available scope: AGREEMENT_PAY

Max. length: 255 characters.

authState

String

Yes

An arbitrary string value will be pass back to partner, useful for CSRF protection.

It suppose to be an unique and non-guessable value associated with each authentication request about to be initiated to avoid CSRF attacks

Max. length: 128 characters.

extendInfo

String

No

extended information

Max. length: 1024 characters.

envInfo

EnvInfo

No

EnvInfo

Response

Property

Data type

Required

Description

authId

String

Yes

authorization request unique identifier

authURL

String

Yes

Redirect URL for partners to redirect to TnG eWallet for user to complete the authorization flow

authClientId

String

Yes

client Id issued by TNGD

Result process logic

For different request results, different actions are to be performed. See the following list for details:

  • If the value of result.resultStatus is S , the authorization url application request is successful. The merchant can use the authorization url to sign contract.
  • If the value of result.resultStatus is F or U , AuthClient may guide user to try again.

Result

resultStatus

resultCode

resultMessage

S

SUCCESS

Success.

U

UNKNOWN_EXCEPTION

An API calling is failed, which is caused by unknown reasons.

U

REQUEST_TRAFFIC_EXCEED_LIMIT

The request traffic exceeds the limit.

F

PROCESS_FAIL

A general business failure occurred. Don't retry.

F

PARAM_ILLEGAL

Illegal parameters exist. For example, a non-numeric input, or an invalid date.

F

ACCESS_DENIED

The access is denied.

F

INVALID_API

The called API is invalid or not active.

F

INVALID_SCOPE

Requested scope is invalid

F

INVALID_CLIENT

Client verification failed

F

INVALID_REDIRECT_URL

Invalid format/pattern of redirect url

Sample

The authorization token application is used to exchange the access token based on the auth code after obtaining the auth code.

image

  1. Firstly the Mini Program bind account for user (Step 1).
  2. The merchant server calls /v1/authorizations/prepare interface to initiate binding flow (Step 2).
  3. E-wallet server returns auth url to the merchant server (Step 3).
  4. The merchant server has to pass through the auth url to the Mini Program (step 4).
  5. The Mini Program calls my.tngdSignContract interface to obtain the authorization code from e-wallet. (Step 5)
  6. E-wallet returns the authorization code to the Mini Program (Step 11)
  7. The Mini Program sends authorization code to the merchant server (Step 12)
  8. The merchant server calls /v1/authorizations/applyToken interface to obtain the access token from e-wallet server and e-wallet server returns the access token and customer ID to the merchant server (Step 13 and Step 15).

Request

copy
{
    "authClientId": "2018103116394800000000",
    "partnerReqId": "663A8FA9-D836-48EE-8AA1-1FF682989DC7",
    "partnerId": "217120000003677100000",
    "authClientDisplayName": "BEST WESTERN I-CITY (LOBBY)",
    "authRedirectUrl": "https://merchant.prepare.redirect.url",
    "authLogoUrl": "https://seeklogo.com/images/merchantlogo.png",
    "scope": [
        "AGREEMENT_PAY"
    ],
    "authState": "202107191152037654567891",
    "extendInfo": " {\"externalUserId\":\"XXXXXXXX\",\"externalUserMobile\":\"XXXXXXXX\"}",
    "envInfo": {
        "terminalType": "SYSTEM",
        "orderTerminalType": "MINI_APP"
    }
}

Response

copy
{
    "authClientId": "2018103116394800000000",
    "authId": "202208261112068001000655600000272",
    "authURL": "https://m-sd.tngdigital.com.my/s/oauth2/index.html#/authorise?authClientId=305XST2CSG0N4P05595&authSign=somesignature&authId=202208261112068001000655600000272",
    "result": {
        "resultCode": "SUCCESS",
        "resultMessage": "Success.",
        "resultStatus": "S"
    }
}