NovoPayment Transaction API

openapi: 3.2.0
info:
  description: Merchant Presented QR is a Service that includes payment or transactions process with tokens.
  version: v1
  title: Merchant Presented QR Transaction API
servers:
- description: Sandbox
  url: https://sandbox-api.novopayment.com/api/v1/mpqr
security:
- oAuth2ClientCredentials: []
tags:
- name: Transaction
paths:
  /transaction/makepayment:
    post:
      summary: Make a payment
      operationId: makePayment
      parameters:
      - $ref: '#/components/parameters/XRequestId'
      - $ref: '#/components/parameters/XPayToken'
      - $ref: '#/components/parameters/XTenantId'
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/apikey'
      - $ref: '#/components/parameters/createApiKey'
      requestBody:
        $ref: '#/components/requestBodies/RQMakePayment'
      responses:
        '201':
          $ref: '#/components/responses/RSMakePayment'
        '400':
          $ref: '#/components/responses/RSGenerateQrCode400'
        '401':
          $ref: '#/components/responses/RS401'
        '500':
          $ref: '#/components/responses/RS500'
      tags:
      - Transaction
components:
  parameters:
    createApiKey:
      name: createApiKey
      in: query
      description: 'Whether to create a new API key for the client.


        Note: do not set to true.

        '
      required: true
      schema:
        type: string
        enum:
        - false
        - true
    apikey:
      name: apikey
      in: query
      description: Public API key, which is different from the shared secret.
      required: true
      schema:
        type: string
        maxLength: 49
    XTenantId:
      name: X-tenant-id
      in: header
      description: 'It is necessary send all petitions for identified the client.

        '
      required: true
      schema:
        type: string
    Accept:
      name: Accept
      in: header
      description: 'Acceptable response format.


        Format: Must include application/json

        '
      required: true
      schema:
        type: string
    XPayToken:
      name: x-pay-token
      in: header
      description: 'A token identifying the transaction and its contents.


        The token expires in 480 seconds (8 minutes) for all clients.

        '
      required: true
      schema:
        type: string
    XRequestId:
      name: x-request-id
      in: header
      description: 'Unique ID for the API request.


        Format: Alphabetic, numeric, and hyphens ( - ), e.g. spaces are not allowed.

        '
      required: true
      schema:
        type: string
        maxLength: 36
  schemas:
    ObjtransactionAmount:
      type: object
      required:
      - transactionAmount
      - transactionCurrencyCode
      properties:
        transactionAmount:
          type: string
          description: Amount associated with transaction. Amount as populated in ISO or API is cumulative of tip or convenience fee as encoded in the QR code or tip as entered by the consumer on the mobile app.
          example: '99.34'
          maxLength: 18
        transactionCurrencyCode:
          type: string
          description: Currency code used for the transaction amount. ISO 4217 three-digit currency code.
          example: USD
          maxLength: 3
        additionalAmounts:
          type: array
          description: "A list of additional amounts related to the transaction Each additional amount is a two-item key-value pair, where the key \nfor the first item is “additionalAmountType” and the key for the second item is “additionalAmountValue.” AdditionalAmountType \nis one of following enums:\n  - TIP\n  - CONVENIENCE_FEE\n  - CONVENIENCE_FEE_PERCENTAGE\n  - SUB_TOTAL\n"
          example:
          - “additionalAmountType”: “TIP”
            “additionalAmountValue”: “3”
    ObjTerminalData:
      type: object
      properties:
        initiationMethod:
          type: string
          description: Method of iniciation on terminal.
          example: method1
        posEntryMode:
          type: string
          description: Mode of entry on POS.
          example: mode1
    RSMakePayment:
      type: object
      required:
      - code
      - message
      - datetime
      properties:
        code:
          type: string
          example: 200.22.000
          description: Operation response code
          maxLength: 10
        message:
          type: string
          example: Process Ok
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: '2020-01-03T16:05:56.517Z'
          description: Operation Time Stamp in ISO 8601 format
          format: date-time
    RSGenerateQrCode400:
      type: object
      properties:
        code:
          type: string
          example: 400.22.003
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          example: Params required
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: '2020-01-03T16:05:56.517Z'
          format: date-time
    ObjDpaTransactionOptions:
      type: object
      required:
      - dpaName
      - merchantChannel
      - transactionAmount
      properties:
        dpaName:
          type: string
          description: Name of the Mobile Application Provider
          example: dpa name
          maxLength: 60
        dpaLocale:
          type: string
          description: Mobile Application Provider’s preferred locale. Based on ISO format for language (ISO 639-1) and alpha-2 country code (ISO 3166-1 alpha-2). The language and country should be separated using an underscore (_).
          example: en_US
        dpaAcceptedBillingCountries:
          type: array
          description: Billing countries. Payments from the listed billing countries are accepted. If this list is empty, all countries are accepted Array of country codes in ISO 3166-1 alpha-2 forma
          example:
          - US
          - “CA”
          - “AU”
        dpaAcceptedShippingCountries:
          type: array
          description: Shipping countries; shipping region country codes that limit the selection of eligible shipping addresses. If this list is empty, all countries are accepted. Array of country codes in ISO 3166-1 alpha-2 format.
          example:
          - us
          - br
        transactionType:
          type: string
          description: This field is informational only. It is not used in the SRC platform for QR transaction processing. To differentiate CNP transaction from a CP transaction, the merchant channel value in dpaTransactionOptions.merchantChannel should correctly indicate the nature of the transaction.
          example: PURCHASE
          enum:
          - PURCHASE (default)
          - BILL_PAYMENT
          - MONEY_TRANSFER
        orderType:
          type: string
          description: Type of orders.
          example: REAUTHORIZATION
          enum:
          - REAUTHORIZATION
          - RECURRING
          - INSTALLMENT
        transactionAmount:
          type: object
          $ref: '#/components/schemas/ObjtransactionAmount'
        merchantOrderId:
          type: string
          description: The order identifier generated by the Mobile Application Provider. Typically used for reconciliation process.
          example: Order1
        merchantCategoryCode:
          type: string
          description: Code associated with Merchant Category.
          example: '5251'
        merchantCountryCode:
          type: string
          description: The country code associated with the merchant's billing or shipping address. ISO-3166 - 1 alpha-2 standard code.
          example: US - United States
        merchantChannel:
          type: string
          description: "Merchant channel establishes the environment in which a QR Code is presented to the consumer. Covering use cases such \nas retail outlet, Ecommerce, bill payment with the purpose of improving transaction reporting. Refer to tables below \nfor details on populating.\n\n  First Character - Media:\n  - 0: Print - Merchant Sticker\n  - 1: Print - Bill / Invoice\n  - 2: Print - Magazine / Poster\n  - 3: Print - Other\n  - 4: Screen / Electronic - Merchant POS / POI \n  - 5: Screen / Electronic - Website \n  - 6: Screen / Electronic - App \n  - 7: Screen / Electronic - Other \n\n  Second Character - Transaction Location:\n  - 0: At Merchant premises / registered address\n  - 1: Not at Merchant premises / registered address\n  - 2: Remote Commerce\n  - 3: Other\n\n  Third Character - Merchant Presence:\n  - 0: Attended POI\n  - 1: Unattended\n  - 2: Semi-attended (self-checkout)\n  - 3: Other  \n"
          example: '600'
        acquirerId:
          type: string
          description: Merchant's Acquirer ID. Not currently used in Visa Pull QR payments.
          example: '498909'
        acquirerMid:
          type: string
          description: Acquirer's Merchant ID. Required in case of Visa QR, utilize Merchant ID provided from QR code.
          example: 00000079
        sellerPresentedData:
          type: object
          required:
          - qrData
          properties:
            customInputData:
              type: array
              description: Data from the Merchant Presented QR code.List of key and value pair.
              example:
              - key: “id_55”
                value: '02'
              - key: “id_56”
                value: '10'
              - key: “id_58”
                value: MX
            qrData:
              type: string
              description: Raw entire QR code data, from scanning QR. Base64 encoded.
              example: Zmdk...GdkZg==
        additionalSellerData:
          type: object
          properties:
            customInputData:
              type: array
              description: Custom input data, as presented by seller; all additional custom data required for processing. List of key and value pair.
              example:
              - key: Sample Key1
                value: '204'
              - key: Sample Key2
                value: abc
        consumerInputData:
          type: object
          properties:
            billNumber:
              type: string
              description: The invoice number or bill number. This number could be provided by the merchant or could be an indication for the mobile application to prompt the consumer to input a Bill Number. For example, the Bill Number may be present when the QR Code is used for bill payment. Required when Present in QR code under the Additional Data Field Template.
            mobileNumber:
              type: string
              description: The mobile number could be provided by the merchant or could be an indication for the mobile application to prompt the consumer to input a Mobile Number. For example, the Mobile Number to be used for multiple use cases, such as mobile top-up and bill payment. Required when Present in QR code under the Additional Data Field Template.
            storeLabel:
              type: string
              description: A distinctive value associated to a store. This value could be provided by the merchant or could be an indication for the mobile application to prompt the consumer to input a Store Label. For example, the Store Label may be displayed to the consumer on the mobile application identifying a specific store. Required when Present in QR code under the Additional Data Field Template.
            loyaltyNumber:
              type: string
              description: Typically, a loyalty card number. This number could be provided by the merchant, if known, or could be an indication for the mobile application to prompt the consumer to input their Loyalty Number. Required when Present in QR code under the Additional Data Field Template.
            referenceLabel:
              type: string
              description: Any value as defined by the merchant or acquirer to identify the transaction. This value could be provided by the merchant or could be an indication for the mobile app to prompt the consumer to input a transaction Reference Label. For example, the Reference Label may be used by the consumer mobile application for transaction logging or receipt display. Required when Present in QR code under the Additional Data Field Template.
            customerLabel:
              type: string
              description: Any value identifying a specific consumer. This value could be provided by the merchant (if known) or could be an indication for the mobile application to prompt the consumer to input their Customer Label. For example, the Customer Label may be a subscriber ID for subscription services, a student enrolment number, etc. Required when Present in QR code under the Additional Data Field Template.
            terminalLabel:
              type: string
              description: A distinctive value associated to a unique sponsored merchant, store location, terminal, or device. See above Merchant ID generation section for details on populating. For example, the Terminal Label may be displayed to the consumer on the mobile application identifying a specific terminal. Required when Present in QR code under the Additional Data Field Template.
            purposeOfTransaction:
              type: string
              description: Any value defining the purpose of the transaction. This value could be provided by the merchant or could be an indication for the mobile application to prompt the consumer to input a value describing the purpose of the transaction. For example, the Purpose of Transaction may have the value "International Data Package" for display on the mobile application. Required when Present in QR code under the Additional Data Field Template.
            additionalConsumerDataRequest:
              type: string
              description: Contains indications that the mobile application is to provide the requested information in order to complete the transaction. The information requested should be provided by the mobile application in the authorization without unnecessarily prompting the consumer. For example, the Additional Consumer Data Request may indicate that the consumer mobile number is required to complete the transaction, in which case the mobile application should be able to provide this number (that the mobile application has previously stored) without unnecessarily prompting the consumer.
              example: ME
    RS500:
      type: object
      properties:
        code:
          type: string
          example: 500.22.999
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          example: Internal Server Error
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: '2020-01-03T16:05:56.517Z'
          format: date-time
    RS401:
      type: object
      properties:
        code:
          type: string
          example: 401.22.990
          description: Operation response code
          minLength: 10
          maxLength: 10
        message:
          type: string
          example: Invalid Access Token
          description: Response code description
          maxLength: 140
        datetime:
          type: string
          example: '2020-01-03T16:05:56.517Z'
          format: date-time
    ObjDpaPhoneNumber:
      type: object
      properties:
        countryCode:
          type: string
          description: Country code.
          example: 1
        phoneNumber:
          type: string
          description: Phone number
          example: 3025874589
    ObjDpaAddress:
      type: object
      properties:
        addressId:
          type: string
          description: Address ID.
          example: 2f679779-3f42-4b8e-5e81-1d259e56ber1
        name:
          type: string
          description: Name
          example: something
        line1:
          type: string
          description: Line 1.
          example: NA
        line2:
          type: string
          description: Line 2.
          example: NA
        line3:
          type: string
          description: Line 3.
          example: NA
        city:
          type: string
          description: City.
          example: Coral Gables
        state:
          type: string
          description: State
          example: FL
        countryCode:
          type: string
          description: Country code
          example: US
        zip:
          type: string
          description: Zip
          example: 33146
        createTime:
          type: string
          description: create time
          example: 12-12-2025
        lastTimeUsed:
          type: string
          description: Last time used
          example: 21-12-2022
    ObjDpaData:
      type: object
      properties:
        dpaPresentationName:
          type: string
          description: DPA presentation Name.
          example: DPA presentation
        dpaAddress:
          type: object
          $ref: '#/components/schemas/ObjDpaAddress'
        dpaName:
          type: string
          description: DPA Name.
          example: DPA name
        dpaEmailAddress:
          type: string
          description: DPA email.
          example: email@dpa.com
        dpaPhoneNumber:
          type: object
          $ref: '#/components/schemas/ObjDpaPhoneNumber'
        dpaLogoUri:
          type: string
          description: DPA logo URI.
          example: www.logos.com
        dpaSupportEmailAddress:
          type: string
          description: DPA suppot Email.
          example: logos@logos.com
        dpaSupportPhoneNumber:
          type: object
          $ref: '#/components/schemas/ObjDpaPhoneNumber'
        dpaSupportUri:
          type: string
          description: DPA support URL.
          example: www.uri.com
        dpaUri:
          type: string
          description: DPA  URI.
          example: www.uri.com
        applicationType:
          type: string
          description: Application type
          example: application/json
        terminalData:
          type: object
          $ref: '#/components/schemas/ObjTerminalData'
        merchantAccountInformation:
          type: string
          description: Merchant Account Information
          example: 400258936325
    RQMakePayment:
      type: object
      required:
      - srcCorrelationId
      properties:
        srcCorrelationId:
          type: string
          description: The unique identifier generated by Visa to track and link API messages. This is used as a transaction identifier assigned by Visa for this particular transaction. Universally Unique Identifier (UUID).
          example: 5821c929-deee-49b7-a6ce-ba88dadbb734
        srcDpaId:
          type: string
          description: Mobile Application Provider identifier, which is generated by Visa during Mobile Apption Plicarovider registration.
          example: DPAID
        srciTransactionId:
          type: string
          description: A unique transaction ID created by the Mobile Application Provider, which may be created on the merchant page. It must be passed through to Visa
          example: 2f679779-3f42-4b8e-5e81-1d259e56ber1
          maxLength: 100
        encryptedPayload:
          type: string
          description: Payload including payment information for authorization purposes.
          example: 4DuQx...b4964M
        dpaData:
          type: object
          $ref: '#/components/schemas/ObjDpaData'
        dpaTransactionOptions:
          type: object
          $ref: '#/components/schemas/ObjDpaTransactionOptions'
  responses:
    RSMakePayment:
      description: Make Payment response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSMakePayment'
    RSGenerateQrCode400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSGenerateQrCode400'
          examples:
            Params Required:
              $ref: '#/components/examples/ParamsRequired'
            Invalid Tenant Id:
              $ref: '#/components/examples/InvalidTenantId'
            Invalid Data:
              $ref: '#/components/examples/InvalidData'
            Invalid Parameters:
              $ref: '#/components/examples/InvalidParameters'
            Error General Services:
              $ref: '#/components/examples/ErrorGeneralServices'
    RS401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RS401'
          examples:
            Invalid Access Token:
              $ref: '#/components/examples/InvalidAccessToken'
            Access Token Not Approved:
              $ref: '#/components/examples/AccessTokenNotApproved'
            Invalid Signature:
              $ref: '#/components/examples/InvalidSignature'
            Access Token Expired:
              $ref: '#/components/examples/AccessTokenExpired'
    RS500:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RS500'
  examples:
    InvalidTenantId:
      value:
        code: 400.22.004
        message: Invalid Tenant ID
        datetime: '2020-01-03T16:05:56.517Z'
    InvalidAccessToken:
      value:
        code: 401.22.990
        message: Invalid Access Token
        datetime: '2020-01-03T16:05:56.517Z'
    InvalidSignature:
      value:
        code: 401.22.992
        message: Invalid signature
        datetime: '2020-01-03T16:05:56.517Z'
    ParamsRequired:
      value:
        code: 400.22.003
        message: Params required
        datetime: '2020-01-03T16:05:56.517Z'
    InvalidParameters:
      value:
        code: 400.22.396
        message: Invalid Parameters
        datetime: '2020-01-03T16:05:56.517Z'
    ErrorGeneralServices:
      value:
        code: 400.22.350
        message: Error General Services
        datetime: '2020-01-03T16:05:56.517Z'
    InvalidData:
      value:
        code: 400.22.089
        message: Invalid Data
        datetime: '2020-01-03T16:05:56.517Z'
    AccessTokenExpired:
      value:
        code: 401.22.993
        message: Access token expired
        datetime: '2020-01-03T16:05:56.517Z'
    AccessTokenNotApproved:
      value:
        code: 401.22.991
        message: Access Token not approved
        datetime: '2020-01-03T16:05:56.517Z'
  requestBodies:
    RQMakePayment:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RQMakePayment'
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      description: 'See [Oauth2 API](https://developer.novopayment.com/api/authentication-method-and-encryption/oauth2-api)

        '
      flows:
        clientCredentials:
          tokenUrl: https://sandbox-api.novopayment.com/oauth2/token
          scopes: {}