openapi: 3.0.3

servers:
- url: https://dev.api.payment25.com/api
  description: Development server
- url: https://api.payment25.com/api
  description: Production server

info:
  title: GoMeddo Payments
  contact: 
    name: GoMeddo Support
    email: info@gomeddo.com
  version: '0.1'
  description: >
    This api is the GoMeddo Payments API developed by GoMeddo. By utilizing this project you can have a single endpoint for 
    multiple payment service provider implemenations. his will enable you to implement a single PSP into your product for 
    either payment links or full fledged API payments without having to manage multiple PSP integrations.

tags: 
  - name: 'V1'
  - name: 'V1 - Admin'

    
security:
  - BearerAuth: []

paths:
  '/v1/accounts':
    get:
      operationId: getAccounts
      summary: GoMeddo Payments Accounts
      description: This will retrieve all registered GoMeddo Payment accounts that your account has access to. 
      tags:
        - V1
      responses:
        '200':
          $ref: '#/components/responses/GetAccountsResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
    post:
      operationId: postAccounts
      summary: Create GoMeddo Payment Account
      description: This will create a new GoMeddo Payment account. This functionality is limited to admin accounts.
      tags:
        - V1 - Admin
      requestBody:
        description: Optional description in *Markdown*
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        '201':
          $ref: '#/components/responses/GetAccountResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
  '/v1/account/{accountId}':
    get:
      operationId: getAccount
      summary: GoMeddo Payment Account Details
      description: This will retrieve a specific GoMeddo Payment account. 
      parameters:
      - name: accountId
        in: path
        required: true
        description: the account identifier, as accountId.
        schema:
          type: string
          format: uuid
      tags:
        - V1
      responses:
        '200':
          $ref: '#/components/responses/GetAccountResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'        
  '/v1/account/{accountId}/providers':
    get:
      operationId: getPaymentProviders
      summary: Payment Providers
      description: This will retrieve all payment service provides for a specific GoMeddo Payment account. 
      tags:
        - V1
      parameters:
        - name: accountId
          in: path
          required: true
          description: the account identifier, as accountId.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          $ref: '#/components/responses/GetPaymentProviderResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
    post:
      operationId: createPaymentProvider
      summary: Create Payment Provider
      description: This will register a new payment service provider under the account. The credentials are stored in AWS Secrets Manager and can only be accessed by GoMeddo Payments. 
      tags:
        - V1
      parameters:
        - name: accountId
          in: path
          required: true
          description: the account identifier, as accountId.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/SaferPayPaymentServiceProvider'
                - $ref: '#/components/schemas/AdyenPaymentServiceProvider'
                - $ref: '#/components/schemas/StripePaymentServiceProvider'
            examples:
              SaferPay:
                $ref: '#/components/examples/SaferPayCreate'
              Adyen:
                $ref: '#/components/examples/AdyenCreate'
              Stripe:
                $ref: '#/components/examples/StripeCreate'
      responses:
        '201':
          $ref: '#/components/responses/GetPaymentProviderResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
  '/v1/account/{accountId}/provider/{providerId}':
    get:
      operationId: getPaymentProvider
      summary: Payment Provider Details
      description: This will retrieve a specific payment service provider. 
      parameters:
      - name: accountId
        in: path
        required: true
        description: the account identifier, as accountId.
        schema:
          type: string
          format: uuid
      - name: providerId
        in: path
        required: true
        description: the provider identifier, as providerId.
        schema:
          type: string
          format: uuid
      tags:
        - V1
      responses:
        '200':
          $ref: '#/components/responses/GetPaymentProviderResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'        
  '/v1/account/{accountId}/provider/{providerId}/webhooks':
    get:
      operationId: getWebhooks
      summary: Provider Webhooks
      description: This will retrieve all webhooks registered for a payment service provider. 
      tags:
        - V1
      parameters:
        - name: accountId
          in: path
          required: true
          description: the account identifier, as accountId.
          schema:
            type: string
            format: uuid
        - name: providerId
          in: path
          required: true
          description: the payment service provider identifier, as providerId.
          schema:
            type: string
            format: uuid       
      responses:
        '200':
          $ref: '#/components/responses/GetWebhooksResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
    post:
      operationId: createWebhook
      summary: Create Provider Webhook
      description: This will create a new webhook under the payment service provider.
      tags:
        - V1
      parameters:
        - name: accountId
          in: path
          required: true
          description: the account identifier, as accountId.
          schema:
            type: string
            format: uuid
        - name: providerId
          in: path
          required: true
          description: the payment service provider identifier, as providerId.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '201':
          $ref: '#/components/responses/GetWebhookResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
  '/v1/account/{accountId}/provider/{providerId}/webhook/{webhookId}':
    get:
      operationId: getWebhook
      summary: Provider Webhook Details
      description: This will retrieve a specific webhook. 
      parameters:
      - name: accountId
        in: path
        required: true
        description: the account identifier, as accountId.
        schema:
          type: string
          format: uuid
      - name: providerId
        in: path
        required: true
        description: the provider identifier, as providerId.
        schema:
          type: string
          format: uuid
      - name: webhookId
        in: path
        required: true
        description: the webhook identifier, as webhookId.
        schema:
          type: string
          format: uuid
      tags:
        - V1
      responses:
        '200':
          $ref: '#/components/responses/GetWebhookResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
    put:
      operationId: updateWebhook
      summary: Update Provider Webhook
      description: This will update an existing webhook.
      tags:
        - V1
      parameters:
        - name: accountId
          in: path
          required: true
          description: the account identifier, as accountId.
          schema:
            type: string
            format: uuid
        - name: providerId
          in: path
          required: true
          description: the provider identifier, as providerId.
          schema:
            type: string
            format: uuid
        - name: webhookId
          in: path
          required: true
          description: the webhook identifier, as webhookId.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Webhook'
      responses:
        '201':
          $ref: '#/components/responses/GetWebhookResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
  '/v1/account/{accountId}/provider/{providerId}/transactions':
    get:
      operationId: getTransactions
      summary: Transactions
      description: This will retrieve all transactions started for a payment service provider. 
      tags:
        - V1
      parameters:
        - name: accountId
          in: path
          required: true
          description: the account identifier, as accountId.
          schema:
            type: string
            format: uuid
        - name: providerId
          in: path
          required: true
          description: the payment service provider identifier, as providerId.
          schema:
            type: string
            format: uuid      
      responses:
        '200':
          $ref: '#/components/responses/GetTransactionsResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
    post:
      operationId: createTransaction
      summary: Start Transaction
      description: This will create a new transaction for the payment service provider.
      tags:
        - V1
      parameters:
        - name: accountId
          in: path
          required: true
          description: the account identifier, as accountId.
          schema:
            type: string
            format: uuid
        - name: providerId
          in: path
          required: true
          description: the payment service provider identifier, as providerId.
          schema:
            type: string
            format: uuid
      requestBody:
        description: The transaction details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transaction'
      responses:
        '201':
          $ref: '#/components/responses/GetTransactionResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
  '/v1/account/{accountId}/provider/{providerId}/transaction/{transactionId}':
    get:
      operationId: getTransaction
      summary: Transactions Details
      description: |
        This will retrieve all details of a specific transaction. A transaction can have a few specific states: 
          - 0 [OPEN]
          - 1 [CANCELED]
          - 2 [AUTHORIZED]
          - 3 [EXPIRED]
          - 4 [FAILED]
          - 5 [PAID]
          - 6 [REFUNDED]
          
        More details about the payment statusses [can be found on our Confluence](https://gen25-jira.atlassian.net/wiki/spaces/PAY25/pages/3173482511/Register+webhooks.)
      parameters:
      - name: accountId
        in: path
        required: true
        description: the account identifier, as accountId.
        schema:
          type: string
          format: uuid
      - name: providerId
        in: path
        required: true
        description: the provider identifier, as providerId.
        schema:
          type: string
          format: uuid
      - name: transactionId
        in: path
        required: true
        description: the transaction identifier, as transactionId.
        schema:
          type: string
          format: uuid
      tags:
        - V1
      responses:
        '200':
          $ref: '#/components/responses/GetTransactionResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
    delete:
      operationId: deleteTransaction
      summary: Delete Transaction
      description: This will delete a specific transaction and cancel it with the PSP.
      parameters:
      - name: accountId
        in: path
        required: true
        description: the account identifier, as accountId.
        schema:
          type: string
          format: uuid
      - name: providerId
        in: path
        required: true
        description: the provider identifier, as providerId.
        schema:
          type: string
          format: uuid
      - name: transactionId
        in: path
        required: true
        description: the transaction identifier, as transactionId.
        schema:
          type: string
          format: uuid
      tags:
        - V1
      responses:
        '200':
          $ref: '#/components/responses/GetTransactionResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'
  '/v1/account/{accountId}/provider/{providerId}/transaction_requests/bulk':
    post:
      operationId: createPaymentRequests
      summary: "Bulk create payment requests"
      description: "Create payment requests in bulk"
      parameters:
      - name: accountId
        in: path
        required: true
        description: the account identifier, as accountId.
        schema:
          type: string
          format: uuid
      - name: providerId
        in: path
        required: true
        description: the provider identifier, as providerId.
        schema:
          type: string
          format: uuid
      tags:
        - V1
      requestBody:
        description: The transaction request details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransactionRequestList'
      responses:
        '200':
          $ref: '#/components/responses/PostBulkTransactionRequestsResponse'
        '400':
          $ref: '#/components/responses/ForbiddenResponse'



     
components:
  securitySchemes:    
    BearerAuth:
      type: http
      scheme: bearer

  responses:
    GetAccountsResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountDetailsList'
    GetAccountResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountDetails'
    GetPaymentProviderResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentServiceProviderDetails'
    GetWebhooksResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhooksDetailsList'
    GetWebhookResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WebhookDetails'
    GetTransactionsResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransactionsDetailsList'
    GetTransactionResponse:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransactionDetails'
    ForbiddenResponse:
      description: 'Your account does not have access to this endpoint.'
      content: 
        'application/json': {}
    PostBulkTransactionRequestsResponse:
      description: List of Transaction Requests
      content:
        'application/json':
          schema:          
            $ref: '#/components/schemas/TransactionRequestList'
          
  examples:
    SaferPayCreate:
      value:
        name: 'SaferPay Test #1'
        provider: 'SAFERPAY'
        credentials:
          api_url: 'https://test.saferpay.com/api/'
          username: 'API_12512_12451593'
          password: 'SuperSecurePassword_1234FDSsn'
          customer_id: '084712'
          terminal_id: '74917394'
    AdyenCreate:
      value:
        name: 'Adyen Test #1'
        provider: 'ADYEN'
        credentials:
          merchant_account: 'https://test.saferpay.com/api/'
          platform: 'live'
          x_api_key: 'KXr3ZcYWfU2^cjCdubQDkexZYZBqxX%FFeVBKV9jqvD5KJ$9Fd$iNTnsF^VyDLpb@j$S5eRt8m73rk3Akc2Nw8^c4hpYmGGC2tJC@Si7T'
    StripeCreate:
      value:
        name: 'Stripe Test #1'
        provider: 'STRIPE'
        credentials:
          api_key: 'idP#rw@GXpWLHdJS!H6wkAd5b34suLXV!M$^rXum4@h3^'
          webhook_secret: 'BLieZVFivZb2xxvDPsSRwQKn%DM4JYkoyeoQHtUaG$^Ji'
            
  schemas:
    Account:
      type: object
      properties:
        name:
          type: string
          example: 'Example Dev'
        primary_email:
          description: 'An account will be created for this mailadres.'
          type: string
          example: 'clara.oswald@gen25.com'
    AccountDetailsList:
      type: array
      items:
        $ref: '#/components/schemas/AccountDetails'
      readOnly: True
    AccountDetails:
      type: object
      properties:
        account_id:
          type: string
          format: uuid
          example: '241700c0-ab77-44a8-bef2-b12fcd6486e4'
        name:
          type: string
          example: 'Example Dev'
        active:
          type: boolean
          example: false
      readOnly: True
    PaymentServiceProviderDetails:
      type: object
      properties:
        provider_id:
          type: string
          format: uuid
          example: '241700c0-ab77-44a8-bef2-b12fcd6486e4'
        name:
          type: string
          example: 'Adyen Dev #1'
        secret_arn:
          type: string
          example: 'arn:aws:secretsmanager:eu-central-1:123456:secret:Payment25ProviderSecret-2d9e5045-a19d-46c3-a971-ec56c640038e'
        provider:
          type: string
          example: 'ADYEN'
        account_id:
          type: string
          format: uuid
          example: '241700c0-ab77-44a8-bef2-b12fcd6486e4'
      readOnly: True
    SaferPayPaymentServiceProvider:
      type: object
      properties:
        name:
          type: string
          example: 'SaferPay Test #1'
        provider:
          type: string
          example: 'SAFERPAY'
        credentials:
          type: object
          properties:
            api_url:
              type: string
              example: 'https://test.saferpay.com/api/'
            username:
              type: string
              example: 'API_12512_12451593'
            password:
              type: string
              example: 'SuperSecurePassword_1234FDSsn'
            customer_id:
              type: string
              example: '084712'
            terminal_id:
              type: string
              example: '74917394'
    StripePaymentServiceProvider:
      type: object
      properties:
        name:
          type: string
          example: 'Stripe Test #1'
        provider:
          type: string
          example: 'STRIPE'
        credentials:
          type: object
          properties:
            api_key:
              type: string
              example: 'idP#rw@GXpWLHdJS!H6wkAd5b34suLXV!M$^rXum4@h3^'
            webhook_secret:
              type: string
              example: 'BLieZVFivZb2xxvDPsSRwQKn%DM4JYkoyeoQHtUaG$^Ji'
    AdyenPaymentServiceProvider:
      type: object
      properties:
        name:
          type: string
          example: 'Adyen Test #1'
        provider:
          type: string
          example: 'ADYEN'
        credentials:
          type: object
          properties:
            merchant_account:
              type: string
              example: 'CustomerNL'
            platform:
              type: string
              example: 'live'
            x_api_key:
              type: string
              example: 'KXr3ZcYWfU2^cjCdubQDkexZYZBqxX%FFeVBKV9jqvD5KJ$9Fd$iNTnsF^VyDLpb@j$S5eRt8m73rk3Akc2Nw8^c4hpYmGGC2tJC@Si7T'
    WebhooksDetailsList:
      type: array
      items:
        $ref: '#/components/schemas/WebhookDetails'
    WebhookDetails:
      readOnly: True
      allOf:
        - $ref: '#/components/schemas/Webhook'
    Webhook:
      type: object
      properties:
        destination:
          type: string
          example: 'https://webhook.io/my-epic-callback'
        active:
          type: boolean
          example: true
        use_basic_auth:
          type: boolean
          example: true
        auth_username:
          type: string
          example: 'username'
        auth_password:
          type: string
          example: 'password'
    Transaction:
      type: object
      properties:
        reference:
          type: string
          example: 'YOUR_PAYMENT_REFERENCE'
        amount:
          $ref: '#/components/schemas/Amount'
        shopper_reference:
          type: string
          example: 'UNIQUE_SHOPPER_ID_2525'
        description:
          type: string
          example: 'Transaction #42'
        country_code:
          type: string
          example: 'NL'
        shopper_locale:
          type: string
          example: 'nl-NL'
    Amount:
      type: object
      properties:
        value:
          type: integer
          example: 4200
        currency:
          type: string
          example: 'EUR'
    TransactionsDetailsList:
      type: array
      items:
        $ref: '#/components/schemas/TransactionDetails'
    TransactionDetails:
      type: object
      properties:
        transaction_id:
          type: string
          example: '67e9c451-670f-48d4-9863-72964e91fc03'
        reference:
          type: string
          example: 'YOUR_PAYMENT_REFERENCE'
        status:
          type: integer
          example: 0
        description:
          type: string
          example: 'Transaction #42'
        shopper_reference:
          type: string
          example: 'UNIQUE_SHOPPER_ID_2525'
        amount:
          type: integer
          example: 4200
        currency:
          type: string
          example: 'EUR'
        country_code:
          type: string
          example: 'NL'
        shopper_locale:
          type: string
          example: 'nl-NL'
        url:
          type: string
          example: 'https://eu.adyen.link/PLB0CCE42848AA3135'
    TransactionRequestList:
      type: object
      properties:
        items:
          type: array
          items: 
            $ref: '#/components/schemas/Transaction'
    TransactionRequestDetailsList:
      type: object
      properties:
        items:
          type: array
          items: 
            $ref: '#/components/schemas/TransactionRequestDetailsList'