Initiate Payment

Request AOC Token for Charging

To initiate a charging via AOC Gateway, Service Provider will need to request for AOC Token from the AOC Gateway.

  1. Service Provider will request for AOC Token for each individual charging request as AOC Token is unique for each transaction.

  2. Once Service Provider gets the unique AOC Token, they will redirect the user to AOC Page by passing over the AOC Token.

Request

HTTP Method

POST

POST <AOC_SERVER>/api/getAOCToken
HTTP/1.1
Content type: application/x-www-form-urlencoded


{
    "apiKey":"Ofa3M7zS2c3",
  "username":"test",
  "spTransID":"201903192030-test1",
  "description":"Testing123456789",
  "currency":"MYR",
  "amount":"0.01",
  "onBehalfOf":"TestSP",
  "channel":"WEB",
  "operator":"operator1",
  "taxAmount":"0",
  "callbackURL":"https%3A%2F%2Fwww.test.com",
  "isSubscription":"True",
  "contactInfo":"6019123456789",
  "purchaseCategoryCode":"Game",
  "referenceCode":"Game",
  "subscriptionName":"testing",
  "subscriptionID":"WeeklyGame1",
  "subscriptionDuration":"8",
  "unSubURL":"https%3A%2F%2Fwww.google.com%2F"
}

Request Parameter

Parameter Name

Description

Usage

apiKey

This will be API Key to access AOC. Will be provided by APIGATE.

(STRING) Mandatory

username

This will be the username provided to the Service Provider by APIGATE.

(STRING) Mandatory

spTransID

This is a unique transaction id per API call event generated by Service Provider. It is your reference for troubleshooting purposes.

(STRING) Mandatory

description

This is the text to appear on the user's bill to allow them to easily identify what they have bought

(STRING) Mandatory

currency

This is the 3 figure code as per ISO 4217

(STRING) Mandatory

amount

This is the actual amount being charged. It needs to be two digit decimal such as 3.00, 6.50 and etc.

(DECIMAL) Mandatory

onBehalfOf

The actual Payee Company Name.

(STRING) Mandatory

purchaseCategoryCode

A purchase category code provided by APIGATE.

(STRING) Mandatory

refundPurchaseCategoryCode

This is the purchaseCategoryCode for refund transaction. This field is optional, if it’s not passed over, the default value during onboarding will be used during Refund.
This value will be provided by APIGATE if applicable.

(STRING) OPTIONAL

referenceCode

Same as purchase category code. This id will be use for any future reconciliation purposes

(STRING) Optional

channel

Indicates the source of user interaction.

(STRING) Mandatory

operator

The operator code provided by APIGATE.

(STRING) Mandatory

taxAmount

The tax already charged by the merchant.

(DECIMAL) Mandatory

callbackURL

The URL to which Service Provider would like AOC Gateway to redirect users once the charging transaction is completed. AOC will pass over the aocTransID to this URL.

(URL STRING) Mandatory

contactInfo

This is the contact information (contact number or email) that will be included in the Success Charge SMS, Renewal SMS and Unsubscribe Success SMS.

(STRING) Mandatory

contentURL

This is the content page URL that will be included in the Success Charge SMS and Renewal SMS. Just leave it empty if not required.

(URL STRING) Optional

isSubscription

This is a boolean flag (true/false) to define if the transaction is a subscription basis or on demand. If it's a subscription basis, the flag needs to be set to true.

(BOOLEAN) Mandatory

subscriptionID

This is a unique subscription id for each different subscription package/services. This field is mandatory if isSubscription is true.

(STRING) Optional

subscriptionName

This is the subscription name for the subscription package/services. This field is mandatory if isSubscription is true.

(STRING) Optional

subscriptionDuration

This is subscription duration for the subscription package/services. (in day) This field is mandatory if isSubscription is true.

(INT) Optional

unSubURL

This is the unsubscribe URL that will be included in the Renewal SMS.
This field is mandatory if isSubscription is true.

(STRING) Optional

isWallet

This is a boolean flag (true/false) to define if the transaction is using e-Wallet. If it’s e-Wallet transaction, the flag need to be set to true. Default will set to false.
[IMPORTANT]: e-Wallet transaction doesn’t support subscription services.

(BOOLEAN) Optional

isWebDeepLink

This is a boolean flag (true/false) to define if the handling of Mobile Wallet App Deep Link is handled by AOC Page or not. If the flag is set to true, AOC Page will try to open the Mobile Wallet App Deep Link (if available). If the flag is set to false, then the AOC page will redirect users to the Web payment page. If the flag is set to false, AOC will return paymentDeepLink and Service Provider can try to open the deep link via their Mobile App.

(BOOLEAN) Optional

callbackAppDeepLink

If a Service Provider has implemented a deep link on their own Mobile App, they can pass the deep link here so Mobile Wallet App will callback to this deep link once payment is completed.

(STRING) Optional

msisdn

This parameter is required for;

  1. Subscription Service via Wallet Payment. (This is the MSISDN of the end-user that has registered with Wallet Provider that is required for Subscription Service. Please advise the APIGATE Team on which Wallet Provider requires this parameter.)
  2. IOD/Subscription for Direct Charging enabled Service Provider.

(STRING) Optional

email

This is the email of the end-user that has registered with Wallet Provider that is required for Subscription Service. Please advise APIGATE Team on which Wallet

(STRING) Optional

isMobileAppAPI

This is a boolean flag (true/false) to define if the transaction is performed via Mobile API. Default value is false. If the flag is true, AOC will send a TAC to user MSISDN via SMS. This feature is only available for Service Providers that have been provisioned for Mobile App API. [IMPORTANT]: Doesn’t support e-Wallet transaction.

(BOOLEAN) Optional

tacMSISDN

The MSISDN of the subscriber. The user’s MSISDN includes the country code, e.g. 60191234567. This field is mandatory if isMobileAppAPI is true.

(STRING) Optional

productId

This is an optional field for IOD transactions for certain Operators (such as Telkomsel). This ID needs to be configured in AOC during on-boarding. Please consult the onboarding team for more information.

(STRING) Optional

renewalCharge

This is the amount that will be charged for subscription renewal if the initial charge amount is different compared to renewal charge. It needs to be two-digit decimal such as 3.00, 6.50 and etc.

This field is optional and only applicable if the initial charge amount is different compared to renewal charge.

(STRING) Optional

requireOTP

This is only applicable for Direct Charge transactions. This is a boolean flag (true/false) to define if the transaction required OTP or not. Please check with the APIGATE team if your account is enable for this feature or not.

(STRING) Optional

Response

HTTP/1.1 200 OK 
Content-Type: application/json 
Date: Tue, 01 Nov 2016 12:00:00 GMT


{ "data" : 
{ 
    "aocToken":"SVpzSWk2SERiQjVlOFZLZFpBblVp", 
    "aocTransID":"12345678",
    "errorCode":"00", 
    "errorMessage":""
} 
}

Response Parameter

Parameter Name

Description

Usage

aocToken

This is a unique token generated by AOC Gateway to identify each AOC transaction. Service Providers need to pass this aocToken during the redirection to AOC Page.

Note: This response parameter will not be applicable for Direct Charging transaction.

(STRING)

aocTransID

This is the unique transaction id generated by AOC Gateway. This id will be used for any future reconciliation purposes. The same id will be passed back to the Service Provider’s callback URL once the transaction is completed.

(STRING)

entitledForFreeTrial

This is a flag to indicate if the user entitles for Subscription Free Trial. The flag doesn’t guarantee the user is able to get a Free trial as it still depends on a free trial quota when the user proceeds with charging. This flag will only be returned when isMobileAppAPI is true.

(STRING)

paymentDeepLink

This is the Mobile Wallet App deep link. This value will only be returned if the “isWebDeepLink” parameter is set to false and if the Mobile Wallet supports a deep link.

(STRING)

errorCode

Please check on the error code list.

(STRING)

errorMessage

Explanation of the error.

(STRING)

Multiple Wallet Payment Option

Additional Information about Multiple Wallet Payment Option

If a Service Provider has onboarding multiple wallet operators, multiple wallet operator code can be passed over in the operator field with comma-delimited. In this case, the user will be shown a payment option page with multiple wallets.

🚧

Note

This option is only available for wallet payment and not normal direct operator billing.