swagger: '2.0'
info:
  title: PSP Merchant API
  version: 1.3.0
  description: >
    The PSP Merchant API allows PSPs to onboard and control their merchants. See
    the [PSP Merchant API
    guide](/docs/APIs/psp-merchant-api/psp-merchant-api-guide/) for concepts and
    usage guidance.
  contact:
    name: Vipps MobilePay AS
    email: developer@vippsmobilepay.com
    url: https://developer.vippsmobilepay.com
tags:
  - name: Merchant
    description: Endpoints and operations to handle merchant sales units.
host: api.vipps.no
basePath: /merchant-management/psp
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json;charset=UTF-8
paths:
  /v1/merchants:
    parameters:
      - $ref: '#/parameters/auth'
      - $ref: '#/parameters/apimKey'
    get:
      operationId: getMerchants
      summary: Get all merchants
      description: This returns an array of all the merchant sales units you have created.
      tags:
        - Merchant
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/GetMerchantsResponse'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '405':
          $ref: '#/responses/405'
        '500':
          $ref: '#/responses/500'
    post:
      operationId: addMerchant
      summary: Create a new merchant
      description: Create a new merchant sales unit.
      tags:
        - Merchant
      parameters:
        - $ref: '#/parameters/idempotency'
        - name: merchant
          in: body
          description: merchant
          required: true
          schema:
            $ref: '#/definitions/CreateMerchantRequest'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/CreateMerchantResponse'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '405':
          $ref: '#/responses/405'
        '409':
          $ref: '#/responses/409'
        '415':
          $ref: '#/responses/415'
        '500':
          $ref: '#/responses/500'
  /v1/merchants/{merchantSerialNumber}:
    parameters:
      - $ref: '#/parameters/auth'
      - $ref: '#/parameters/apimKey'
      - $ref: '#/parameters/merchantSerialNumber'
    get:
      operationId: getMerchant
      summary: Get merchant by Id
      description: Get details for a merchant sales unit.
      tags:
        - Merchant
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/Merchant'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '405':
          $ref: '#/responses/405'
        '500':
          $ref: '#/responses/500'
    patch:
      operationId: patchMerchant
      summary: Update a merchant
      description: Update limited details for a merchant sales unit.
      tags:
        - Merchant
      parameters:
        - name: merchant
          in: body
          description: merchant
          required: true
          schema:
            $ref: '#/definitions/UpdateMerchantRequest'
      responses:
        '200':
          description: OK
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '405':
          $ref: '#/responses/405'
        '415':
          $ref: '#/responses/415'
        '500':
          $ref: '#/responses/500'
responses:
  '400':
    description: Invalid request, check request parameters
    schema:
      $ref: '#/definitions/Error'
  '401':
    description: Unauthorized
  '403':
    description: Forbidden
    schema:
      $ref: '#/definitions/Error'
  '404':
    description: Item does not exist
    schema:
      $ref: '#/definitions/Error'
  '405':
    description: Request method not supported
    schema:
      $ref: '#/definitions/Error'
  '409':
    description: Idempotent conflict
    schema:
      $ref: '#/definitions/Error'
  '415':
    description: Unsupported media type
    schema:
      $ref: '#/definitions/Error'
  '500':
    description: Internal server error
    schema:
      $ref: '#/definitions/Error'
parameters:
  merchantSerialNumber:
    name: merchantSerialNumber
    type: string
    in: path
    required: true
    description: Unique ID for the merchant's sales unit.
    minLength: 5
    maxLength: 10
    pattern: ^\d{5,10}$
  auth:
    name: Authorization
    in: header
    required: true
    description: >-
      The access token is a base64-encoded string that is required for all API
      calls. It is a JWT (JSON Web Token). The access token is fetched from the
      [`POST:/accesstoken/get`](/api/access-token#tag/Authorization-Service/operation/fetchAuthorizationTokenUsingPost)
      endpoint. It is valid for 1 hour in the test environment and 24 hours in
      the production environment.
    type: string
  apimKey:
    name: Ocp-Apim-Subscription-Key
    in: header
    description: >-
      This is your PSP subscription key, used to create and manage payments for
      all your merchants. Keep it secret.
    required: true
    type: string
  idempotency:
    name: Idempotency-Key
    in: header
    description: Unique key for idempotent operation
    required: true
    type: string
definitions:
  Merchant:
    description: Details of a merchant
    required:
      - merchantSerialNumber
      - name
      - address
      - status
      - organizationNumber
      - companyName
      - companyEmail
    properties:
      organizationNumber:
        type: string
        minLength: 1
        maxLength: 50
        x-order: 1
        example: '123456789'
        description: >-
          Organization number of the merchant, in the correct format for the
          organization's country. For Norway: The orgno must be 9 digits without
          spaces, the merchant must be active in the [Norwegian business
          registry](https://www.brreg.no) and the orgno must be for the main
          entity ("hovedenhet"), not a sub entity ("underenhet"). For other
          countries: The orgno, address, etc is validated as much as practically
          possible.
      companyName:
        type: string
        x-order: 2
        example: Nordic Goods AS
        description: >-
          The legal name of the organization. This may be different from `name`,
          which is displayed in the Vipps / MobilePay app.
      companyEmail:
        type: string
        x-isnullable: true
        x-order: 3
        example: user@example.com
        description: The merchant's email address
      merchantSerialNumber:
        type: string
        description: Unique ID for the merchant's sales unit
        minLength: 5
        maxLength: 10
        pattern: ^\d{5,10}$
        x-order: 4
        example: '123456'
      name:
        type: string
        description: >-
          The merchant's name. This name will be displayed in the Vipps /
          MobilePay app. This may be different from the legal name in
          `companyName`.
        x-order: 5
        example: Example AS
      status:
        type: string
        description: The merchant's status with Vipps MobilePay
        enum:
          - ACTIVE
          - DEACTIVATED
          - PENDING
        default: PENDING
        x-order: 7
      email:
        type: string
        description: Contact email for the merchant. Can be the same as `companyEmail`.
        format: email
        x-isnullable: true
        x-order: 10
        example: user@example.com
      website:
        type: string
        description: The URL for the merchant's website
        format: uri
        x-isnullable: true
        x-order: 11
        example: https://example.com
      createdAt:
        type: string
        description: Date-time when the merchant was signed up
        format: date-time
        x-isnullable: true
        x-order: 12
        example: '2019-01-01T00:00:00Z'
      updatedAt:
        type: string
        description: Date-time when the merchant was last updated
        format: date-time
        x-isnullable: true
        x-order: 13
        example: '2019-01-01T00:00:00Z'
      address:
        description: The merchant's address
        $ref: '#/definitions/Address'
        x-order: null
      marketPlaceId:
        type: string
        description: >-
          ID of the merchant's marketplace. This is related to invoicing
          multiple merchants in the same price tier and requires special
          contract to take effect.
        pattern: ^[a-zA-Z0-9-]{0,64}$
        x-isnullable: true
  GetMerchantsResponse:
    type: object
    description: Response of successful getMerchants operation
    required:
      - merchants
    properties:
      merchants:
        type: array
        description: List of Merchants
        items:
          $ref: '#/definitions/Merchant'
  CreateMerchantRequest:
    description: Request for addMerchant operation
    properties:
      organizationNumber:
        type: string
        minLength: 1
        maxLength: 50
        x-order: 1
        example: '123456789'
        description: >-
          Organization number of the merchant, in the correct format for the
          organization's country. For Norway: The orgno must be 9 digits without
          spaces, the merchant must be active in the [Norwegian business
          registry](https://www.brreg.no) and the orgno must be for the main
          entity ("hovedenhet"), not a sub entity ("underenhet"). For other
          countries: The orgno, address, etc is validated as much as practically
          possible.
      name:
        type: string
        minLength: 1
        maxLength: 200
        description: >-
          The merchant's name. This name will be displayed in the Vipps /
          MobilePay app. This may be different from the legal name in
          `companyName`.
        example: Example AS
      mccCode:
        type: string
        description: >-
          Four-digit number listed in ISO 18245 for retail financial services,
          used to classify a business by the types of goods or services it
          provides
        minLength: 4
        maxLength: 4
        pattern: ^\d{4}$
        example: '5411'
      marketPlaceId:
        type: string
        description: >-
          ID of the merchant's marketplace. This is related to invoicing
          multiple merchants in the same price tier and requires special
          contract to take effect
        pattern: ^[a-zA-Z0-9-]{0,64}$
      logo:
        type: string
        description: >-
          Base64 encoded string of the logo of the merchant. The logo will be
          displayed in the Vipps / MobilePay app, both when paying and on
          receipts. The logo must be in PNG (Portable Network Graphics) format.
          Square images are recommended. The longest side can not be more than
          1000 pixels. The minimum size is 100 x 100 pixels.
        example: VGhlIGltYWdlIGdvZXMgaGVyZQ== (truncated)
      email:
        type: string
        description: Contact email for the merchant. Can be same as companyEmail
        format: email
        pattern: >-
          ^[a-zA-Z0-9.!#$%&*+\/=?^_{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
        maxLength: 255
        example: user@example.com
      website:
        type: string
        description: The URL for the merchant's website
        pattern: >-
          ^[(http(s)?):\/\/(www\.)?a-zA-Z0-9@:\-%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)*$
        format: uri
        maxLength: 255
        example: https://example.com
      address:
        description: The merchant's address
        $ref: '#/definitions/Address'
      companyName:
        type: string
        minLength: 1
        maxLength: 255
        example: Nordic Goods AS
        description: >-
          The legal name of the organization. This may be different from `name`,
          which is displayed in the Vipps / MobilePay app.
      termsOfServiceAccepted:
        type: boolean
        x-nullable: true
        example: true
        description: >-
          Has the Vipps MobilePay terms of service for GDPR and Privacy been
          accepted by the merchant. Needed for login, userinfo, and express
          features.
      companyEmail:
        type: string
        format: email
        pattern: >-
          ^[a-zA-Z0-9.!#$%&*+\/=?^_{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
        maxLength: 255
        example: user@example.com
        description: The merchant's email address
    required:
      - name
      - address
      - logo
      - organizationNumber
      - companyName
      - companyEmail
      - mccCode
  UpdateMerchantRequest:
    description: >-
      Request for patchMerchant operation. At least one of the properties is
      required
    properties:
      deactivate:
        type: boolean
        description: >-
          Set as true in order to deactivate a merchant. Already deactivated
          merchant cannot be activated or updated through the API
      name:
        type: string
        maxLength: 200
        description: >-
          The merchant's name. This name will be displayed in the Vipps /
          MobilePay app. This may be different from the legal name in
          `companyName`.
        example: Example AS
      companyName:
        type: string
        maxLength: 255
        example: Nordic Goods AS
        description: The legal name of the organization.
      termsOfServiceAccepted:
        type: boolean
        x-nullable: true
        example: true
        description: Has the terms of service been accepted by the merchant.
      mccCode:
        type: string
        description: >-
          Four-digit number listed in ISO 18245 for retail financial services,
          used to classify a business by the types of goods or services it
          provides
        minLength: 4
        maxLength: 4
        pattern: ^\d{4}$
        example: '5411'
      logo:
        type: string
        description: >-
          Base64 encoded string of the logo of the merchant. The logo will be
          displayed in the Vipps / MobilePay app, both when paying and on
          receipts. The logo must be in PNG (Portable Network Graphics) format.
          Square images are recommended. The longest side can not be more than
          1000 pixels. The minimum size is 100 x 100 pixels.
      email:
        type: string
        description: Contact email for the merchant. Can be same as companyEmail
        format: email
        pattern: >-
          ^[a-zA-Z0-9.!#$%&*+\/=?^_{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
        maxLength: 255
        example: user@example.com
      website:
        type: string
        description: The URL for the merchant's website
        format: uri
        pattern: >-
          ^[(http(s)?):\/\/(www\.)?a-zA-Z0-9@:\-%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#?&//=]*)*$
        maxLength: 255
        example: https://example.com
      address:
        description: The merchant's address
        $ref: '#/definitions/Address'
      marketPlaceId:
        type: string
        description: >-
          ID of the merchant's marketplace. This is related to invoicing
          multiple merchants in the same price tier and requires special
          contract to take effect
        pattern: ^[a-zA-Z0-9-]{0,64}$
  CreateMerchantResponse:
    description: Response of successful addMerchant operation
    required:
      - merchantSerialNumber
    properties:
      merchantSerialNumber:
        type: string
        description: Unique ID for the merchant's sales unit
        minLength: 5
        maxLength: 10
        pattern: ^\d{5,10}$
  Address:
    type: object
    description: The merchant's address
    required:
      - addressLine1
      - city
      - country
      - postCode
    properties:
      addressLine1:
        type: string
        description: Address Line 1
        example: Robert Levins gate 5
        maxLength: 255
        x-order: 1
      addressLine2:
        type: string
        description: Address Line 2
        example: 'Att: Rune Garborg'
        maxLength: 255
        x-isnullable: true
        x-order: 2
      city:
        type: string
        description: City
        example: Oslo
        maxLength: 255
        x-order: 3
      postCode:
        type: string
        description: Postcode
        minLength: 0
        maxLength: 10
        pattern: ^[A-Za-z0-9 ]+$
        example: '0154'
        x-order: 4
      country:
        type: string
        description: Two letter country code. All ISO 3166 country codes are supported.
        pattern: ^\w{2}$
        minLength: 2
        maxLength: 2
        example: 'NO'
        default: 'NO'
        x-order: 5
  Error:
    type: object
    description: Problem details of HTTP APIs based on RFC 7807
    required:
      - status
      - title
      - detail
      - instance
    properties:
      type:
        type: string
        description: |
          "A URI reference that identifies the problem type"
        example: https://example.net/validation-error
        x-order: 1
      title:
        type: string
        description: |
          "A short, human-readable summary of the problem type"
        example: Postcode validation error
        x-order: 2
      status:
        type: number
        description: >
          "The HTTP status code generated by the origin server for this
          occurrence of the problem"
        example: 400
        x-order: 3
      detail:
        type: string
        description: >
          "A human-readable explanation specific to this occurrence of the
          problem.

          The detail member, if present, ought to focus on helping the client
          correct the problem,

          rather than giving debugging information."
        example: Postcode must be four digits
        x-order: 4
      instance:
        type: string
        description: >
          "A URI reference that identifies the specific occurrence of the
          problem"
        example: https://example.net/validation-error/postcode
        x-order: 5
