LayUp Technologies PaymentPlanService API

openapi: 3.2.0
info:
  title: Layup endpoints AbsaDebiCheckService Payment Plan Service API
  version: 1.4.16
  description: 'Welcome to The Layup Swagger page. This page allows developers to interactively explore the API. For more detailed documentation see [The Layup documentation page](https://documentation.layup.co.za/).


    # Introduction


    ## What is LayUp


    LayUp is a lay-by payment solution. LayUp Schedules payments and ensures that your clients pay securely, effectively and on time. Depending on your parameters LayUp schedules a payment plan for your clients. Once a payment plan has been completed we notify you. There are 3 stories that are of importance to a merchant:


    1. Order Creation

    2. Deposit Received (and holding Stock for your client)

    3. Order Completion.


    LayUp allows you to take full control over the entire payment process if you wish to do so. We also provide a convenient front-end for users to use. The front-end should significantly reduce the time to integrate and get you started using LayUp as soon as possible.


    Once an order is completed a notification will be sent to the merchant so that you can provide the client with their product.


    ## How to use LayUp


    As a merchant who wants to place an order through LayUp, you want to send the relevant information to the LayUp API to create the order. The API will return an order ID. Unless your integration is using a custom user interface, you want to send the user to the LayUp customer payment widget. The URL for this widget is <u>https://shopper.layup.co.za/order/{orderId}</u> for production and <u>https://sandbox.layup.co.za/order/{orderId}</u> for sandbox.

    '
servers:
- url: http://localhost:3000
- url: https://localhost:3000
- url: wss://localhost:3000
security:
- apiKey:
  - read
  - write
tags:
- name: PaymentPlanService
paths:
  /v1/payment-plan:
    post:
      operationId: PaymentPlanService_Create
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanResponse'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      parameters:
      - name: _id
        in: query
        required: false
        schema:
          type: string
      tags:
      - PaymentPlanService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/modelPaymentPlanRequest'
        required: true
  /v1/payment-plan-send-notification:
    post:
      operationId: PaymentPlanService_sendPaymentPlanNotification
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanResponse'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      tags:
      - PaymentPlanService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/modelPaymentPlanSendNotificationRequest'
        required: true
  /v1/payment-plan-split:
    post:
      operationId: PaymentPlanService_CreateSplitPayment
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanResponseMany'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      parameters:
      - name: _id
        in: query
        required: false
        schema:
          type: string
      tags:
      - PaymentPlanService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/modelPaymentPlanSplitBody'
        required: true
  /v1/payment-plan/preview:
    post:
      operationId: PaymentPlanService_CreatePreview
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanPreviewResponseMany'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      tags:
      - PaymentPlanService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/modelPaymentPlanPreviewRequest'
        required: true
  /v1/payment-plan/preview/{_id}:
    get:
      operationId: PaymentPlanService_GetPreview
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanPreviewResponseMany'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      parameters:
      - name: _id
        in: path
        required: true
        schema:
          type: string
      - name: frequency
        in: query
        required: false
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          format: int32
      - name: paymentPlanId
        in: query
        required: false
        schema:
          type: string
      tags:
      - PaymentPlanService
  /v1/payment-plan/{_id}:
    get:
      operationId: PaymentPlanService_Get
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanResponse'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      parameters:
      - name: _id
        in: path
        required: true
        schema:
          type: string
      - name: populate
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      tags:
      - PaymentPlanService
    delete:
      operationId: PaymentPlanService_Del
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanDelResponse'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      parameters:
      - name: _id
        in: path
        required: true
        schema:
          type: string
      tags:
      - PaymentPlanService
    put:
      operationId: PaymentPlanService_Update
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanResponse'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      parameters:
      - name: _id
        in: path
        required: true
        schema:
          type: string
      tags:
      - PaymentPlanService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/modelPaymentPlanRequest'
        required: true
  /v1/payment-plan/{token}:
    get:
      operationId: PaymentPlanService_getByMsisdnAndToken
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/modelPaymentPlanResponse'
        '204':
          description: Successfully processed the request, no content.
        '403':
          description: Returned when the user does not have permission to access the resource.
        '404':
          description: Returned when the resource does not exist.
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      - name: msisdn
        in: query
        required: false
        schema:
          type: string
      - name: populate
        in: query
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      tags:
      - PaymentPlanService
components:
  schemas:
    modelSplitUser:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
        cellNumber:
          type: string
          pattern: ^\+27\d{9}$
    modelCancellationTermRequest:
      type: object
      properties:
        active:
          type: boolean
        definition:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelCancellationDefinition'
    modelPaymentPlanRequest:
      type: object
      properties:
        orderId:
          type: string
        benefactorId:
          type: string
        quantity:
          type: integer
          format: int32
        automaticBilling:
          type: boolean
        frequency:
          type: string
          title: weekly or monthly
        offset:
          type: integer
          format: int32
          title: for weekly 0-6, for monthly 0-30
        token:
          type: string
        agreedToTerms:
          type: boolean
    modelCustomize:
      type: object
      properties:
        logo:
          $ref: '#/components/schemas/modelLogo'
        imageUrl:
          $ref: '#/components/schemas/modelImageUrl'
        paymentWidget:
          $ref: '#/components/schemas/modelPaymentWidgetLogo'
    modelPaymentPlanSendNotificationRequest:
      type: object
      properties:
        _id:
          type: string
    modelProductResponse:
      type: object
      properties:
        _id:
          type: string
        amount:
          type: integer
          format: int32
        link:
          type: string
          format: uri
        sku:
          type: string
        name:
          type: string
        depositType:
          type: string
    modelCancellationPolicyDefinition:
      type: object
      properties:
        deposit:
          type: boolean
        percentage:
          type: integer
          format: int32
        flatFee:
          type: integer
          format: int32
        percentageShouldUseTotalPaid:
          type: boolean
    modelPaymentResponse:
      type: object
      properties:
        _id:
          type: string
        paymentPlanId:
          type: string
        due:
          type: string
        amount:
          type: integer
          format: int32
        paid:
          type: boolean
        userId:
          type: string
        locked:
          type: boolean
        pending:
          type: boolean
        timestamp:
          type: number
          format: double
        paymentMethod:
          type: string
        paymentType:
          type: string
        note:
          type: string
        reference:
          type: string
        orderStatus:
          type: string
        amountExcludingFee:
          type: integer
          format: int32
        fee:
          type: integer
          format: int32
        failed:
          type: boolean
        verifyError:
          type: string
        refundedAmount:
          type: integer
          format: int32
        refundPaymentId:
          type: string
        connectorData:
          $ref: '#/components/schemas/modelConnectorData'
        destinationId:
          type: string
        destinationType:
          type: string
    modelCancellationType:
      type: object
      properties:
        name:
          type: string
        definition:
          $ref: '#/components/schemas/modelCancellationTypeDefinition'
        finalPaymentMissed:
          type: boolean
    modelPlanPaymentConnectorData:
      type: object
      properties:
        _id:
          type: string
        amount:
          type: integer
          format: int32
        paymentProviderPaymentId:
          type: string
        paymentReference:
          type: string
        paymentMethod:
          type: string
        paymentProvider:
          type: string
        paymentProviderResponses:
          $ref: '#/components/schemas/modelPaymentProviderResponses'
    modelPaymentPlanResponse:
      type: object
      properties:
        _id:
          type: string
        orderId:
          type: string
        benefactorId:
          type: string
        completed:
          type: boolean
        quantity:
          type: integer
          format: int32
        depositDue:
          type: integer
          format: int32
        amountDue:
          type: integer
          format: int32
        automaticBilling:
          type: boolean
        timestamp:
          type: number
          format: double
        payments:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelPlanPayment'
        benefactor:
          $ref: '#/components/schemas/modelPaymentPlanBenefactor'
        frequency:
          type: string
          enum:
          - WEEKLY
          - MONTHLY
        offset:
          type: integer
          format: int32
        depositDueExcludingFee:
          type: integer
          format: int32
        amountDueExcludingFee:
          type: integer
          format: int32
        order:
          $ref: '#/components/schemas/modelOrderResponse'
        debicheckStatus:
          type: string
        debicheckLastFailedReasons:
          type: array
          items:
            type: string
        debicheckMandateActiveId:
          type: string
        debicheckMandateIds:
          type: array
          items:
            type: string
        payAtReferenceNumber:
          type: string
        agreedToTerms:
          type: boolean
    modelCancellationTypeDefinition:
      type: object
      properties:
        missed:
          type: integer
          format: int32
        percentage:
          type: integer
          format: int32
    modelNote:
      type: object
      properties:
        change:
          type: string
        date:
          type: string
        name:
          type: string
        reason:
          type: string
        details:
          type: string
        read:
          type: boolean
        userId:
          type: string
        type:
          type: string
        hide:
          type: boolean
        unread:
          type: boolean
    modelPaymentWidgetLogo:
      type: object
      properties:
        enabled:
          type: boolean
        value:
          type: string
    modelPaymentPlanSplitBody:
      type: object
      properties:
        clients:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelSplitUser'
        paymentPlan:
          $ref: '#/components/schemas/modelPaymentPlanRequest'
        redirectTo:
          type: string
        verificationRedirect:
          type: string
    modelPaymentPlanBenefactor:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        email:
          type: string
    modelImageUrl:
      type: object
      properties:
        enabled:
          type: boolean
        value:
          type: string
    modelPaymentPlanPreviewResponseMany:
      type: object
      properties:
        amountDue:
          type: integer
          format: int32
        merchant:
          type: string
        merchantTermsLink:
          type: string
        reference:
          type: string
        orderName:
          type: string
        depositDue:
          type: integer
          format: int32
        endDateMax:
          type: string
        imageUrl:
          type: string
        enablesSplit:
          type: boolean
        products:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelProductResponse'
        paymentPlans:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelPaymentPlanPreviewResponse'
        depositAmount:
          type: integer
          format: int32
        depositType:
          type: string
          enum:
          - INSTALMENT
          - FLAT
          - PERCENTAGE
          required:
          - 'true'
        flatFee:
          type: number
          format: double
        percFee:
          type: number
          format: double
        validDays:
          type: array
          items:
            type: integer
            format: int32
        validDates:
          type: array
          items:
            type: integer
            format: int32
        amountDueExcludingFee:
          type: integer
          format: int32
        depositDueExcludingFee:
          type: integer
          format: int32
        paymentMethods:
          $ref: '#/components/schemas/modelPaymentMethod'
        weeklyPayments:
          type: boolean
        orderState:
          type: string
        groupPaymentPlan:
          $ref: '#/components/schemas/modelGroupPayment'
        orderToClone:
          $ref: '#/components/schemas/modelOrderResponse'
        customFeatures:
          $ref: '#/components/schemas/modelCustomize'
        cancellationTerms:
          $ref: '#/components/schemas/modelCancellationTermRequest'
        initiatorId:
          type: string
        debiCheckMinimum:
          $ref: '#/components/schemas/modelValueEnabledPair'
        monthlyPayments:
          type: boolean
    modelConnectorData:
      type: object
      properties:
        paymentProvider:
          type: string
        paymentMethod:
          type: string
      description: Connector data bypasses protobuf conversion to allow any fields.
    modelValueEnabledPair:
      type: object
      properties:
        enabled:
          type: boolean
        value:
          type: integer
          format: int32
    modelVoucherSettings:
      type: object
      properties:
        active:
          type: boolean
        minimumSavingGoalInCents:
          type: integer
          format: int32
        maximumSavingGoalInCents:
          type: integer
          format: int32
        rewardType:
          type: string
        rewardFlatAmountInCents:
          type: integer
          format: int32
        rewardPercentage:
          type: integer
          format: int32
        voucherProvider:
          type: string
    modelPaymentPlanDelResponse:
      type: object
      properties:
        _id:
          type: string
        orderId:
          type: string
        benefactorId:
          type: string
        completed:
          type: boolean
        quantity:
          type: integer
          format: int32
        depositDue:
          type: integer
          format: int32
        amountDue:
          type: integer
          format: int32
        automaticBilling:
          type: boolean
        payments:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelPlanPayment'
        active:
          type: boolean
    modelOrderResponse:
      type: object
      properties:
        _id:
          type: string
        endDateMax:
          type: string
          format: date-time
          required:
          - 'true'
        endDateMin:
          type: string
          format: date-time
        initiatorId:
          type: string
        products:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelProductResponse'
        state:
          enum:
          - PARTIAL
          - PLACED
          - COMPLETED
          - CANCELLED
          - CANCELLING
          - EXPIRED
          - SUSPENDED
          default: PARTIAL
        supplierId:
          type: string
        cancelledBy:
          type: string
        amountDue:
          type: integer
          format: int32
        flatFee:
          type: integer
          format: int32
        percFee:
          type: number
          format: double
        depositPerc:
          type: number
          format: double
        absorbsFee:
          type: boolean
        reference:
          type: string
        name:
          type: string
        imageUrl:
          type: string
        plans:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelPaymentPlanResponse'
        createdAt:
          type: string
        timestamp:
          type: number
          format: double
        enablesSplit:
          type: boolean
        depositAmount:
          type: integer
          format: int32
        depositType:
          type: string
          enum:
          - INSTALMENT
          - FLAT
          - PERCENTAGE
          required:
          - 'true'
        expire:
          type: string
        cancellationTerms:
          $ref: '#/components/schemas/modelCancellationTermRequest'
        weeklyPayments:
          type: boolean
        paymentMethods:
          $ref: '#/components/schemas/modelPaymentMethod'
        stateUpdatedAt:
          type: string
        updatedAt:
          type: string
        groupPaymentPlan:
          $ref: '#/components/schemas/modelGroupPayment'
        cloneExpiry:
          type: integer
          format: int32
        cloneCount:
          type: integer
          format: int32
        orderCancellationRequest:
          type: string
        notifications:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelNote'
        acceptedProposedCancellationTerms:
          type: boolean
        customFeatures:
          $ref: '#/components/schemas/modelCustomize'
        merchantName:
          type: string
        merchantTermsLink:
          type: string
        merchantLink:
          type: string
        debiCheckMinimum:
          $ref: '#/components/schemas/modelValueEnabledPair'
        supplier:
          $ref: '#/components/schemas/modelSupplier'
        orderRefundRequest:
          type: string
        orderRefundAmount:
          type: integer
          format: int32
        orderRefundFee:
          type: integer
          format: int32
        monthlyPayments:
          type: boolean
        type:
          type: string
        balance:
          type: integer
          format: int32
        description:
          type: string
        isIncreasedDepositAmountAllowed:
          type: boolean
        suspendOnCancel:
          type: boolean
        voucherSettings:
          $ref: '#/components/schemas/modelVoucherSettings'
    modelPaymentProviderResponses:
      type: object
    modelPlanPayment:
      type: object
      properties:
        _id:
          type: string
        due:
          type: string
        amount:
          type: integer
          format: int32
        paid:
          type: boolean
        timestamp:
          type: number
          format: double
        paymentMethod:
          type: string
        paymentType:
          type: string
        amountExcludingFee:
          type: integer
          format: int32
        fee:
          type: integer
          format: int32
        pending:
          type: boolean
        failed:
          type: boolean
        reconciliated:
          type: boolean
        refundedAmount:
          type: integer
          format: int32
        refundPaymentId:
          type: string
        connectorData:
          $ref: '#/components/schemas/modelPlanPaymentConnectorData'
        verifiedAt:
          type: string
        dueAt:
          type: string
    modelCancellationPolicy:
      type: object
      properties:
        name:
          type: string
          enum:
          - Deposit
          - Percentage
          - FlatFee
          - Combination
        definition:
          $ref: '#/components/schemas/modelCancellationPolicyDefinition'
    modelSupplier:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        merchantId:
          type: string
    modelPaymentPlanPreviewRequest:
      type: object
      properties:
        amountDue:
          type: integer
          required:
          - 'true'
        depositPerc:
          type: number
          required:
          - 'true'
        endDateMax:
          type: string
          format: date-time
          required:
          - 'true'
        endDateMin:
          type: string
          format: date-time
          required:
          - 'true'
        absorbsFee:
          type: boolean
          required:
          - 'true'
        frequency:
          type: string
          enum:
          - WEEKLY
          - MONTHLY
        offset:
          type: integer
          format: int32
        depositAmount:
          type: integer
          format: int32
        depositType:
          type: string
          enum:
          - INSTALMENT
          - FLAT
          - PERCENTAGE
          required:
          - 'true'
        flatFee:
          type: number
          format: double
        percFee:
          type: number
          format: double
        paymentPlanId:
          type: string
        quantity:
          type: integer
          format: int32
    modelPaymentPlanPreviewResponse:
      type: object
      properties:
        months:
          type: integer
          format: int32
        deposit:
          type: integer
          format: int32
        payments:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelPaymentResponse'
        quantity:
          type: integer
          format: int32
        orderState:
          type: string
    modelPaymentMethod:
      type: object
      properties:
        creditOrDebitCard:
          type: boolean
        eft:
          type: boolean
        debiCheck:
          type: boolean
        payAt:
          type: boolean
        capitecPay:
          type: boolean
        dashpay:
          type: boolean
        terminalCard:
          type: boolean
        offline:
          type: boolean
        embeddedCheckout:
          type: boolean
    modelCancellationDefinition:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/modelCancellationType'
        policy:
          $ref: '#/components/schemas/modelCancellationPolicy'
        start:
          type: integer
          format: int32
        end:
          type: integer
          format: int32
        gracePeriod:
          type: integer
          format: int32
    modelGroupPayment:
      type: object
      properties:
        enabled:
          type: boolean
        cloneLimit:
          type: integer
          format: int32
        expiry:
          type: integer
          format: int32
    modelLogo:
      type: object
      properties:
        enabled:
          type: boolean
        value:
          type: string
    modelPaymentPlanResponseMany:
      type: object
      properties:
        paymentPlans:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/modelPaymentPlanResponse'
  securitySchemes:
    apiKey:
      type: apiKey
      name: apikey
      in: header