ACCOUNT-ON-FILE (AOF)

Using PayWay's Account on File (AoF) service, ABA account holder can authorize merchant to store their ABA account token for future payment without entering the Mobile PIN again.

Merchant will only receive unique token for the linked ABA account and never see Account details while the real account details are securely stored on PayWay payment gateway.

The token can be used to initiate a payment during customer checkout, or the transactions can be initiated by merchants for scheduled and recurring payments depending of business need.

LINK ACCOUNT API

Use this API to request a QR on Web Platform or Deeplink on Mobile app to initiate linking ABA Account.

There are 2 ways how merchant can save payer's ABA account details in own system:

  • If payer processing payment through merchant's website on PC then merchant should display QR code for scanning with ABA Mobile app. During scanning QR with ABA Mobile app payer agrees to save its account on merchant side. Only ABA Mobile app can be used to scanning this QR code.
  • If payer processing payment through merchant's website or application on mobile device with pre-installed ABA Mobile app merchant should display button with deep link. Pressing (tap) on the button with link will launch ABA Mobile app where payer can select account that want to save on merchant application. ABA Mobile should be pre-installed on payer's device otherwise it will be redirected to App store or Play store.

API ENDPOINTS

Testing url:

https://checkout-sandbox.payway.com.kh/api/aof/request-qr

Production url:

https://checkout.payway.com.kh/api/aof/request-qr

  • Method: POST

REQUEST PARAMETER DESCRIPTION

# Field name Data type Remark Example
1 req_time

mandatory

 Timestamp [UTC] Format YYYYmmddHis 20210123234559
2 merchant_id

mandatory

 String [20] Mobile or Application ID onlinesshop24
3 return_param

mandatory

 String Will be included no pushback notification
4 return_url Text base 64 encode url; for override push back to Merchant “e5596529ddad43802fd1211d2503cd594a71e360381b8f15d6fbfa”
5 hash

mandatory

 Text Base64 encode of hash hmac sha512 encryption merchant_id + req_time with public_key. 
  • 
        $hash = base64_encode(hash_hmac('sha512', $merchant_id . $req_time, $public_key, true));
“waNDRBqpuvXM3BACX+X1Sxtg4U+Q/5dlI5C/VT+RuVUeflZ4GBpZLA7uSmByHLc56hl0H1zrT3+cOwJQn/eHYw==”

EXAMPLE REQUEST

  • 
        
	{   
	    "req_time": "20210723080525",
	    "merchant_id": "ec1000002",
	    "return_param": null,
	    "return_url": “e5596529ddad43802fd1211d2503cd594a71e360381b8f15d6fbfa”,
	    "hash": "waNDRBqpuvXM3BACX+X1Sxtg4U+Q/5dlI5C/VT+RuVUeflZ4GBpZLA7uSmByHLc56hl0H1zrT3+cOwJQn/eHYw=="
	}

EXAMPLE RESPONSE

  • 
        
	 {  
	 	"status": {
          "code": "00",
         "message": "QR generated successfully"     
	 	},
	    "deeplink": “abamobilebank://ababank.com?type=account_on_file&qrcode=ABAAOF%2BhEGxkym0GCTuGTSatzgFsexgxkuw%
	    "qr_string":"ABAAOF+hEGxkym0GCTuGTSatzgFsesgxkuw+8P0J3qJEbdUOWAMN0PdBi2Q/+xEVex6SbF19enqLB2xU46jTzVY1h3M9b8kJA==",
	    "qr_image": "https://payway-staging.ababank.com/assets/abaqr/abaqr-8f89f23955e7e68c5616270 27526ftvKQv8JML.png",
	    "expire_in": 1627113926
	 }

Note:

  • For Web implementation the ‘qr_image’ is to be rendered on the webpage so customer can Scan and Authorize linking of account.
  • For Mobile app integration ‘deeplink’ is to be used for calling ABA mobile so customer can enter the pin to Authorize the linking of account.
# Field name Data type Remark Example
1 Code String

Possible Response status

  • 00 Generate QR successfully
  • 04 Parameter Validation Required
2 Message String
3 deeplink String abamobilebank://ababank.com?type=account_on_file&qrcode=ABAAOF%2BhEGxkym0GCTuGTSatzgFsesgxkuw%%2FB4OzkNFrPlVDZTF68PNPJ1lM9b8kJA%3D%3D
4 qr_string String ABAAOF+hEGxkym0GCTuGTSatzgFsesgxkuw+8P0J3qJEbdUOWAMN0PdBi2Q/+xEVex6SbF19enqLB2xU46jTzVeWUNLRXJ/GG+4OzkNFrPlVDZTF68PNPJ1lM9b8kJA==
5 qr_image String https://payway-staging.ababank.com/assets/abaqr/abaqr-8f89f2395ad495aba3a15e70a6e68c56162702752.png
6 expire_in String 1627113926

The response contains deeplink, qr_string, qr_image and expiration time (as timestamp). Parameter "qr_string" can be converted as QR for desktop browsers so the customer can scan the it with his ABA Mobile and Enter pin ABA account in merchant's online store.

Parameter "deeplink" must be represented as HTTP link in merchant mobile application or merchant web site on mobile device. It allows customers clicking on it to automatically launch ABA Mobile.

See the sample code under 1.2 Deeplink for Native app integration for how to open ABA Mobile using the deeplink.

LINKED ACCOUNT PUSHBACK NOTIFICATION

After ABA account holder authorize linking their account by scanning the QR or with Deeplink, PayWay will pushback a unique Account Token with non-sensitive payer details to the Callback URL provided by Merchant. Merchant must store this token for the future purchase request.

EXAMPLE RSPONSE

  • 
        {
          "tran_id": "aof-370732ef43",
          "status": 0,
          "return_params":
            {
            "ctid":"37195a893ed5304ea...",
            "payment_status":"",
            "card_status":
              {
              "status":"00",
              "pwt":"371932f4102dacb606a8ca1e....",
              "mask_account":"*****0123",
              "expired_in":5184000
              },
          "return_param":"5644"
            }
          }

RESPONSE PARAMETER DESCRIPTION

# Field name Data type Remark Example
1 status string aof-370732ef43
2 tran_id String 0
3 return_params String
4 ctid String 37195a893ed5304ea
5 payment_status String
6 card_status String
7 status String 00
8 pwt String 371932f4102dacb606a8ca1e371932f41a8ca1e
9 mask_account String *****0123
10 expired_in String 5184000
11 return_param String 5644

REMOVE ACCOUNT API

Use this APIs to allow customer to be able to delete the linked account.

API ENDPOINTS

TESTING URL:

https://checkout-sandbox.payway.com.kh/api/aof/merchant-remove-account

PRODUCTION URL:

https://checkout.payway.com.kh/api/aof/merchant-remove-account

  • Method: POST
# Field name Data type Remark Example
1 req_time

mandatory

 Timestamp [UTC] Format YYYYmmddHis 20210123234559
2 merchant_id

mandatory

 String [20] Mobile or Application ID onlinesshop24
3 ctid

mandatory

 String Consumer token ID
4 pwt

mandatory

 String PayWay token
5 hash

mandatory

 text Base64 encode of hash hmac sha512 encryption merchant_id + req_time + ctid + pwt with public_key. 
  • 
        $hash = base64_encode(hash_hmac('sha512', $merchant_id . $ctid . $pwt, $public_key, true));

EXAMPLE REQUEST

  • 
        {
	      "ctid": "239acf04eace99ea15...",
	      "merchant_id": "ec000002",
	      "pwt": "23932588e6e1a330fedb1c135ac8df6ba1b....",
	      "req_time": "20200211101409",
	      "hash": "NWJkOTdhNGQ0NDY1YjBlODRjOTViMjVjZWIxZjY0NzUyNjRiMjhlYWQ1MmNlN2ViMTc..."
	    }

EXAMPLE RESPONSE

  • 
        {
          "status": {
              "code": "00",
      	      "message": "Success"
            }
      	}

RESPONSE PARAMETER DESCRIPTION

# Field name Data type Remark Example
1 code String Possible Statuses
  • 00 QR is valid
  • 01 Invalid api-key
  • 04 Parameter Validation Required
2 message String [20]

RENEW EXPIRED ACCOUNT API

Validity of the Linked account token is only for 60 Days. Merchant must renew the token to continue using AoF on your customer profile.

Note the account token can be renewed before it expires.

API ENDPOINTS

Testing url:

https://checkout-sandbox.payway.com.kh/api/aof/renew-expired-account

Production url:

https://checkout.payway.com.kh/api/aof/renew-expired-account

  • Method: POST

REQUEST PARAMETER DESCRIPTION

# Field name Data type Remark Example
1 req_time

mandatory

 Timestamp [UTC] Format YYYYmmddHis 20210123234559
2 merchant_id

mandatory

 String [20] Mobile or Application ID onlinesshop24
3 ctid

mandatory

 String Consumer token ID
4 pwt String PayWay token
5 hash

mandatory

Encrypt with: (###conString###)

Encryption method: ###encrypt### 		Text
  • hash: (merchant_id + ctid + pwt + req_time)
  • Encrypt with: "CALL_C_sha512( 'CURR_FIELD', 'fb62988kjad260f6668');"

EXAMPLE REQUEST

  • 
        {
          "req_time": "20210315030017",
          "merchant_id": "ec000002",
          "ctid": "3757acf04eace99ea1590857c7066acf260e",
          "pwt": "375732588e6e1a330fedb1c135ac8df6ba1b671278cfef7d73c9dfac86883115bdbec4",
          "hash": "XQhWgSbviuo+y9rOkRKfSGORCDuMyLDfTV0n6DwDz8r8wsdRA5hWbNf+dXDzqt1a3cmXnRpClSw9YSwQ0+wvsg=="
        }

EXAMPLE RESPONSE

  • 
        {
          "status": {
              "code": "00",
      	      "message": "Success"
            }
      	}

RESPONSE PARAMETER DESCRIPTION

# Field name Data type Remark Example
1 code String Possible Statuses
  • 00 Success
  • 11 other - server-side error
2 message String

PURCHASE WITH LINKED ACCOUNT

Creating a transaction with Account on File is similar to creating a purchase transaction using Create Transaction - Purchase API, the difference is while you submit a purchase request you must include the parameters 'ctid' , 'pwt' along with other mandatory parameters.

the transaction will be auto approved and immediately charge customer without having them to enter the pin.

Use Purchase API with parameters ‘ctid’, 'pwt', that you received while linking ABA account, upon successful payment PayWay will pushback payment status with the Transaction id.

API ENDPOINTS

TESTING URL:

https://checkout-sandbox.payway.com.kh/api/payment-gateway/v1/payments/purchase

PRODUCTION URL:

https://checkout.payway.com.kh/api/payment-gateway/v1/payments/purchase

  • Method: POST

EXAMPLE REQUEST

  • 
        {
              "req_time": "20200722113241",
              "tran_id": "scl-00011",
              "ctid": "234acf04eace99ea15...",
              "pwt": "23432588e6e1a330fedb1c135ac8df6ba1b...",
              "firstname": "chhengleap",
              "lastname": "soem",
              "email": "[email protected]",
              "phone": "0969890686",
              "amount": "0.50",
              "items": "W3sibmFtZSI6InRlc3QiLCJxdWFudGl0eSI6IjEiLCJwcmljZSI6IjEuMDAifV0=",
              "hash": "JTRVo/P16biznpoCQ3LbPLB2nLRMayuYiSjk4L42y10nKx2hF/6CVsa81NlqXSuw7og3vuHd3Hz3rKc6BLud2A=="
          }

PAYMENT SUCCESS PUSHBACK NOTIFICATION

Upon successful payment with the saved token PayWay will pushback the payment status with the Transaction id. 

  • 
        {
          "tran_id":"1632300046",
          "apv":"000011",
          "status":0
        }

CHECKOUT ERROR CODE

in case of having any issue while using the API, the table below could help you to quickly understand what went wrong.

# Description
1 00 Success
2 01 Invalid Header Key
3 02 Wrong Hash
4 03 Token Expired
5 04 Parameter Validation Required
6 05 Parameter Invalid Format
7 06 The Request is Expired
8 07 Invalid Data
9 08 Login Fail
10 09 Fail to connect to PwPwd system
11 10 Invalid hash token
12 11 Maximum number of requests is attempts has been exceeded
13 12 Invalid authentication info
14 13 Validation phone number is already used!
15 14 Invalid sort type [asc, desc]
16 15 You have no permission to access this feature
17 16 Request Timeout
18 17 Restrict User
19 18 Invalid ABA Account Number
20 21 Already registered, go to login or reset password if you forgot.
21 22 This account already registered on another app, please contact support for detail.
22 403 Forbidden