openapi: 3.0.3 info: title: EDC Payment Gateway - Freeze Balance version: 1.2.4 description: 'Freeze balance available on * **EDC APP / WEB Channel** (DeepLink, SDK, WebView) * **Bank Partner Channel** (IBanking, OTC ...) This API goes **both ways**: OONE implements the token, bill inquiry and freeze endpoints; the partner bank implements create transaction, settlement and verify transaction. Each page states who implements it.' servers: - url: http://freezebal.oone.bz:60447 description: 'OONE Staging (EDC Staging: provided later once VPN configured)' - url: https://{BANK_URL} description: Partner bank endpoint variables: BANK_URL: default: bank.example.com description: Bank API base URL paths: /v1/Security/Token: post: operationId: getToken summary: Get Token description: 'Use this endpoint to get token for access freeze balance api. (5.0 in overall diagram) Implemented by: OONE. Called by: Partner bank.' tags: - Authorization servers: - url: http://freezebal.oone.bz:60447 description: 'OONE Staging (EDC Staging: provided later once VPN configured)' requestBody: required: true content: application/json: schema: type: object properties: username: type: string description: provided by OONE password: type: string description: provided by OONE clientId: type: string description: provided by OONE secret: type: string description: provided by OONE refreshToken: type: string description: provided by OONE required: - username - password - clientId - secret example: username: sys_xxx@edc.com.kh password: xxxx clientId: freeze_api secret: xxxx refreshToken: '' responses: '200': description: Response (check `code` for the business result) content: application/json: schema: type: object properties: token: type: string description: Token for access freeze end-point refreshToken: type: string description: For request new token once current token expired tokenExpireTime: type: string format: date-time description: Expire time of token username: type: string example: token: eyJhbGciOiJSUzI1NiIsI**********************2HugC_gQ refreshToken: aff518cf926********a913cff5934a tokenExpireTime: '2022-04-08T07:32:50.1382803' username: sys_xxx@edc.com.kh security: [] /v1/Security/RefreshToken: post: operationId: getRefreshToken summary: Get Refresh Token description: 'Use this endpoint to get request new token whenever current token expired. (5.0 in overall diagram) Implemented by: OONE. Called by: Partner bank.' tags: - Authorization servers: - url: http://freezebal.oone.bz:60447 description: 'OONE Staging (EDC Staging: provided later once VPN configured)' requestBody: required: true content: application/json: schema: type: object properties: clientId: type: string description: provided by OONE secret: type: string description: provided by OONE refreshToken: type: string description: from response of get token required: - clientId - secret - refreshToken example: clientId: freeze_api secret: xxx refreshToken: aff518cf926********a913cff5934a responses: '200': description: Response (check `code` for the business result) content: application/json: schema: type: object properties: token: type: string description: Token for access freeze end-point refreshToken: type: string description: For request new token once current token expired tokenExpireTime: type: string format: date-time description: Expire time of token username: type: string example: token: eyJhbGciOiJSUzI1NiIsI**********************2MkslB_db refreshToken: werd78cf926********a913cff591sdx tokenExpireTime: '2022-04-08T10:32:50.1382803' username: sys_xxx@edc.com.kh security: [] /v1/Freeze/Bill: post: operationId: billInquiry summary: Bill Inquiry description: 'Use this endpoint to request bill information. (5.0 in overall diagram) Implemented by: OONE. Called by: Partner bank. Failed response codes: 101 Bill {X} not exists!; 102 Bill {X} was in {Y} status!; 103 Bill {X} was over due date!' tags: - Freeze servers: - url: http://freezebal.oone.bz:60447 description: 'OONE Staging (EDC Staging: provided later once VPN configured)' requestBody: required: true content: application/json: schema: type: string description: Transaction number (txn), sent as a raw JSON string example: F1008XX responses: '200': description: Response (check `code` for the business result) content: application/json: schema: type: object properties: txn: type: string description: Transaction number desc: type: string description: Bill description amount: type: number description: Bill amount which freezable currency: type: string description: Currency code (ISO 4217) phone: type: string description: Consumer phone number example: txn: F1008XX desc: វិក្កយបត្របង្កកប្រាក់កក់ថ្លៃបន្តចរន្ត amount: 84000 currency: KHR phone: 010 XXX XX8 security: - bearerAuth: [] /transaction/create: post: operationId: createTransaction summary: Create Transaction (Bank Partner) description: '(1.1 in overall diagram) Implemented by: Partner bank. Called by: EDC App / Web. Authorization: Bank consider any type of authorization.' tags: - Freeze servers: - url: https://{BANK_URL} description: Partner bank endpoint variables: BANK_URL: default: bank.example.com description: Bank API base URL requestBody: required: true content: application/json: schema: type: object properties: merchant_id: type: string description: Merchant ID at bank side transaction_id: type: string description: Transaction reference number from EDC transaction_amount: type: number description: Amount to freeze transaction_currency: type: string description: Currency code (ISO 4217) transaction_description: type: string description: Description bill_type: type: string description: freeze or utility return_url: type: string description: The URL that bank will redirect to after payment completed callback_url: type: string description: The URL that bank will send transaction details to EDC side to confirm the transaction (webhook) hash: type: string description: 'Hash calculation field (ensure the data integrity). Algorithm: MD5Hash ( merchant_id + transaction_id + transaction_amount + transaction_currency + bill_type + {HASH_SECRET_KEY} )' required: - merchant_id - transaction_id - transaction_amount - transaction_currency - bill_type - return_url - callback_url - hash example: merchant_id: EDC transaction_id: F1008XX transaction_amount: 84000 transaction_currency: KHR transaction_description: '' bill_type: freeze return_url: https://example.com/transaction/complete callback_url: https://example.com/transaction/callback hash: 4be8fc1f50834aacb5c46005501cda8b... responses: '200': description: Response (check `code` for the business result) content: application/json: schema: type: object properties: code: type: string description: Response code message: type: string description: Response message data: type: object properties: web_payment_url: type: string description: The URL to call web payment mobile_deep_link: type: string description: The deep link to call bank app description: Data Object example: code: '000' message: '' data: web_payment_url: https://bankdomain/payment/.... mobile_deep_link: bank://... security: [] /v1/Freeze: post: operationId: freeze summary: Freeze description: 'Once bank completed process freeze balance at bank side, bank need to invoke this endpoint to acknowledge bill freeze status to OONE. (5.0 in overall diagram) Implemented by: OONE. Called by: Partner bank. Failed response codes: 101 Bill {X} not exists!; 102 Bill {X} was in {Y} status!; 103 Bill {X} was over due date!' tags: - Freeze servers: - url: http://freezebal.oone.bz:60447 description: 'OONE Staging (EDC Staging: provided later once VPN configured)' requestBody: required: true content: application/json: schema: type: object properties: txn: type: string description: Transaction number refNo: type: string description: Reference number from bank side transDate: type: string format: date-time description: Transaction date effectiveDate: type: string format: date-time description: Expired freeze bill date -- e.g. X Bank has policy 30 days to block bill so that bill will automate unfreeze in that amount of days if no settle was invoke from OONE. required: - txn - refNo - transDate - effectiveDate example: txn: F1008XX refNo: XX011FT transDate: '2022-04-07T18:51:30.992Z' effectiveDate: '2022-05-07T18:51:30.992Z' responses: '200': description: Response (check `code` for the business result) content: application/json: schema: type: object properties: code: type: string description: Response code message: type: string description: Response message example: code: '00' message: Success security: - bearerAuth: [] /settle: post: operationId: settlement summary: Settlement (Bank Partner) description: 'Settlement (Bank Partner) Implemented by: Partner bank. Called by: OONE. Authorization: Bank consider any type of authorization.' tags: - Freeze servers: - url: https://{BANK_URL} description: Partner bank endpoint variables: BANK_URL: default: bank.example.com description: Bank API base URL requestBody: required: true content: application/json: schema: type: object properties: txn: type: string description: Transaction number refNo: type: string description: Ref number from bank amount: type: number description: Amount to settle currency: type: string description: Currency code (ISO 4217) required: - txn - refNo - amount - currency example: txn: F1008XX refNo: XX011FT amount: 84000 currency: KHR responses: '200': description: Response (check `code` for the business result) content: application/json: schema: type: object properties: code: type: string description: Response code message: type: string description: Response message data: type: object properties: txn: type: string description: Transaction number refNo: type: string description: Ref number after success settle desc: type: string description: Description description: Data Object example: code: '000' message: '' data: txn: F1008XX refNo: X10311 desc: '' security: [] /verify: post: operationId: verifyTransaction summary: Verify Transaction (Bank Partner) description: 'Verify Transaction is an API Endpoint that bank partner need to produce for OONE to request for checking transaction status. Implemented by: Partner bank. Called by: OONE. Authorization: Bank consider any type of authorization.' tags: - Freeze servers: - url: https://{BANK_URL} description: Partner bank endpoint variables: BANK_URL: default: bank.example.com description: Bank API base URL requestBody: required: true content: application/json: schema: type: object properties: txn: type: string description: Transaction number required: - txn example: txn: F1008XX responses: '200': description: Response (check `code` for the business result) content: application/json: schema: type: object properties: code: type: string description: Response code message: type: string description: Response message data: type: object properties: txn: type: string description: Transaction number status: type: string description: pending, frozen, settled currency: type: string description: Currency code (ISO 4217) transaction_amount: type: number transaction_date: type: string transaction_ref: type: string description: bank transaction ref desc: type: string description: Description description: Data Object example: code: '000' message: '' data: txn: F1008XX status: frozen currency: KHR transaction_amount: 60000 transaction_date: '2023-05-30T09:25:30' transaction_ref: X10311 desc: '' security: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: Token provided privately / from the token endpoint