# Credentials on File ## 1. Introduction Credential on File (CoF) is an innovative solution that allows businesses to securely store customer payment details for **on-demand or automatic future payments**. **Customers save their ABA account or their credit/debit card once**, and they can make future payments without re-entering their details. #### Common Use Cases: - **Subscription Services** – Automatic recurring billing for weekly/monthly plans - **One-Click Purchase** – Faster checkout experience for returning customers - **Recurring Bills** - Utilities, insurance, loan payments processed automatically - **Usage-Based Billing** - Dynamic charging based on consumption metrics ## 2. How it works 1. The customer selects **"Link ABA Account”** on your platform. - Desktop users will see a QR code to scan with ABA Mobile. Mobile users are sent via deeplink to open ABA Mobile - The user confirms and authorises the account link in the app. - PayWay generates and sends a secure token to your platform. 2. You store the token securely for future payments. 3. When the customer wants to pay, they select their linked ABA account and process the payment. 4. PayWay processes the transaction and confirms the status. **Option #1: Link a Card** 1. Customer selects "Link credit/debit card" on your platform 2. They enter their card details and authorize the link 3. PayWay generates a secure token and sends it to your system 4. You store this token safely for future transactions 5. When ready to pay, customer simply selects their linked card 6. PayWay processes the payment and confirms the result **Option #2: Save Card During Checkout** 1. Customer proceeds through normal checkout and selects "Save My Card for Future Payments" 2. PayWay generates a secure token and sends it to your system 3. You store this token safely for future transactions 4. For subsequent purchases, customer selects their saved card to complete payment 5. PayWay processes the transaction and confirms the result ## 3. Set up your COF UI To integrate PayWay Credentials on File and allow your customers to add their ABA account or Credit/Debit card to your platform, you must have UI section where customers can: - Add or link their ABA account or credit/debit card - View all their saved payment methods - Remove any linked payment method when needed :::caution[] You **must** follow PayWay Credential on file guidelines to ensure proper customer card/account storage. To store ABA accounts or cards securely on your website To store ABA accounts or cards securely on your mobile apps ::: ## 4. Integration Steps To allow your customers to link their ABA account on your platform, use the [Link Account](https://developer.payway.com.kh/link-account-14530828e0.md) API. Here’s a sample of a successful API response: ```json { "status": { "code": "00", "message": "QR generated successfully" }, "deeplink": "abamobilebank://ababank.com?type=account_on_file&qrcode=ABAAOF...uGTSatzgFses", "qr_string": "ABAAOF+hEGxkym0GCTuGTSatzgF...Bi2Q/+xEVex6SbF19enqLB2xU46jTzVY", "qr_image": "https://payway-staging.ababank.com/assets/abaqr/aba8f8...0a6e68c5616", "expire_in": 1627113926 } ``` Display a QR code using `qr_string` or `qr_image` for customers to scan with ABA Mobile and authorise the account linking. Use the `deeplink` to launch ABA Mobile automatically, where customers can select which account to link to your platform. Here's a JavaScript code snippet to open it: ```js const data = {DATA RESPONSE FROM LINK ACCOUNT API} if (isAndroid) { window.location = `intent://ababank.com?type=account_on_file&qrcode=${encodeURIComponent( data.qr_string )}#Intent;scheme=abamobilebank;end;` } else { window.location = data.deeplink } ``` Use the `deeplink` to launch ABA Mobile automatically, where customers can select which account to link to your platform. Here is a sample Android code snippet to open it: ```js private fun openDeepLink(qrString: String) { try { val url = "${ABA_SCHEME}://${ABA_DOMAIN}?type=payway&qrcode=${qrString}" // value from "abapay_deeplink" val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url)) startActivity(intent) } catch (ex: Exception) { val intent = Intent(Intent.ACTION_VIEW).apply { intent.data = Uri.parse("market://details?id=com.paygo24.ibank") startActivity(intent) } } companion object { const val ABA_SCHEME = "abamobilebank" const val ABA_DOMAIN = "ababank.com" } ``` Use the `deeplink` to launch ABA Mobile automatically, where customers can select which account to link to your platform. Here is a sample iOS code snippet to open it: ```js let deeplink = response.deeplink let appStore = "https://apps.apple.com/us/app/aba-mobile-bank/id968860649" guard let deeplinkURL = URL(string: deeplink), let appStoreURL = URL(string: appStore) else { //Something went wrong, check url respond from API. return } UIApplication.shared.open(deeplinkURL, options: [:]) { success in if !success // Open app store UIApplication.shared.open(appStoreURL, options: [:]) } } ``` After user linked their ABA account, PayWay will call your `return_url` param and passing the following information. Your `return_url` must accept http method `POST` and content type `application/json`. ```json { "tran_id": "aof-rq-1741840838", "apv": "", "status": 0, "return_params": { "ctid": "6451397de98d966...e7f5db97738209", "payment_status": "", "card_status": { "status": "00", "pwt": "645139774AF0ED859615580A1...B992C374", "mask_account": "*****1481", "expired_in": 1747024840 }, "return_param": "{YOUR RETURN PARAMS DURING INITIATE LINK ACCOUNT}" } } ``` --- **tran_id** **`string`** Transaction id auto generate by payment gateway --- **apv** **`string`** Approval code. Since this is a linked account without a purchase, this field will always be empty --- **status** **`string`** The value is always `0`, which represents success. --- **return_params** **`object`** - **ctid** **`string`** Consumer Token Identification. This is a unique token automatically generated by the payment gateway to identify the consumer securely. - **payment_status** **`string`** Since this is a linked account without a purchase, this field will always be empty. - **card_status** **`object`** - **status** **`string`** The value is always `00`, which represents success. - **pwt** **`string`** PayWay token. his is a unique token automatically generated by the payment gateway to identify ABA Account. - **mask_account** **`string`** Masked ABA account. Only the last 4 digits are shown. - **expired_in** **`int`** The token expiration date, represented as a timestamp. - **return_param** **`string`** Your `return_param` contains the information you sent to the payment gateway during the link account initiation process. If you encounter issues with the pushback notification and do not receive the details, you can manually retrieve the linked account information using the [Get link account details](https://developer.payway.com.kh/get-linked-account-details-14530834e0.md) API. Once Card on File is enabled on your profile, an option will appear at checkout, allowing customers to save their card during the purchase. Additionally, we provide a separate API that enables customers to link their credit or debit card to your platform without requiring an initial purchase. To integrate this, use the [Link Card](https://developer.payway.com.kh/link-card-14530829e0.md) API. PayWay will respond with a saved card web page that you can render in an iFrame, allowing customers to securely enter their card details directly on the PayWay screen. After the user links their card, PayWay will call your `return_url` parameter and pass the following information. Your `return_url` must accept HTTP method `POST` and the content type `application/json`. ```json { "tran_id": "ZMRAbbOGRvtxncM", "status": 0, "return_params": { "tran_id": "ZMRAbbOGRvtxncM", "ctid": "6789826ae362d...91e75ba15d92c5373", "payment_status": "APPROVED", "card_status": { "status": 0, "pwt": "6789826D10512B3D5AD8A0...DAB948353E#UHJRB", "mask_pan": "**** **** **** 4031", "card_type": "Visa" }, "return_param": "{YOUR RETURN PARAMS DURING INITIATE LINK CARD}" } } ``` --- **tran_id** **`string`** Transaction ID is automatically generated by the payment gateway. --- **status** **`string`** The value is always `0`, which represents success. --- **return_params** **`object`** - **tran_id** **`string`** Transaction ID is automatically generated by the payment gateway. - **ctid** **`string`** Consumer Token Identification. This is a unique token automatically generated by the payment gateway to identify the consumer securely. - **payment_status** **`string`** When linking a card, the card must have a minimum balance of 0.01 USD. A 0.01 USD transaction will be temporarily processed and then immediately refunded. The value is always `APPROVED`, which represents success. - **card_status** **`object`** - **status** **`int`** The value is always `0`, which represents success. - **pwt** **`string`** PayWay token. This is a unique token automatically generated by the payment gateway to identify an ABA account. - **mask_pan** **`string`** Masked linked card PAN. Only the last 4 digits are displayed. - **card_type** **`string`** Type of the card. It can be `Visa`, `MC`, `JCB`, or `CUP`. - **return_param** **`string`** Your `return_param` contains the information you sent to the payment gateway during the link card initiation process. To perform purchase using the token, please follow the specification of [Purchase using token](https://developer.payway.com.kh/purchase-using-token-14530833e0.md) API