openapi: 3.0.3
info:
  title: 'pensopay merchant api'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'http://merchant.pensopay.com'
paths:
  /api/merchants:
    post:
      summary: 'Create a merchant'
      operationId: createAMerchant
      description: "If a webhook **is not** provided, the request will take up to 10 seconds.\n\nIf a webhook **is** provided, the request will use the webhook to inform\nwhen the merchant creation process is done."
      parameters: []
      responses:
        201:
          description: 'Successful request without a webhook'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    uuid: 3af2082e-e6c6-4a53-be24-2741eff37a3d
                    reference_id: 398475
                    state: live_awaiting_approval
                    country: DK
                    cvr: '36410876'
                    contact_name: 'John Doe'
                    contact_email: johndoe@pensopay.com
                    url: 'https://pensopay.com'
                    company_information:
                      cvr: 36410876
                      city: Vejle
                      name: 'PENSOPAY A/S'
                      email: contact@pensopay.com
                      phone: '77344388'
                      address: 'Roms Hule 4, 3. sal'
                      zipcode: 7100
                    created_at: '2022-04-20T13:37:00.000000Z'
                    credentials:
                      pensopay:
                        token: 9037c9b0b8690aa148b2d28b9d2a949e8a664055570df4c5b964c503a2047422
                        account_id: 112233
                        private_key: b9f11f2b2cd3feb6b682322890dc7d9946a20d118a84607451291c298bd60f78
                    addons:
                      mobilepay: true
                properties:
                  data:
                    type: object
                    properties:
                      uuid:
                        type: string
                        example: 3af2082e-e6c6-4a53-be24-2741eff37a3d
                      reference_id:
                        type: integer
                        example: 398475
                      state:
                        type: string
                        example: live_awaiting_approval
                      country:
                        type: string
                        example: DK
                      cvr:
                        type: string
                        example: '36410876'
                      contact_name:
                        type: string
                        example: 'John Doe'
                      contact_email:
                        type: string
                        example: johndoe@pensopay.com
                      url:
                        type: string
                        example: 'https://pensopay.com'
                      company_information:
                        type: object
                        properties:
                          cvr:
                            type: integer
                            example: 36410876
                          city:
                            type: string
                            example: Vejle
                          name:
                            type: string
                            example: 'PENSOPAY A/S'
                          email:
                            type: string
                            example: contact@pensopay.com
                          phone:
                            type: string
                            example: '77344388'
                          address:
                            type: string
                            example: 'Roms Hule 4, 3. sal'
                          zipcode:
                            type: integer
                            example: 7100
                      created_at:
                        type: string
                        example: '2022-04-20T13:37:00.000000Z'
                      credentials:
                        type: object
                        properties:
                          pensopay:
                            type: object
                            properties:
                              token:
                                type: string
                                example: 9037c9b0b8690aa148b2d28b9d2a949e8a664055570df4c5b964c503a2047422
                              account_id:
                                type: integer
                                example: 112233
                              private_key:
                                type: string
                                example: b9f11f2b2cd3feb6b682322890dc7d9946a20d118a84607451291c298bd60f78
                      addons:
                        type: object
                        properties:
                          mobilepay:
                            type: boolean
                            example: true
        401:
          description: 'Unauthorized (missing or invalid API token)'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Insufficient API token permissions'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'This action is unauthorized.'
                properties:
                  message:
                    type: string
                    example: 'This action is unauthorized.'
        422:
          description: 'Validation error of input'
          content:
            text/plain:
              schema:
                type: string
                example: "{\n \"message\": \"The given data was invalid.\",\n \"errors\": {\n     \"contact_name\": [\n         \"The name field is required.\"\n     ],\n     \"contact_email\": [\n         \"The email field is required.\"\n     ],\n     \"iban\": [\n         \"The iban field is required.\"\n     ],\n     \"cvr\": [\n         \"The cvr field is invalid.\"\n     ]\n}"
        500:
          description: 'Internal server error'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'An internal error occured. Pensopay has been notified.'
                properties:
                  message:
                    type: string
                    example: 'An internal error occured. Pensopay has been notified.'
      tags:
        - Merchants
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reference_id:
                  type: string
                  description: 'Internal reference id you can choose to use.'
                  example: '398475'
                  nullable: false
                contact_name:
                  type: string
                  description: "The name of the business' contact."
                  example: 'John Doe'
                  nullable: false
                contact_email:
                  type: string
                  description: "The email of the business' contact."
                  example: johndoe@example.com
                  nullable: false
                company_phone:
                  type: string
                  description: 'The phone number for the business.'
                  example: '77344388'
                  nullable: false
                business_model_description:
                  type: string
                  description: 'A short business model description for the merchant.'
                  example: hic
                  nullable: false
                country:
                  type: string
                  description: 'The country for the business is optional, will default to "DK" if not provided. If set to something else than "DK", the information field is required.'
                  example: DK
                  nullable: false
                cvr:
                  type: string
                  description: "The business' VAT number."
                  example: '36410876'
                  nullable: false
                iban:
                  type: string
                  description: "The business' iban number."
                  example: DK9230055205310542
                  nullable: false
                company_information:
                  type: array
                  description: 'Optional company information is REQUIRED if country is not set to "DK"'
                  example:
                    - sapiente
                  items:
                    type: string
                url:
                  type: string
                  description: 'The URL for the business is optional.'
                  example: 'https://pensopay.com'
                  nullable: true
                webhook:
                  type: string
                  description: "URL to send merchant's private keys and tokens to."
                  example: 'https://example.com/webhooks'
                  nullable: false
                addons:
                  type: array
                  description: 'Specify which addons should be enabled on creation'
                  example:
                    - asperiores
                  items:
                    type: string
              required:
                - contact_name
                - contact_email
                - business_model_description
                - cvr
                - iban
                - webhook
    get:
      summary: 'List merchants'
      operationId: listMerchants
      description: 'List all merchants created by authenticated user'
      parameters:
        -
          in: query
          name: page
          description: 'Which page to display. Must be at least 1.'
          example: 41
          required: false
          schema:
            type: integer
            description: 'Which page to display. Must be at least 1.'
            example: 41
            nullable: false
        -
          in: query
          name: per_page
          description: 'How many items to display per page. Must be at least 1. Must not be greater than 50.'
          example: 5
          required: false
          schema:
            type: integer
            description: 'How many items to display per page. Must be at least 1. Must not be greater than 50.'
            example: 5
            nullable: false
      responses:
        200:
          description: 'Collection of merchants created'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      uuid: 3af2082e-e6c6-4a53-be24-2741eff37a0d
                      reference_id: 398475
                      state: live_awaiting_approval
                      cvr: '36410876'
                      contact_name: 'John Doe'
                      contact_email: johndoe@pensopay.com
                      url: 'https://pensopay.com'
                      company_information:
                        cvr: 36410876
                        city: Vejle
                        name: 'PENSOPAY A/S'
                        email: contact@pensopay.com
                        phone: '77344388'
                        address: 'Roms Hule 4, 3. sal'
                        zipcode: 7100
                      created_at: '2022-04-20T13:37:00.000000Z'
                      credentials:
                        pensopay:
                          token: 9837c9b0b8690aa148b2d28b9d2a949e8a664055570df4c5b964c503a1047422
                          account_id: 112233
                          private_key: b9f10f2b2cd3feb6b682322890cc7d9946a20d118a84607451291c298bd60f78
                      addons:
                        mobilepay: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        uuid: 3af2082e-e6c6-4a53-be24-2741eff37a0d
                        reference_id: 398475
                        state: live_awaiting_approval
                        cvr: '36410876'
                        contact_name: 'John Doe'
                        contact_email: johndoe@pensopay.com
                        url: 'https://pensopay.com'
                        company_information:
                          cvr: 36410876
                          city: Vejle
                          name: 'PENSOPAY A/S'
                          email: contact@pensopay.com
                          phone: '77344388'
                          address: 'Roms Hule 4, 3. sal'
                          zipcode: 7100
                        created_at: '2022-04-20T13:37:00.000000Z'
                        credentials:
                          pensopay:
                            token: 9837c9b0b8690aa148b2d28b9d2a949e8a664055570df4c5b964c503a1047422
                            account_id: 112233
                            private_key: b9f10f2b2cd3feb6b682322890cc7d9946a20d118a84607451291c298bd60f78
                        addons:
                          mobilepay: true
                    items:
                      type: object
                      properties:
                        uuid:
                          type: string
                          example: 3af2082e-e6c6-4a53-be24-2741eff37a0d
                        reference_id:
                          type: integer
                          example: 398475
                        state:
                          type: string
                          example: live_awaiting_approval
                        cvr:
                          type: string
                          example: '36410876'
                        contact_name:
                          type: string
                          example: 'John Doe'
                        contact_email:
                          type: string
                          example: johndoe@pensopay.com
                        url:
                          type: string
                          example: 'https://pensopay.com'
                        company_information:
                          type: object
                          properties:
                            cvr:
                              type: integer
                              example: 36410876
                            city:
                              type: string
                              example: Vejle
                            name:
                              type: string
                              example: 'PENSOPAY A/S'
                            email:
                              type: string
                              example: contact@pensopay.com
                            phone:
                              type: string
                              example: '77344388'
                            address:
                              type: string
                              example: 'Roms Hule 4, 3. sal'
                            zipcode:
                              type: integer
                              example: 7100
                        created_at:
                          type: string
                          example: '2022-04-20T13:37:00.000000Z'
                        credentials:
                          type: object
                          properties:
                            pensopay:
                              type: object
                              properties:
                                token:
                                  type: string
                                  example: 9837c9b0b8690aa148b2d28b9d2a949e8a664055570df4c5b964c503a1047422
                                account_id:
                                  type: integer
                                  example: 112233
                                private_key:
                                  type: string
                                  example: b9f10f2b2cd3feb6b682322890cc7d9946a20d118a84607451291c298bd60f78
                        addons:
                          type: object
                          properties:
                            mobilepay:
                              type: boolean
                              example: true
      tags:
        - Merchants
  '/api/merchants/{merchant_id}':
    get:
      summary: 'Show single merchant'
      operationId: showSingleMerchant
      description: ''
      parameters: []
      responses:
        200:
          description: Merchant
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    uuid: 3af2082e-e6c6-4a53-be24-2741eff37a0d
                    reference_id: 398475
                    state: live_awaiting_approval
                    cvr: '36410876'
                    contact_name: 'John Doe'
                    contact_email: johndoe@pensopay.com
                    url: 'https://pensopay.com'
                    company_information:
                      cvr: 36410876
                      city: Vejle
                      name: 'PENSOPAY A/S'
                      email: contact@pensopay.com
                      phone: '77344388'
                      address: 'Roms Hule 4, 3. sal'
                      zipcode: 7100
                    created_at: '2022-04-20T13:37:00.000000Z'
                    credentials:
                      pensopay:
                        token: 9837c9b0b8690aa148b2d28b9d2a949e8a664055570df4c5b964c503a1047422
                        account_id: 112233
                        private_key: b9f10f2b2cd3feb6b682322890cc7d9946a20d118a84607451291c298bd60f78
                    addons:
                      mobilepay: true
                properties:
                  data:
                    type: object
                    properties:
                      uuid:
                        type: string
                        example: 3af2082e-e6c6-4a53-be24-2741eff37a0d
                      reference_id:
                        type: integer
                        example: 398475
                      state:
                        type: string
                        example: live_awaiting_approval
                      cvr:
                        type: string
                        example: '36410876'
                      contact_name:
                        type: string
                        example: 'John Doe'
                      contact_email:
                        type: string
                        example: johndoe@pensopay.com
                      url:
                        type: string
                        example: 'https://pensopay.com'
                      company_information:
                        type: object
                        properties:
                          cvr:
                            type: integer
                            example: 36410876
                          city:
                            type: string
                            example: Vejle
                          name:
                            type: string
                            example: 'PENSOPAY A/S'
                          email:
                            type: string
                            example: contact@pensopay.com
                          phone:
                            type: string
                            example: '77344388'
                          address:
                            type: string
                            example: 'Roms Hule 4, 3. sal'
                          zipcode:
                            type: integer
                            example: 7100
                      created_at:
                        type: string
                        example: '2022-04-20T13:37:00.000000Z'
                      credentials:
                        type: object
                        properties:
                          pensopay:
                            type: object
                            properties:
                              token:
                                type: string
                                example: 9837c9b0b8690aa148b2d28b9d2a949e8a664055570df4c5b964c503a1047422
                              account_id:
                                type: integer
                                example: 112233
                              private_key:
                                type: string
                                example: b9f10f2b2cd3feb6b682322890cc7d9946a20d118a84607451291c298bd60f78
                      addons:
                        type: object
                        properties:
                          mobilepay:
                            type: boolean
                            example: true
      tags:
        - Merchants
    delete:
      summary: 'Request merchant off-boarding'
      operationId: requestMerchantOffBoarding
      description: ''
      parameters: []
      responses:
        204:
          description: 'Successful request'
        401:
          description: 'Unauthorized (missing or invalid API token)'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Insufficient API token permissions'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'This action is unauthorized.'
                properties:
                  message:
                    type: string
                    example: 'This action is unauthorized.'
        500:
          description: 'Internal server error'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'An internal error occured. Pensopay has been notified.'
                properties:
                  message:
                    type: string
                    example: 'An internal error occured. Pensopay has been notified.'
      tags:
        - Merchants
    patch:
      summary: 'Update a merchant'
      operationId: updateAMerchant
      description: 'Partially update a merchant.'
      parameters: []
      responses:
        200:
          description: 'Update merchant'
          content:
            text/plain:
              schema:
                type: string
                example: "{\n  \"data\": {\n         \"uuid\": \"3af2082e-e6c6-4a53-be24-2741eff37a0d\",\n         \"reference_id\": 398475,\n         \"state\": \"live_awaiting_approval\",\n         \"cvr\": \"36410876\",\n         \"contact_name\": \"John Doe\",\n         \"contact_email\": \"johndoe@pensopay.com\",\n         \"url\": \"https://pensopay.com\",\n         \"company_information\": {\n             \"cvr\": 36410876,\n             \"city\": \"Vejle\",\n             \"name\": \"PENSOPAY A/S\",\n             \"email\": \"contact@pensopay.com\",\n             \"phone\": \"77344388\",\n             \"address\": \"Roms Hule 4, 3. sal\",\n             \"zipcode\": 7100\n         },\n         \"created_at\": \"2022-04-20T13:37:00.000000Z\",\n         \"credentials\": {\n             \"pensopay\": {\n                 \"token\": \"9837c9b0b8690aa148b2d28b9d2a949e8a664055570df4c5b964c503a1047422\",\n                 \"account_id\": 112233,\n                 \"private_key\": \"b9f10f2b2cd3feb6b682322890cc7d9946a20d118a84607451291c298bd60f78\"\n              }\n         },\n        \"addons\": {\n            \"mobilepay\": true\n        }\n }"
      tags:
        - Merchants
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                addons:
                  type: array
                  description: ''
                  example: null
                  items:
                    type: string
    parameters:
      -
        in: path
        name: merchant_id
        description: "The merchant's VAT or UUID"
        example: culpa
        required: true
        schema:
          type: string
tags:
  -
    name: Merchants
    description: "\nEndpoints for managing merchants.\n\n**Changes**\n- 2024-06-17: Support for non-DK countries added, requires input in `company_information` array-field.\n- 2024-06-17: The `information` field has been renamed to `company_information`."
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'You can retrieve your token by visiting going to <a href="/user/api-tokens" target="_blank">this form</a>.'
security:
  -
    default: []
