openapi: 3.0.3
info:
  title: EDC Payment Gateway - Auto Direct Debit
  version: 2.1.3
  description: 'Auto Direct Debit is a web service which EDC Payment Gateway integrate to partnered banks to enable auto payment
    when consumers have new bills to pay.


    This API goes **both ways**: some endpoints are implemented by EDC Payment Gateway and called by the bank; others are
    implemented by the bank and called by EDC Payment Gateway. Each page states who implements it.'
servers:
- url: https://edc-sit-api.oone.bz/pg-directdebit-api
  description: EDC SIT (staging)
- url: https://{domain}
  description: Partner bank endpoint
  variables:
    domain:
      default: bank.example.com
      description: Bank API domain
paths:
  /directdebit/subscribe/request:
    post:
      operationId: subscriptionRequest
      summary: Subscription Request
      description: 'EDC App / Web request subscription to bank side.


        Implemented by: Partner bank. Called by: EDC App / Web.'
      tags:
      - Subscribe
      servers:
      - url: https://{domain}
        description: Partner bank endpoint
        variables:
          domain:
            default: bank.example.com
            description: Bank API domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchant_id:
                  type: string
                  description: Merchant ID at bank side
                merchant_secret:
                  type: string
                  description: Merchant secret key at bank side
                transaction_id:
                  type: string
                  description: Transaction reference number from EDC
                transaction_description:
                  type: string
                  description: Transaction description
                return_url:
                  type: string
                  description: The URL that bank will redirect to EDC side after subscription on bank page completed. We will
                    provide as web url when subscribe from web and deeplink when subscribe from mobile platform.
                details:
                  type: array
                  items:
                    type: object
                    properties:
                      company_code:
                        type: string
                        description: Company code
                      company_name:
                        type: string
                        description: Company name
                      consumer_code:
                        type: string
                        description: Consumer code
                      consumer_name:
                        type: string
                        description: Consumer name
                      consumer_name_latin:
                        type: string
                        description: Consumer name in Latin
                    required:
                    - company_code
                    - company_name
                    - consumer_code
                    - consumer_name
                  description: List of consumers
              required:
              - merchant_id
              - merchant_secret
              - transaction_id
              - return_url
              - details
            example:
              merchant_id: EDC
              merchant_secret: xxxxxxxxxxxxxxxx
              transaction_id: '174952172035635'
              transaction_description: ''
              details:
              - company_code: EDC-BTB
                company_name: អគ្គិសនីបាត់ដំបង
                consumer_code: '73562510'
                consumer_name: លោក ជា សំណាង
                consumer_name_latin: Mr. Chea Samnang
              - company_code: EDC
                company_name: អគ្គិសនីកម្ពុជា
                consumer_code: '93533310'
                consumer_name: លោក លីសីហា
                consumer_name_latin: Mr. Ly Seyha
      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 in English
                  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: []
  /subscribe/v2:
    post:
      operationId: subscriptionConfirm
      summary: Subscription Confirm
      description: 'This operation is to confirm the subscription at EDC side.


        Implemented by: EDC Payment Gateway. Called by: Partner bank.'
      tags:
      - Subscribe
      servers:
      - url: https://edc-sit-api.oone.bz/pg-directdebit-api
        description: EDC SIT (staging)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                biller_code:
                  type: string
                  description: Biller prefix code (Default is EDC)
                ref_no:
                  type: string
                  description: Full bank account number of the consumer
                subscribe_date:
                  type: string
                  description: Subscription date (ISO 8601)
                subscribe_ref:
                  type: string
                  description: Subscription reference number from EDC. Bank need to provide this field when subscribe from
                    EDC channel
                details:
                  type: array
                  items:
                    type: object
                    properties:
                      consumer_code:
                        type: string
                        description: Consumer code
                      subscribe_token:
                        type: string
                        description: 'Hash calculation field Base64(SHA-512(biller_code + consumer_code + ref_no + subscript_date[yyyyMMddHHmmss]
                          + bank_token)) Note: Bank need to store this value in their side.'
                    required:
                    - consumer_code
                    - subscribe_token
                  description: List of consumers and subscribe tokens
              required:
              - biller_code
              - ref_no
              - subscribe_date
              - details
            example:
              biller_code: EDC
              ref_no: 001937779
              subscribe_date: '2022-02-18 15:30:12'
              subscribe_ref: '1234567890'
              details:
              - consumer_code: '73562510'
                subscribe_token: '...Wk83giJmm3zQEqCoNUGXRUe+I5U7mSd0CCCGRa70aBw=='
              - consumer_code: '93533310'
                subscribe_token: '...tk90giJmm3zQEqCoNUGXEEE+Y5U7mSd0CCCGDb98eAc=='
      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 in English
                  message_kh:
                    type: string
                    description: Response message in Khmer
              example:
                code: '000'
                message: Direct Debit subscribed successfully.
                message_kh: សេវាកម្មទូទាត់ប្រាក់ដោយស្វ័យប្រវត្តិត្រូវបានភ្ជាប់ដោយជោគជ័យ។
      security:
      - bearerAuth: []
  /unsubscribe/v1:
    post:
      operationId: unsubscribe
      summary: Unsubscribe
      description: 'Unsubscribe


        Implemented by: EDC Payment Gateway and partnered banks. Called by: Partner bank / EDC Payment Gateway.'
      tags:
      - Auto Direct Debit
      servers:
      - url: https://edc-sit-api.oone.bz/pg-directdebit-api
        description: EDC SIT (staging)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subscribe_token:
                  type: string
                  description: Token from subscribe
                unsubscribe_date:
                  type: string
                  description: Unsubscribe date
              required:
              - subscribe_token
              - unsubscribe_date
            example:
              subscribe_token: '...Wk83giJmm3zQEqCoNUGXRUe+I5U7mSd0CCCGRa70aBw=='
              unsubscribe_date: '2022-02-20 15:30:12'
      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 in English
                  message_kh:
                    type: string
                    description: Response message in Khmer
              example:
                code: '000'
                message: Direct Debit unsubscribed successfully.
                message_kh: សេវាកម្មទូទាត់ប្រាក់ដោយស្វ័យប្រវត្តិត្រូវបានផ្តាច់ដោយជោគជ័យ។
      security:
      - bearerAuth: []
  /validate/consumer/v1:
    post:
      operationId: validateConsumer
      summary: Validate Consumer
      description: 'Partnered bank request to this operation to validate the consumer code and get back consumer information.


        Implemented by: EDC Payment Gateway. Called by: Partner bank.'
      tags:
      - Auto Direct Debit
      servers:
      - url: https://edc-sit-api.oone.bz/pg-directdebit-api
        description: EDC SIT (staging)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                biller_code:
                  type: string
                  description: Biller prefix code (Default is EDC)
                consumer_code:
                  type: string
                  description: Consumer code
              required:
              - biller_code
              - consumer_code
            example:
              biller_code: EDC
              consumer_code: '73562510'
      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 in English
                  message_kh:
                    type: string
                    description: Response message in Khmer
                  data:
                    type: object
                    properties:
                      company_code:
                        type: string
                        description: Company code
                      company_name:
                        type: string
                        description: Company name
                      consumer_code:
                        type: string
                        description: Consumer code
                      consumer_name:
                        type: string
                        description: Consumer name
                      consumer_name_latin:
                        type: string
                        description: Consumer name in Latin
                    description: Data object
              example:
                code: '000'
                message: ''
                message_kh: ''
                data:
                  company_code: EDC-BTB
                  company_name: អគ្គិសនីបាត់ដំបង
                  consumer_code: '73562510'
                  consumer_name: លោក ជា សំណាង
                  consumer_name_latin: Mr. Chea Samnang
      security:
      - bearerAuth: []
  /validate/token/v1:
    post:
      operationId: validateSubscribeToken
      summary: Validate Subscribe Token
      description: 'Partnered bank able to generate subscribe token with this operation.


        Implemented by: EDC Payment Gateway. Called by: Partner bank.'
      tags:
      - Auto Direct Debit
      servers:
      - url: https://edc-sit-api.oone.bz/pg-directdebit-api
        description: EDC SIT (staging)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                biller_code:
                  type: string
                  description: Biller prefix code (Default is EDC)
                consumer_code:
                  type: string
                  description: Consumer code
                ref_no:
                  type: string
                  description: Full bank account number of the consumer
                subscribe_date:
                  type: string
                  description: Subscription date (ISO 8601)
              required:
              - biller_code
              - consumer_code
              - ref_no
              - subscribe_date
            example:
              biller_code: EDC
              consumer_code: '73562510'
              ref_no: 001937779
              subscribe_date: '2022-02-18 15:30:12'
      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 in English
                  message_kh:
                    type: string
                    description: Response message in Khmer
                  data:
                    type: object
                    properties:
                      subscribe_token:
                        type: string
                        description: Hash calculation field
                    description: Data object
              example:
                code: '000'
                message: ''
                message_kh: ''
                data:
                  subscribe_token: '...Wk83giJmm3zQEqCoNUGXRUe+I5U7mSd0CCCGRa70aBw=='
      security:
      - bearerAuth: []
  /security/token:
    post:
      operationId: paymentAuthorize
      summary: Payment Authorize
      description: 'EDC Payment Gateway will request to this operation to get access token before request to other operations.


        Implemented by: Partner bank. Called by: EDC Payment Gateway.'
      tags:
      - Auto Direct Debit
      servers:
      - url: https://{domain}
        description: Partner bank endpoint
        variables:
          domain:
            default: bank.example.com
            description: Bank API domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: Client username
                password:
                  type: string
                  description: Client password
              required:
              - username
              - password
            example:
              username: EDC
              password: pa$$w0rt
      responses:
        '200':
          description: Response (check `code` for the business result)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Response code
                  token:
                    type: string
                    description: Access token
              example:
                code: '000'
                token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJleHAiOjE2Mjk5MDEyMTUsImp0aSI
      security: []
  /directdebit/payment/confirm:
    post:
      operationId: paymentConfirm
      summary: Payment Confirm
      description: 'EDC Payment Gateway will request to this operation to confirm the payment when consumer has new bill.


        Implemented by: Partner bank. Called by: EDC Payment Gateway.'
      tags:
      - Auto Direct Debit
      servers:
      - url: https://{domain}
        description: Partner bank endpoint
        variables:
          domain:
            default: bank.example.com
            description: Bank API domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                currency:
                  type: string
                  description: Currency code (ISO 4217)
                transaction_amount:
                  type: number
                  format: float
                  description: Bill amount
                transaction_ref:
                  type: string
                  description: Biller transaction reference number
                subscribe_token:
                  type: string
                  description: Subscribe token
                company_code:
                  type: string
                  description: Company code
                company_name:
                  type: string
                  description: Company name
              required:
              - currency
              - transaction_amount
              - transaction_ref
              - subscribe_token
              - company_code
              - company_name
            example:
              currency: KHR
              transaction_amount: 100000
              transaction_ref: '2714902590000102001'
              subscribe_token: '...Wk83giJmm3zQEqCoNUGXRUe+I5U7mSd0CCCGRa70aBw=='
              company_code: EDC-BTB
              company_name: អគ្គិសនីបាត់ដំបង
      responses:
        '200':
          description: Response (check `code` for the business result)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Response code
                  status:
                    type: string
                    description: Response status
                  message:
                    type: string
                    description: Response message
                  transaction_id:
                    type: string
                    description: Transaction ID at bank side
                  transaction_date:
                    type: string
                    description: Transaction date
                  convenience_fee_amount:
                    type: number
                    description: Bank transaction fee charge (Consumer pay the fee)
                  sponsor_fee_amount:
                    type: number
                    description: Bank transaction fee charge (Biller pay the fee)
              example:
                code: '000'
                status: Success
                message: Transaction successfully.
                transaction_id: FT2120805B9YG4S6
                transaction_date: '2022-02-20 15:30:12.000'
                convenience_fee_amount: 0.0
                sponsor_fee_amount: 0.0
      security:
      - bearerAuth: []
  /directdebit/payment/verify:
    post:
      operationId: paymentVerify
      summary: Payment Verify
      description: 'EDC Payment Gateway will request to this operation to verify the payment.


        Implemented by: Partner bank. Called by: EDC Payment Gateway.'
      tags:
      - Auto Direct Debit
      servers:
      - url: https://{domain}
        description: Partner bank endpoint
        variables:
          domain:
            default: bank.example.com
            description: Bank API domain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction_ref:
                  type: string
                subscribe_token:
                  type: string
                  description: Subscribe token
              required:
              - transaction_ref
              - subscribe_token
            example:
              transaction_ref: '2714902590000102001'
              subscribe_token: '...Wk83giJmm3zQEqCoNUGXRUe+I5U7mSd0CCCGRa70aBw=='
      responses:
        '200':
          description: Response (check `code` for the business result)
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Response code
                  status:
                    type: string
                    description: Response status
                  message:
                    type: string
                    description: Response message
                  transaction_id:
                    type: string
                    description: Transaction ID at bank side
                  transaction_date:
                    type: string
                    description: Transaction date
                  convenience_fee_amount:
                    type: number
                    description: Bank transaction fee charge (Consumer pay the fee)
                  sponsor_fee_amount:
                    type: number
                    description: Bank transaction fee charge (Biller pay the fee)
              example:
                code: '000'
                status: Success
                message: Transaction successfully.
                transaction_id: FT2120805B9YG4S6
                transaction_date: '2022-02-20 15:30:12.000'
                convenience_fee_amount: 0.0
                sponsor_fee_amount: 0.0
      security:
      - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Token provided privately / from the token endpoint