NovoPayment Onboarding 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 Onboarding API
servers:
- description: Sandbox
  url: https://sandbox-api.novopayment.com/api/v1/mpqr
security:
- oAuth2ClientCredentials: []
tags:
- name: Onboarding
paths:
  /onboarding:
    post:
      summary: Create Merchant
      description: Acquirers use this endpoint to register a Merchant in the MPQR ecosystem
      operationId: CreateMerchant
      requestBody:
        $ref: '#/components/requestBodies/RQCreateMerchant'
      responses:
        '200':
          $ref: '#/components/responses/RSCreateMerchant'
        '400':
          $ref: '#/components/responses/RSCreateMerchant400'
        '401':
          $ref: '#/components/responses/RS401'
        '500':
          $ref: '#/components/responses/RS500'
      tags:
      - Onboarding
components:
  schemas:
    RQCreateMerchant:
      type: object
      required:
      - companyPrimaryLegalName
      - primaryWebsiteURL
      - companyCity
      - companyCountryCode
      - primaryContactEmail
      - acquirerIdentifiers
      properties:
        serviceContext:
          type: string
          description: Service context
          example: TOKENIZATION
          maxLength: 13
          enum:
          - TOKENIZATION
        dunsNumber:
          type: number
          description: A D&B DUNS number is a nine-digit number that is recognized as the universal standard to track businesses worldwide. It is designed to enhance the credibility of your business and enable potential customers, lenders, and suppliers to learn about your company.
          example: 75102765
          maxLength: 9
        companyPrimaryTradeName:
          type: string
          description: Trade name of token requestor, such as a doing-business-as(DBA) name. If not specified, the legal name(companyPrimaryLegalName) is used by default.<br><br>**Allowed characters**:<br>Alphanumeric, excepting semi-colon, percent sign, and parentheses.
          maxLength: 75
        companyPrimaryLegalName:
          type: string
          description: Legal name of token requestor. Some processors may not support a 75-character legal name. You cannot exceed the limit imposed by your processor.<br><br>**Allowed characters**:<br>Alphanumeric, excepting semi-colon, percent sign, and parentheses
          example: Pepito Pizza
          maxLength: 75
        status:
          type: string
        primaryWebsiteURL:
          type: string
          description: The URL for your token requestor’s site for handling VTS transactions.<br><br>**Allowed characters**:<br>Alphanumeric, valid URL
          example: www.pepitospizza.com
          maxLength: 100
        companyAddress1:
          type: string
          description: 'First line of the token Requestor’s primary address.<br><br>**Allowed characters**:<br>Alphabetic, numeric, or the following characters: spaces, ‘ (single quote), # (pound-sign or hash), , (comma), _ (underscore), :(colon), / (forward slash), and – (hyphen)

            '
          maxLength: 140
        companyAddress2:
          type: string
          description: 'First line of the token requestor’s primary address.<br><br>**Allowed characters**: Alphabetic, numeric, or the following characters: spaces, ‘ (single quote), # (pound-sign or hash), , (comma), _ (underscore), :(colon), / (forward slash), and – (hyphen)

            '
          maxLength: 140
        companyCity:
          type: string
          description: 'City in the token requestor’s primary address.<br><br>**Allowed characters**:<br>Alphabetic, numeric, or the following characters: spaces, ‘ (single quote), . (period), and – (hyphen)

            '
          example: Mexico City
          maxLength: 100
        companyStateProvinceCode:
          type: string
          description: State or province code associated with the physical address in the specified country. The companyStateProvinceCode for US must be a standard 2-characters code.
          maxLength: 2
        companyPostalCode:
          type: string
          description: Postal code associated with the primary address of token requestor, such as a ZIP code.
          maxLength: 7
        companyCountryCode:
          type: string
          description: ISO-3166-1 alpha-2 standard country associated with the token requestor’s primary address.
          example: MX
          maxLength: 2
        companyPhone:
          type: string
          description: Token requestor’s primary phone number.
          maxLength: 16
        primaryContactFirstName:
          type: string
          description: First name of token requestor’s primary contact person.
          maxLength: 256
        primaryContactLastName:
          type: string
          description: 'Surname of token requestor’s primary contact person.<br><br>**Allowed characters**:<br>Alphabetic or the following characters: spaces, ‘ (single quote), ` (back tick), ~ (tilde), “ (double quote), . (period), and – (hyphen)

            '
          maxLength: 256
        primaryContactEmail:
          type: string
          description: Email address of token requestor’s primary contact.
          example: ventas@pepitospizza.com
          maxLength: 256
        relationships:
          type: object
          description: 'Relationship to the token requestor being onboarded, which is by externalClientId. If not specified, Visa creates the externalClientId for you, which is available in the response.<br><br>**Allowed characters**:<br>An array of Relationships structures.

            '
          properties:
            externalClientId:
              type: string
              description: 'The relationship ID for the entity being onboarded. This is the relationship ID to use when calling TSP APIs.

                '
              maxLength: 100
        acquirerIdentifiers:
          type: object
          description: Acquirer and merchant identifiers
          required:
          - acquirerId
          - acquirerMerchantId
          properties:
            acquirerId:
              type: string
              description: 'Acquirer Id

                '
              example: 66978068
              maxLength: 15
            acquirerMerchantId:
              type: string
              description: 'Unique identifier relation Acquirer and Merchant Id.<br><br>This value is mandatory in future request.

                '
              example: 9655936598
              maxLength: 25
        tokenizationConfiguration:
          type: object
          required:
          - tokenizationProfiles
          - tokenRequestorId
          properties:
            channelSecurityContext:
              type: string
              description: 'Channel security context; default is shared secret.

                '
              maxLength: 100
            tokenizationProfiles:
              type: object
              description: 'List of profiles

                '
              required:
              - profileName
              - applicationId
              properties:
                profileName:
                  type: string
                  description: 'Profile name in tokenization services

                    '
                  maxLength: 50
                applicationId:
                  type: string
                  description: 'Unique Identifier same as the wallet provider

                    '
                  maxLength: 36
            tokenRequestorId:
              type: string
              description: 'Identification to use for payments

                '
              maxLength: 20
    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
    RSCreateMerchant:
      type: object
      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
        data:
          type: object
          properties:
            id:
              type: string
              description: 'VISA''s identification response Id

                '
            acquirerIdentifiers:
              type: object
              required:
              - acquirerId
              - acquirerMerchantId
              properties:
                acquirerId:
                  type: string
                  description: 'Acquirer ID

                    '
                acquirerMerchantId:
                  type: string
                  description: 'Unique identifier relation Acquirer and Merchant Id

                    '
            tokenizationConfiguration:
              type: object
              required:
              - tokenizationProfiles
              - tokenRequestorId
              properties:
                channelSecurityContext:
                  type: string
                  description: 'Channel security context; default is shared secret.

                    '
                  maxLength: 100
                tokenizationProfiles:
                  type: object
                  description: 'List of profiles

                    '
                  required:
                  - profileName
                  - applicationId
                  properties:
                    profileName:
                      type: string
                      description: 'Profile name in tokenization services

                        '
                      maxLength: 50
                    applicationId:
                      type: string
                      description: 'Unique Identifier same as the wallet provider

                        '
                      maxLength: 36
                tokenRequestorId:
                  type: string
                  description: 'Identification to use for payments

                    '
                  maxLength: 20
            qrData:
              type: string
              description: 'Raw entire QR code data, from scanning QR. Base64 encoded

                '
    RSCreateMerchant400:
      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
  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'
    NoResultsFound:
      value:
        code: 200.22.364
        message: No results found
        datetime: '2020-01-03T16:05:56.517Z'
        data:
          status: 401
          code: 9159
          severity: ERROR
          message: TokenValidationFailed
          info: ''
    CreateMerchantOk:
      value:
        code: 200.22.000
        message: Process Ok
        datetime: '2020-01-03T16:05:56.517Z'
        data:
          id: 8e9ed12e-e4ba-4ad2-ac9d-2bcb1c8fc18a
          acquirerIdentifiers:
            acquirerId: 66978068
            acquirerMerchantId: 9655936598
          tokenizationConfiguration:
            channelSecurityContext: SHARED_SECRET
            tokenizationProfiles:
              profileName: Test1
              applicationId: Test1
            tokenRequestorId: 40000000057
          qrData: iVB...YII=
    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'
  responses:
    RSCreateMerchant:
      description: Process Ok
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSCreateMerchant'
          examples:
            Process Ok:
              $ref: '#/components/examples/CreateMerchantOk'
            No Results Found:
              $ref: '#/components/examples/NoResultsFound'
    RSCreateMerchant400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RSCreateMerchant400'
          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'
  requestBodies:
    RQCreateMerchant:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RQCreateMerchant'
      required: true
  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: {}