Monoova Generate a Client Session API

openapi: 3.2.0
info:
  description: '# Introduction

    Monoova''s Online Card Payment Service incorporates a next-gen Card Payment Checkout integrated with our expansive Payments API to allow merchants to capture card and mobile wallet payments from your customers online and receive funds into your Monoova account for automated reconciliation and disbursement.'
  version: v1
  title: Monoova Card Payments Generate a Client Session API
  contact:
    name: Monoova Support
    email: support@monoova.com
    url: https://www.monoova.com
  x-logo:
    url: https://movdpwebsiteprodae.blob.core.windows.net/images/Monoova-Primary-Logo-Black-RGB.png
    altText: Monoova logo
servers:
- url: https://api.monoova.com
  description: Production URL#
- url: https://sand-api.monoova.com
  description: Sandbox URL
security:
- BearerAuth: []
tags:
- name: Generate a Client Session
paths:
  /au/card/ccm/CreditCardTransaction/token:
    post:
      tags:
      - Generate a Client Session
      summary: Generate a Client Session
      description: This endpoint is used to generate a client session token which is required to render the payment screen. All the fields are mandatory and will be passed on to the issuer while creating payments.
      operationId: generate-clientSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClientSessionDto'
            example:
              clientTransactionUniqueReference: 6aac85b115c7405180e6c7a7735c9f3c
              customer:
                billingAddress:
                  firstName: Joseph
                  lastName: Blogs
                  street:
                  - 1 Walker St
                  suburb: North Sydney
                  state: NSW
                  postalCode: '2000'
                  countryCode: AU
                emailAddress: joe.blogs@monoova.com
                customerId: '12345678'
                firstName: Joseph
                lastName: Blogs
              paymentDetails:
                cardType: Visa
                description: sample token create
                saveOnSuccess: true
                clientPaymentTokenUniqueReference: my-visa-card
                capturePayment: true
                applySurcharge: false
              amount:
                currencyAmount: 100.0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateClientSessionResponse'
        '400':
          description: Error
          content:
            application/json:
              example:
                traceId: 0d4518e0-8934-489c-b303-1f82323f2595
                errors:
                - errorCode: CCM_ACC_LIMIT_REACHED
                  errorMessage: transaction amount 100.00 plus existing transactions 100.00 exceeds limit 50
        '500':
          description: Error
          content:
            application/json:
              example:
                traceId: fb2d673d-3c5a-408e-8d3c-76f7c4ac2aca
                errors:
                - errorCode: CCM_UNEXPECTED_ERROR
                  errorMessage: Internal server error. Please contact Monoova support.
components:
  schemas:
    CreateClientSessionDto:
      type: object
      required:
      - clientTransactionUniqueReference
      - customer
      - paymentDetails
      - amount
      properties:
        clientTransactionUniqueReference:
          type: string
          description: Id will be used to uniquely identify each payment request made by our customer. <br/> Id should be unique across Payment and Refund.
          maxLength: 40
          pattern: ^[a-zA-Z0-9_-]{1,40}$
        customer:
          $ref: '#/components/schemas/CustomerDetailsDto'
        paymentDetails:
          $ref: '#/components/schemas/PaymentDetailsDto'
        amount:
          type: object
          properties:
            currencyAmount:
              description: Payment amount. Must be zero when capturePayment is false, otherwise must be greater than zero.
              type: number
              format: decimal
              maximum: 20000000.0
              minimum: 0.0
              multipleOf: 0.01
      additionalProperties: false
    CustomerDetailsDto:
      type: object
      required:
      - emailAddress
      properties:
        billingAddress:
          type:
          - object
          - 'null'
          description: The customers billing address. If any part of the billing address is provided, all of the following fields must be provided
          properties:
            firstName:
              type:
              - string
              - 'null'
              maxLength: 60
              description: First name of the biller
            lastName:
              type:
              - string
              - 'null'
              maxLength: 60
              description: Last name of the biller
            street:
              type: string
              maxLength: 60
              description: Street of the biller
            suburb:
              type: string
              maxLength: 14
              description: Suburb of the biller
            state:
              type: string
              maxLength: 3
              description: State of the biller
            postalCode:
              type: string
              maxLength: 14
              description: Postcode of the biller
            countryCode:
              type: string
              maxLength: 2
              pattern: ^[A-Z]{2}
              description: 2 character ISO country code
        emailAddress:
          description: email address of the biller. This is required for 3DS
          maxLength: 40
          pattern: ^[a-zA-Z0-9.!#$%&’+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)
          type: string
        customerId:
          type: string
          pattern: ^[a-zA-Z0-9_-]{1,40}$
          description: 'Value to uniquely identify a customer within a particular client/mAccount.

            '
        firstName:
          type:
          - string
          - 'null'
          maxLength: 60
          pattern: ^[^#<>$%^_=[\\]\\\\{}|;~`]+$
          description: 'Customer first name. Mandatory if billingAddress is not provided

            '
        lastName:
          type:
          - string
          - 'null'
          maxLength: 60
          pattern: ^[^#<>$%^_=[\\]\\\\{}|;~`]+$
          description: 'Customer last name. Mandatory if billingAddress is not provided

            '
      additionalProperties: false
    GenerateClientSessionResponse:
      type: object
      properties:
        traceId:
          type: string
          example: 36ed60f5-dcf1-4947-a31e-8ec93d06ca4b
        clientTransactionUniqueReference:
          type: string
          example: DCCCC5DE-CC48-4942-A419-F1B84EC122C4
        clientTokenExpirationDate:
          type:
          - string
          - 'null'
          description: The date and time that the session expires.
          example: 2023-02-22 02:49:19.525918+00:00
        clientToken:
          type: string
          example: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6ImNsaWVudC10b2tlbi1zaWduaW5nLWtleSJ9.eyJleHAiOjE2NzcwMzQxNTksImFjY2Vzc1Rva2VuIjoiMDIzZGE2ZWQtMDE2MS00OThiLWI0NDgtNDBjOTc0NDk2ZWEyIiwiYW5hbHl0aWNzVXJsIjoiaHR0cHM6Ly9hbmFseXRpY3MuYXBpLnNhbmRib3guY29yZS5wcmltZXIuaW8vbWl4cGFuZWwiLCJhbmFseXRpY3NVcmxWMiI6Imh0dHBzOi8vYW5hbHl0aWNzLnNhbmRib3guZGF0YS5wcmltZXIuaW8vY2hlY2tvdXQvdHJhY2siLCJpbnRlbnQiOiJDSEVDS09VVCIsImNvbmZpZ3VyYXRpb25VcmwiOiJodHRwczovL2FwaS5zYW5kYm94LnByaW1lci5pby9jbGllbnQtc2RrL2NvbmZpZ3VyYXRpb24iLCJjb3JlVXJsIjoiaHR0cHM6Ly9hcGkuc2FuZGJveC5wcmltZXIuaW8iLCJwY2lVcmwiOiJodHRwczovL3Nkay5hcGkuc2FuZGJveC5wcmltZXIuaW8iLCJlbnYiOiJTQU5EQk9YIiwicGF5bWVudEZsb3ciOiJERUZBVUxUIn0.22vMTZEf66pOelIUpsx_98bYD5cvQWkfnsuhnPE8bII
      additionalProperties: false
    PaymentDetailsDto:
      type: object
      properties:
        cardType:
          type: string
          description: Card Type. Must be one of Visa, Mastercard. Case insensitive.
        description:
          type: string
          description: Payment description. This will be saved in Monoova's system but will not be passed to the issuer.
          maxLength: 40
        saveOnSuccess:
          type: boolean
          default: false
          description: System will save the payment method on successful payment. Optional, defaults to false.
        allowCredit:
          type: boolean
          default: true
          description: If set to true, credit card will be allowed. If set to false only Debit cards and prepaid cards will be allowed. Optional, defaults to true.
        clientPaymentTokenUniqueReference:
          type: string
          description: The unique id the client will use to refer to the persisted token for future payments. Mandatory if saveOnSuccess is true, otherwise prohibited. The value must be unique for this combination of client (mAccount) and customerId. Lowercase will be converted to uppercase.
          maxLength: 40
          pattern: ^[a-zA-Z0-9_-]{1,40}$
        applySurcharge:
          type: boolean
          default: false
          description: Add a calculated fee to the total amount for this transaction. Optional, defaults to false. Only allowed to be true if the surcharging is enabled in the account configuration.
        capturePayment:
          type:
          - boolean
          - 'null'
          description: Set to false (with an appropriate amount) if payment only needs to be authorized. Set to true or ignore this property if payment needs to be authorized and captured.
          default: true
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    BasicAuth:
      type: http
      scheme: basic
x-tagGroups:
- name: ''
  tags:
  - Generate a Bearer Token
  - Generate a Client Session
  - Get Transaction By Id
  - Get Transaction By Date Range
  - Request Refund Transaction
  - Get Async Request Status
  - Create Payment Using Token
  - Get Payment Method Token Details
  - Update Payment Method Token Status
  - Webhooks
  - Monoova Error Codes