> ## Documentation Index
> Fetch the complete documentation index at: https://docs.commercepay.asia/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Payment

> **The payment gateway requests a new payment**

The following input parameters are expected to be provided by the merchant to perform an online payment transaction.

> - Channel Id may refer to the [Get Channel List](/api-reference/get-tenant-channels-by-country)
> - If merchants would like to use [CommercePay Hosted Payment Web solution](/docs/hosted-session-checkout), merchants may skip Channel Id parameter.



## OpenAPI

````yaml /openapi.json post /api/services/app/PaymentGateway/RequestPayment
openapi: 3.0.1
info:
  title: CommercePay API
  version: v1
  description: >
    ---

    **Credentials Accounts**


    Every account is provided with separate keys for testing and for running
    live transactions. Once the merchant application has been approved,
    developers can begin the process of integrating the CommercePay API. The
    following details will be provided to get started with the integration. 


    <a href="https://docs.commercepay.asia/docs/api/d19b0f3289ae0-get-started"
    target="_blank">Get Started</a>
  contact: {}
servers:
  - description: Staging
    url: https://staging-payments.commerce.asia
  - url: https://payments.commerce.asia
    description: Production
security: []
paths:
  /api/services/app/PaymentGateway/RequestPayment:
    post:
      tags:
        - PaymentGateway
      summary: Request Payment
      description: >-
        **The payment gateway requests a new payment**


        The following input parameters are expected to be provided by the
        merchant to perform an online payment transaction.


        > - Channel Id may refer to the [Get Channel
        List](/api-reference/get-tenant-channels-by-country)

        > - If merchants would like to use [CommercePay Hosted Payment Web
        solution](/docs/hosted-session-checkout), merchants may skip Channel Id
        parameter.
      operationId: ApiServicesAppPaymentgatewayRequestpaymentPost
      parameters:
        - $ref: '#/components/parameters/AbpTenantId'
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/CapSignature'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestPaymentInputDto'
            examples:
              Example Request:
                value:
                  channelId: 0
                  providerChannelId: string
                  currencyCode: MYR
                  amount: 0
                  referenceCode: string
                  description: string
                  ipAddress: string
                  userAgent: string
                  returnUrl: string
                  callbackUrl: string
                  savePayment: false
                  customer:
                    email: string
                    mobileNo: string
                    name: string
                    username: string
                    identificationNumber: string
                    identificationType: 1
                  subMerchant:
                    uniqueId: string
                    name: string
                  localCitizen: true
                  recurringPaymentInfo:
                    id: string
                    mode: 1
                    numberOfPayments: 1
                    effectiveDate: string
                    maximumPaymentAmount: 0
                    expiryDate: string
                    isFixedAmount: true
                  requestPaymentExtraInfo:
                    channelGroupId: 0
                  platformCharge:
                    partnerId: string
                    amount: 0
                  timestamp: 0
              Sample Input:
                value:
                  channelId: 2
                  providerChannelId: TEST0021
                  currencyCode: MYR
                  amount: 100
                  referenceCode: string
                  description: Order details
                  ipAddress: string
                  userAgent: string
                  returnUrl: https://returnurl.com/
                  callbackUrl: https://callback.com/
                  customer:
                    email: email@gmail.com
                    mobileNo: '0123456789'
                    name: name
                    username: username
                  timestamp: 1621851652617
        description: ''
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestPaymentOutputDto'
              examples:
                Example Response:
                  value:
                    currencyCode: MYR
                    amount: 0
                    transactionNumber: string
                    channelId: 0
                    redirectionType: 1
                    redirectUrl: string
                    clientScript: string
        '400':
          description: |-
            Bad Request
            Invalid Timestamp.
            Invalid Signature.
components:
  parameters:
    AbpTenantId:
      schema:
        type: string
      in: header
      name: Abp-TenantId
      required: true
      description: Your unique Merchant ID assigned by CommercePay.
    Authorization:
      schema:
        type: string
      in: header
      name: Authorization
      required: true
      description: Your API credentials used for authentication (typically a Bearer token).
    CapSignature:
      schema:
        type: string
      in: header
      name: cap-signature
      required: true
      description: >-
        A unique security hash used to verify the integrity of the request body.
        See [Generate Signature](/docs/generate-signature) for how to generate
        this.
  schemas:
    RequestPaymentInputDto:
      type: object
      additionalProperties: false
      x-examples:
        Example 1:
          channelId: 2
          providerChannelId: TEST0021
          currencyCode: MYR
          amount: 100
          referenceCode: string
          description: Order details
          ipAddress: string
          userAgent: string
          returnUrl: https://returnurl.com/
          callbackUrl: https://callback.com/
          savePayment: true
          customer:
            email: email@gmail.com
            mobileNo: '0123456789'
            name: name
            username: username
            identificationNumber: string
            identificationType: 1
          subMerchant:
            uniqueId: string
            name: string
          localCitizen: true
          recurringPaymentInfo:
            id: string
            mode: 1
            numberOfPayments: 0
            effectiveDate: string
            maximumPaymentAmount: 0
            expiryDate: string
            isFixedAmount: true
          requestPaymentExtraInfo:
            channelGroupId: 0
          platformCharge:
            partnerId: string
            amount: 0
          timestamp: 1621851652617
      required:
        - currencyCode
        - amount
        - referenceCode
        - ipAddress
        - returnUrl
        - timestamp
      properties:
        channelId:
          type: integer
          format: int32
          description: >-
            An identifier that represents a CommercePay payments channel. Refer
            to the id on response endpoints of [Get Channel
            List](/api-reference/get-tenant-channels-by-country)


            Optional: Send without channelId parameter to call Payment web
          example: 2
          nullable: true
        providerChannelId:
          type: string
          description: >-
            An identifier that represents the payment provider channel. To get
            providerChannelId, kindly refer to [Get Provider
            Channels](/api-reference/get-provider-channels) for more information
          example: TEST0021
          nullable: true
        currencyCode:
          type: string
          description: Currency code with a 3-letter ISO 4217 standard code
          maxLength: 3
          example: MYR
        amount:
          type: integer
          format: int64
          description: >-
            **Please take note:** The Amount parameter only accepts integer
            units. For example, 1000 is equivalent to 10.00 for the backend.


            Invalid Format: 1,000.00
          example: 100
        referenceCode:
          type: string
          description: Merchant Reference Code
          maxLength: 50
        description:
          type: string
          description: Transaction Description
          example: Order details
          maxLength: 100
          nullable: true
        ipAddress:
          type: string
          description: Customer’s IP address captured by the merchant system
          maxLength: 50
        userAgent:
          type: string
          description: >-
            **[Conditional]** Customer’s user agent. It is recommended to input
            for a better user experience for specific channels due to different
            platforms such as desktop, mobile, or app view. Example channels
            impact: ShopeePay
          maxLength: 200
          nullable: true
        returnUrl:
          type: string
          description: >-
            Return URL supplied by the merchant server for the payment response
            and used by CommercePay to redirect the customer's browser back to
            the desired page on the Merchant’s site
          example: https://returnurl.com/
          maxLength: 500
        callbackUrl:
          type: string
          example: https://callback.com/
          maxLength: 500
          description: >-
            Callback URL is host-to-host communication. CommercePay sends the
            transaction response to the merchant callback server based on the
            callback URL given. If the URL is provided, the callback will be
            triggered; otherwise, it would not trigger. Refer to the Merchant
            Callback URL to know more
          nullable: true
        savePayment:
          type: boolean
          description: >-
            **[Conditional for Tokenize Payment]** To save user info for
            subsequent payment
        customer:
          $ref: '#/components/schemas/PayeeDto'
        subMerchant:
          $ref: '#/components/schemas/SubMerchant'
        localCitizen:
          type: boolean
          description: >-
            **[Conditional for certain channel]** Example: If the customer is
            from Malaysia, kindly set it as True; else, set it as False
        recurringPaymentInfo:
          $ref: '#/components/schemas/RecurringPaymentInfoDto'
        requestPaymentExtraInfo:
          $ref: '#/components/schemas/RequestPaymentExtraInfo'
        platformCharge:
          $ref: '#/components/schemas/PlatformChargeDto'
        timestamp:
          type: integer
          format: int64
          description: new Date().getTime()
          example: 1621851652617
        ChannelDetails:
          $ref: '#/components/schemas/ChannelDetailsDto'
        BrowserInfo:
          $ref: '#/components/schemas/BrowserInfoDto'
        VirtualAccountCode:
          type: string
          maxLength: 30
          description: Code to identify virtual account to make payment.
          nullable: true
        loyaltyPaymentInfoDto:
          $ref: '#/components/schemas/LoyaltyPaymentInfoDto'
    RequestPaymentOutputDto:
      type: object
      additionalProperties: false
      x-examples:
        example-1:
          currencyCode: MYR
          amount: 100
          transactionNumber: string
          channelId: -2147483648
          redirectionType: 1
          redirectUrl: string
          clientScript: string
      x-internal: false
      properties:
        currencyCode:
          type: string
          description: Currency code with a 3-letter ISO 4217 standard code
          example: MYR
          maxLength: 3
          nullable: true
        amount:
          type: integer
          format: int64
          description: >-
            **Please take note:** The Amount parameter only accepts integer
            units. For example, 1000 is equivalent to 10.00 for the backend
          example: 100
        transactionNumber:
          type: string
          description: Unique CAP Transaction Number
          maxLength: 24
          nullable: true
        channelId:
          type: integer
          format: int32
          description: >-
            Refer to endpoints in [Get Channel
            List](/api-reference/get-tenant-channels-by-country)
          nullable: true
        redirectionType:
          $ref: '#/components/schemas/RedirectionType'
        redirectUrl:
          type: string
          description: URL used for the customer to redirect to the payment page
          nullable: true
        clientScript:
          type: string
          description: Client script used for the customer to redirect to the payment page
          nullable: true
        transactionExpired:
          type: string
          format: date-time
          description: Transaction Expired Date Time
    PayeeDto:
      type: object
      additionalProperties: false
      x-examples: {}
      properties:
        email:
          type: string
          description: Customer’s Email Address
          example: email@gmail.com
          maxLength: 150
          nullable: true
        mobileNo:
          type: string
          description: Customer’s Mobile Number
          example: '0123456789'
          maxLength: 16
          nullable: true
        name:
          type: string
          description: Customer’s Name
          example: name
          maxLength: 36
          nullable: true
        username:
          type: string
          description: Customer’s unique ID for recurring payments or next saved payments
          example: username
          maxLength: 36
          nullable: true
        identificationNumber:
          type: string
          description: '**[Conditional for FPX Recurring]**'
        identificationType:
          $ref: '#/components/schemas/IdentificationType'
    SubMerchant:
      type: object
      properties:
        uniqueId:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
      additionalProperties: false
    RecurringPaymentInfoDto:
      type: object
      additionalProperties: false
      description: '[Conditional for Recurring Payment]'
      properties:
        id:
          type: string
          description: >-
            Unique ID provided by the merchant to identify a subscription or
            account for recurring payments
          nullable: true
        mode:
          $ref: '#/components/schemas/RecurringMode'
        numberOfPayments:
          type: integer
          format: int32
          description: >-
            Maximum Recurring Frequency: 999 (Example: Frequency value 1 => 1
            day / 1 week / 1 month / 1 year)
          nullable: true
        effectiveDate:
          type: string
          description: Recurring effective start date Format ddMMyyyy (E.g 20122022)
          nullable: true
        maximumPaymentAmount:
          type: integer
          format: int64
          description: Maximum payment amount of the each recurring payment
          minimum: 0
          nullable: true
        expiryDate:
          type: string
          description: Recurring expiry date format ddMMyyyy (E.g 20122022)
          nullable: true
        isFixedAmount:
          type: boolean
          description: Whether every recurring is a fixed amount or not
          nullable: true
    RequestPaymentExtraInfo:
      type: object
      description: '[Optional]'
      properties:
        ChannelGroupId:
          type: integer
          description: >-
            Optional: Used for displaying selected channel groups on CommercePay
            hosted payment web
          format: int32
          nullable: true
        HiddenChannel:
          type: array
          description: 'Optional: To hide channels on CommercePay hosted payment web'
          deprecated: true
          nullable: true
          items:
            type: integer
            format: int32
            default: 0
        WhitelistChannelGroup:
          type: array
          description: >-
            Optional: Specific channel group channel display on the CommercePay
            hosted payment page.
          nullable: true
          items:
            type: integer
            format: int32
        WhitelistChannel:
          type: array
          description: >-
            Optional: Specific channel display on the CommercePay hosted payment
            page.
          nullable: true
          items:
            type: integer
            format: int32
    PlatformChargeDto:
      type: object
      additionalProperties: false
      description: >-
        Optional: Only Authorized Partners by CommercePay are allowed to charge
        platform fees to the merchant
      properties:
        partnerId:
          type: string
          description: Unique Id to identify authorized partner.
          nullable: true
        amount:
          type: integer
          format: int64
          description: Platform charge amount.
          nullable: true
    ChannelDetailsDto:
      type: object
      x-examples:
        Example 1:
          cardNumber: '5123450000000008'
          expiryMonth: '01'
          expiryYear: '39'
          holderName: test
          securityCode: '100'
          AuthType: 1
      description: '[Optional]'
      properties:
        cardNumber:
          type: string
          description: Card Number
          example: 48481000XXXXXXXX
          nullable: true
        expiryMonth:
          type: string
          description: Card Expiry Month
          example: '01'
          nullable: true
        expiryYear:
          type: string
          description: Card Expiry Year
          example: '99'
          nullable: true
        holderName:
          type: string
          description: Card Holder Name
          example: ALEXXXXXXXX
          nullable: true
        securityCode:
          type: string
          description: Card Security Code
          maxLength: 3
          example: '999'
        AuthType:
          $ref: '#/components/schemas/AuthType'
    BrowserInfoDto:
      type: object
      x-examples:
        Example 1:
          javaEnabled: true
          colorDepth: 24
          screenHeight: 600
          screenWidth: 800
          timeZoneOffset: '+08:00'
      properties:
        javaEnabled:
          type: boolean
          nullable: true
        colorDepth:
          type: integer
          nullable: true
        screenHeight:
          type: integer
          nullable: true
        screenWidth:
          type: integer
          nullable: true
        timeZoneOffset:
          type: string
          nullable: true
      description: '[Optional]'
    LoyaltyPaymentInfoDto:
      title: LoyaltyPaymentInfoDto
      type: object
      description: '[Conditional for Loyalty payment]'
      properties:
        cardNumber:
          type: string
          description: Card Number
        cardPassword:
          type: string
          description: Card Password
        redemptionPoint:
          type: integer
          format: int64
          description: Redemption Point
          example: 10
    RedirectionType:
      enum:
        - 1
        - 2
      type: integer
      format: int32
      x-enumNames:
        - UrlRedirection
        - RenderScriptRedirection
      description: |
        Notes: 1 = UrlRedirection
    IdentificationType:
      enum:
        - 1
        - 2
        - 3
        - 4
        - 5
      type: integer
      x-enumNames:
        - NewIdentityNumber
        - OldIdentityNumber
        - PassportNumber
        - BusinessRegistration
        - Others
      x-examples: {}
      description: >-
        **[Conditional for FPX Recurring]**


        New Identity Number = 1, Old Identity Number = 2, Passport Number = 3,
        Business Registration = 4, Others = 5
    RecurringMode:
      enum:
        - 1
        - 2
        - 3
        - 4
      type: integer
      format: int32
      x-enumNames:
        - Daily
        - Weekly
        - Monthly
        - Yearly
      description: Daily = 1, Weekly = 2, Monthly = 3, Yearly = 4
      title: ''
    AuthType:
      title: AuthType
      enum:
        - 1
      x-enumNames:
        - PreAuth

````