Modulr Variable Recurring Payments API

openapi: 3.2.0
info:
  title: Modulr Variable Recurring Payments API
  description: Modulr API
  license:
    name: © Modulr Finance
    url: https://www.modulrfinance.com
  version: '1.0'
servers:
- url: https://api-sandbox.modulrfinance.com/api-sandbox-token
security:
- modulo_security: []
tags:
- name: Variable Recurring Payments
paths:
  /vrp:
    post:
      tags:
      - Variable Recurring Payments
      summary: Initiate a Variable Recurring Payment.
      description: Initiates a new Variable Recurring Payment using an existing authorised consent.
      operationId: initiateVrpPayment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pispgateway.VrpPaymentRequest'
        required: true
      responses:
        '201':
          description: Variable Recurring Payment initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pispgateway.VrpPaymentResponse'
        '400':
          description: The consent cannot be processed as it does not exist.
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pispgateway.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /vrp-consents:
    post:
      tags:
      - Variable Recurring Payments
      summary: Create a VRP consent
      description: Create a Variable Recurring Payment (VRP) consent for authorisation by the payment service user. The consent can then be used to initiate one or more payments within the payment constraints specified.
      operationId: initiateConsentCreation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pispgateway.CreateVrpConsentCreationRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pispgateway.CreateVrpConsentInitiationResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pispgateway.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /vrp-consents/{consentId}/funds-confirmation:
    post:
      tags:
      - Variable Recurring Payments
      summary: Confirm the availability of funds in an account.
      description: Confirm the availability of funds in account, prior to initiating a Variable Recurring Payment, using an authorised consent.
      operationId: confirmFunds
      parameters:
      - name: consentId
        in: path
        description: Vrp consent id
        required: true
        style: simple
        explode: false
        schema:
          type: string
          minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pispgateway.VrpConfirmationOfFundsRequest'
        required: true
      responses:
        '200':
          description: Confirmation of Funds successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pispgateway.VrpConfirmationOfFundsResponse'
        '400':
          description: Confirmation of funds request cannot be processed as the consent with the provided ID does not exist.
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pispgateway.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /vrp/{vrpPaymentId}:
    get:
      tags:
      - Variable Recurring Payments
      summary: Get Variable Recurring Payment
      description: Fetch the details of a payment initiated using Variable Recurring Payment (VRP) based on a unique payment ID.
      operationId: getVrpPayment
      parameters:
      - name: vrpPaymentId
        in: path
        description: Vrp Payment Id
        required: true
        style: simple
        explode: false
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pispgateway.VrpPaymentDetailsResponse'
        '400':
          description: The payment cannot be retrieved as it does not exist.
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pispgateway.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
  /vrp-consents/{consentId}:
    get:
      tags:
      - Variable Recurring Payments
      summary: Get VRP consent.
      description: Returns information about a given Variable Recurring Payment consent.
      operationId: getVrpConsent
      parameters:
      - name: consentId
        in: path
        description: Vrp consent id
        required: true
        style: simple
        explode: false
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pispgateway.VrpConsentResponse'
        '400':
          description: The consent details cannot be retrieved as it does not exist
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pispgateway.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
    delete:
      tags:
      - Variable Recurring Payments
      summary: Revoke a VRP consent.
      description: Cancels a VRP consent and stops further variable recurring payments being made using it.
      operationId: revokeVrpConsent
      parameters:
      - name: consentId
        in: path
        description: Vrp consent id
        required: true
        style: simple
        explode: false
        schema:
          type: string
          minLength: 1
      responses:
        '202':
          description: Vrp consent revoked
        '400':
          description: The consent cannot be revoked as it does not exist
          content:
            '*/*':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/pispgateway.MessageResponse'
      security:
      - HMAC: []
      - TOKEN: []
components:
  schemas:
    pispgateway.CreateVrpConsentInitiationResponse:
      type: object
      description: Response object to Initiate Vrp Consent
      properties:
        vrpConsentInitiationId:
          type: string
          description: The unique identifier of the VRP consent initiation request at Modulr
          example: E210000004
        redirectUrl:
          type: string
          description: A redirect URL for the user to authorise the payment initiation request at the ASPSP
          example: https://www.bankofmoney.com/authorize
    pispgateway.VrpConfirmationOfFundsResponse:
      type: object
      properties:
        fundsAvailable:
          type: boolean
          description: The result of funds availability check, can be one of 'true' or 'false'
        fundsAvailabilityCheckDateTime:
          type: string
          format: date-time
          description: The time that the funds availability check occurred
    pispgateway.Destination:
      type: object
      description: The destination account for the payment
      properties:
        type:
          type: string
          description: Indicates the type of destination. Can be one of ACCOUNT, SCAN
          enum:
          - ACCOUNT
          - SCAN
        id:
          type: string
          description: Identifier of the destination account if using ACCOUNT type
          example: A1100001
        accountNumber:
          type: string
          description: Account Number of destination account if using SCAN type
          example: '12345678'
          pattern: ^[0-9]{8}$
        sortCode:
          type: string
          description: Sort Code of destination account if using SCAN type
          example: '000000'
          pattern: ^[0-9]{6}$
        name:
          type: string
          description: Name of destination account if using SCAN type (this may be truncated)
          example: Test
          maxLength: 70
          minLength: 0
      required:
      - type
    pispgateway.Payment:
      type: object
      properties:
        currency:
          type: string
          description: Currency of the payment amount. Must be specified in ISO 4217 format.
        amount:
          type: number
          description: Payment amount
          example: '100.00'
        reference:
          type: string
          description: A reference used to unambiguously refer to the payment transaction. Min 6 to max 18 characters. Can contain alphanumeric, '-', '.', '&', '/' and space.
      required:
      - currency
      - reference
    pispgateway.PaymentConstraints:
      type: object
      description: 'Limits that will apply to payments initiated using this consent. '
      properties:
        maximumIndividualAmount:
          $ref: '#/components/schemas/pispgateway.MaximumIndividualVrPayment'
          description: Maximum amount of any single payment initiated using this consent.
        periodicLimits:
          type: array
          description: Maximum amount of all payments that can be initiated using this consent in a given period. If the periodAlignment is “Calendar”, the limit is pro-rated in the first period to the remaining number of days.
          items:
            $ref: '#/components/schemas/pispgateway.PeriodicLimit'
      required:
      - maximumIndividualAmount
    pispgateway.VrpPaymentDetailsResponse:
      type: object
      properties:
        consentId:
          type: string
          description: The unique identifier of the VRP consent initiation request at Modulr.
          example: E210000004
        payment:
          $ref: '#/components/schemas/pispgateway.Payment'
          description: Payment details for the VRP payment initiation request.
        status:
          type: string
          description: The current status of the VRP payment.
          enum:
          - SUBMITTED
          - ACCEPTEDWITHOUTPOSTING
          - ACCEPTEDSETTLEMENTINPROCESS
          - PENDING
          - REJECTED
          - ACCEPTEDCREDITSETTLEMENTCOMPLETED
          - ACCEPTEDSETTLEMENTCOMPLETED
          - RECEIVED
          - CANCELLED
          - BLOCKED
          - ACCEPTEDTECHNICALVALIDATION
          - ACCEPTEDCUSTOMERPROFILE
          - ACCEPTEDFUNDSCHECKED
          - ACCEPTEDWITHCHANGE
          - ACCEPTEDSETTLEMENTCOMPLETEDCREDITORACCOUNT
          - ACCEPTEDSETTLEMENTCOMPLETEDDEBITORACCOUNT
          - ER_GENERAL
          - ER_EXTSYS
        statusReasonCodes:
          type: array
          items:
            type: string
            description: Specifies the status reason in a code form.
            example: ERIN
            maxLength: 4
            minLength: 1
        interactionType:
          type: string
          description: 'PSU interaction type permitted under this consent. Must be one of: IN_SESSION (customer is present), OFF_SESSION (customer is not present).'
          enum:
          - IN_SESSION
          - OFF_SESSION
      required:
      - consentId
      - payment
      - status
    pispgateway.VrpConfirmationOfFundsRequest:
      type: object
      description: Request object to confirm the availability of funds in account
      properties:
        currency:
          type: string
          description: Currency of the maximum individual amount. Must be specified in ISO 4217 format.
        amount:
          type: number
          description: amount that will be confirmed for availability of funds - '1' = 1.00 GBP
          example: '100.00'
      required:
      - currency
    pispgateway.VrpConsentResponse:
      type: object
      description: Response object of VRP Consent
      properties:
        aspspId:
          type: string
          description: Identifier of the payer’s ASPSP where the consent will be created. The ASPSP must have the "SWEEPING" or "COMMERCIAL" capability enabled (which can be checked using our API).
          example: H100000001
        destination:
          $ref: '#/components/schemas/pispgateway.Destination'
          description: Destination account details that will receive variable recurring payments initiated using this consent.
        paymentConstraints:
          $ref: '#/components/schemas/pispgateway.PaymentConstraints'
          description: Limits that will apply to payments initiated using this consent.
        reference:
          type: string
          description: Reference to be used for the Consent. This will appear on the Account statement/the recipient's bank account. Min 6 to max 18 characters. Can contain alphanumeric, '-', '.', '&', '/' and space.
          example: Invoice ABC123
        validFromDate:
          type: string
          format: date-time
          description: Start date time from which payments can be initiated using this consent. Must be specified using YYYY-MM-DDTHH:mm:ssZ format.
          example: '2022-01-31T20:16:01.90Z'
        validToDate:
          type: string
          format: date-time
          description: End date time after which payments cannot be initiated using this consent. Must be specified using YYYY-MM-DDTHH:mm:ssZ format.
          example: '2022-07-31T20:16:01.90Z'
        type:
          type: string
          description: Type of VRP consent that will be created.
          enum:
          - SWEEPING
          - CVRP1
        status:
          type: string
          description: The current status of the VRP consent.
          enum:
          - AWAITING_AUTHORISATION
          - AUTHORISED
          - REJECTED
          - REVOKED
          - ER_GENERAL
          - ER_EXTSYS
        interactionTypes:
          type: array
          description: List of PSU interaction types permitted under this consent. Must be one or both of IN_SESSION (customer is present), OFF_SESSION (customer is not present)
          items:
            type: string
            enum:
            - IN_SESSION
            - OFF_SESSION
        ultimateCreditor:
          $ref: '#/components/schemas/pispgateway.UltimateParty'
          description: The ultimate beneficiary of the payment, party to which an amount of money is due. Provided if different from the immediate creditor.
        ultimateDebtor:
          $ref: '#/components/schemas/pispgateway.UltimateParty'
          description: The ultimate payer, party that owes an amount of money to the (ultimate) creditor. Provided if different from the account holder.
        risk:
          $ref: '#/components/schemas/pispgateway.OBRisk'
          description: Additional details used for risk scoring for Payments.
      required:
      - aspspId
      - destination
      - paymentConstraints
      - reference
      - status
      - type
    pispgateway.CreateVrpConsentCreationRequest:
      type: object
      description: Request object to Initiate VRP Consent Creation
      properties:
        aspspId:
          type: string
          description: Identifier of the payer’s ASPSP where the consent will be created. The ASPSP must have the "SWEEPING" or "COMMERCIAL" capability enabled (which can be checked using our API).
          example: H100000001
        destination:
          $ref: '#/components/schemas/pispgateway.Destination'
          description: Destination account details that will receive variable recurring payments initiated using this consent.
        paymentConstraints:
          $ref: '#/components/schemas/pispgateway.PaymentConstraints'
          description: Limits that will apply to payments initiated using this consent.
        validFromDate:
          type: string
          format: date-time
          description: Start date time from which payments can be initiated using this consent. Must be specified using YYYY-MM-DDTHH:mm:ssZ format.
          example: '2022-01-31T20:16:01.90Z'
        validToDate:
          type: string
          format: date-time
          description: End date time after which payments cannot be initiated using this consent. Must be specified using YYYY-MM-DDTHH:mm:ssZ format.
          example: '2022-07-31T20:16:01.90Z'
        type:
          type: string
          description: Type of VRP consent that will be created.
          enum:
          - SWEEPING
          - CVRP1
        reference:
          type: string
          description: Reference to be used for the Consent. This will appear on the Account statement/the recipient's bank account. Min 6 to max 18 characters. Can contain alphanumeric, '-', '.', '&', '/' and space.
          example: Invoice ABC123
        interactionTypes:
          type: array
          description: List of PSU interaction types permitted under this consent. Mandatory for CVRP consent type. Must be one or both of IN_SESSION (customer is present), OFF_SESSION (customer is not present)
          items:
            type: string
            enum:
            - IN_SESSION
            - OFF_SESSION
        ultimateCreditor:
          $ref: '#/components/schemas/pispgateway.UltimateParty'
          description: The ultimate beneficiary of the payment, party to which an amount of money is due. To be provided if different from the immediate creditor.
        ultimateDebtor:
          $ref: '#/components/schemas/pispgateway.UltimateParty'
          description: The ultimate payer, party that owes an amount of money to the (ultimate) creditor. To be provided if different from the account holder.
        risk:
          $ref: '#/components/schemas/pispgateway.OBRisk'
          description: It is used to specify additional details for risk scoring for Payments.
      required:
      - aspspId
      - destination
      - paymentConstraints
      - reference
      - type
    pispgateway.OBRisk:
      type: object
      properties:
        merchantCategoryCode:
          type: string
          description: Category code conforming to ISO 18245, related to the type of services or goods the merchant provides.
          maxLength: 4
          minLength: 3
        merchantCustomerIdentification:
          type: string
          description: The unique customer identifier of the PSU with the merchant.
          maxLength: 70
          minLength: 1
        contractPresentIndicator:
          type: boolean
          description: Indicates if Payee has a contractual relationship with the PISP.
        beneficiaryPrepopulatedIndicator:
          type: boolean
          description: Indicates if PISP has immutably prepopulated payment details for the PSU.
        beneficiaryAccountType:
          type: string
          description: Specifies the extended type of beneficiary account if known.
          enum:
          - Business
          - BusinessSavingsAccount
          - Charity
          - Collection
          - Corporate
          - Ewallet
          - Government
          - Investment
          - ISA
          - JointPersonal
          - Pension
          - Personal
          - PersonalSavingsAccount
          - Premier
          - Wealth
        deliveryAddress:
          $ref: '#/components/schemas/pispgateway.PostalAddress'
          description: Information that locates and identifies a delivery address.
      required:
      - beneficiaryPrepopulatedIndicator
      - contractPresentIndicator
      - merchantCategoryCode
      - merchantCustomerIdentification
    pispgateway.PostalAddress:
      type: object
      properties:
        addressType:
          type: string
          description: Identifies the nature of the postal address. BIZZ (Business), DLVY (Delivery), MLTO (Mail To), PBOX (PO Box), ADDR (Postal), HOME (Residential), CORR (Correspondence), STAT (Statement).
          enum:
          - BIZZ
          - DLVY
          - MLTO
          - PBOX
          - ADDR
          - HOME
          - CORR
          - STAT
        department:
          type: string
          description: Identification of a division of a large organisation or building.
          maxLength: 70
          minLength: 1
        subDepartment:
          type: string
          description: Identification of a sub-division of a large organisation or building.
          maxLength: 70
          minLength: 1
        streetName:
          type: string
          description: Name of a street or thoroughfare.
          maxLength: 140
          minLength: 1
        buildingNumber:
          type: string
          description: Number that identifies the position of a building on a street.
          maxLength: 16
          minLength: 1
        buildingName:
          type: string
          description: Name of a referenced building.
          maxLength: 140
          minLength: 1
        floor:
          type: string
          description: Number that identifies the level within a building.
          maxLength: 70
          minLength: 1
        unitNumber:
          type: string
          description: Number that identifies the unit of a specific address.
          maxLength: 16
          minLength: 1
        room:
          type: string
          description: Information that locates and identifies a room to form part of an address.
          maxLength: 70
          minLength: 1
        postBox:
          type: string
          description: Information that locates and identifies a box in a post office assigned to a person or organization, where letters for them are kept until called for.
          maxLength: 16
          minLength: 1
        townLocationName:
          type: string
          description: Name of a built-up area, with defined boundaries, and a local government.
          maxLength: 140
          minLength: 1
        districtName:
          type: string
          description: Number that of the regional area, known as a district, which forms part of an address.
          maxLength: 140
          minLength: 1
        careOf:
          type: string
          description: The 'care of' address is used whenever sending mail to a person or organisation who does not actually live or work at the address. They will receive the mail for the individual.
          maxLength: 140
          minLength: 1
        postCode:
          type: string
          description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
          maxLength: 16
          minLength: 1
        townName:
          type: string
          description: Name of a built-up area, with defined boundaries, and a local government.
          maxLength: 140
          minLength: 1
        countrySubDivision:
          type: string
          description: Identifies a subdivision of a country such as state, region, county.
          maxLength: 35
          minLength: 1
        country:
          type: string
          description: Nation with its own government, as an ISO 3166-1 alpha-2 country code.
          example: GB
          pattern: ^[A-Z]{2,2}$
        addressLine:
          type: array
          description: Information that locates and identifies a specific address, as defined by postal services, presented in free format text. Maximum 7 lines, each up to 70 characters.
          items:
            type: string
    pispgateway.UltimateParty:
      type: object
      properties:
        name:
          type: string
          description: Name by which a party is known and which is usually used to identify that party.
          maxLength: 140
          minLength: 1
        identification:
          type: string
          description: Identification assigned by an institution.
          maxLength: 256
          minLength: 1
        lei:
          type: string
          description: Legal entity identification as an alternate identification for a party. Legal Entity Identifier is a code allocated to a party as described in ISO 17442 Financial Services - Legal Entity Identifier (LEI).
          maxLength: 20
          minLength: 1
        postalAddress:
          $ref: '#/components/schemas/pispgateway.PostalAddress'
          description: Information that locates and identifies a specific address, as defined by postal services.
    pispgateway.VrpPaymentRequest:
      type: object
      properties:
        consentId:
          type: string
          description: The unique identifier of the VRP consent initiation request at Modulr.
          example: E210000004
        payment:
          $ref: '#/components/schemas/pispgateway.Payment'
          description: Payment details for the VRP payment initiation request.
        interactionType:
          type: string
          description: 'PSU interaction type permitted under this consent. Must be one of: IN_SESSION (customer is present), OFF_SESSION (customer is not present).'
          enum:
          - IN_SESSION
          - OFF_SESSION
      required:
      - consentId
      - payment
    pispgateway.MaximumIndividualVrPayment:
      type: object
      description: Maximum amount of any single payment initiated using this consent.
      properties:
        currency:
          type: string
          description: Currency of the maximum individual amount. Must be specified in ISO 4217 format.
        amount:
          type: number
          description: Maximum amount of any single payment initiated using this consent - '1' = 1.00 GBP
          example: '100.00'
      required:
      - currency
    pispgateway.VrpPaymentResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the VRP payment initiation request at Modulr
          example: V21000001E
        status:
          type: string
          description: The current status of vrp payment. Must be one of “SUBMITTED”, “ACCEPTEDWITHOUTPOSTING”, “ACCEPTEDSETTLEMENTINPROCESS”, “PENDING”, “REJECTED”, “ACCEPTEDCREDITSETTLEMENTCOMPLETED”, “ACCEPTEDSETTLEMENTCOMPLETED”, “RECEIVED”, “CANCELLED”, “BLOCKED”, “ACCEPTEDTECHNICALVALIDATION”, “ACCEPTEDCUSTOMERPROFILE”, “ACCEPTEDFUNDSCHECKED”, “ACCEPTEDWITHCHANGE”, “ACCEPTEDSETTLEMENTCOMPLETEDCREDITORACCOUNT”, “ACCEPTEDSETTLEMENTCOMPLETEDDEBITORACCOUNT”, “ER_GENERAL”, “ER_EXTSYS”
          enum:
          - SUBMITTED
          - ACCEPTEDWITHOUTPOSTING
          - ACCEPTEDSETTLEMENTINPROCESS
          - PENDING
          - REJECTED
          - ACCEPTEDCREDITSETTLEMENTCOMPLETED
          - ACCEPTEDSETTLEMENTCOMPLETED
          - RECEIVED
          - CANCELLED
          - BLOCKED
          - ACCEPTEDTECHNICALVALIDATION
          - ACCEPTEDCUSTOMERPROFILE
          - ACCEPTEDFUNDSCHECKED
          - ACCEPTEDWITHCHANGE
          - ACCEPTEDSETTLEMENTCOMPLETEDCREDITORACCOUNT
          - ACCEPTEDSETTLEMENTCOMPLETEDDEBITORACCOUNT
          - ER_GENERAL
          - ER_EXTSYS
      required:
      - status
    pispgateway.MessageResponse:
      type: object
      properties:
        field:
          type: string
        code:
          type: string
          enum:
          - GENERAL
          - BUSINESSRULE
          - MFASTATUS
          - MFAERROR
          - MFATIMEOUT
          - MFADEVICEMM
          - MFAMESSAGEINVALID
          - NOTFOUND
          - DUPLICATE
          - INVALID
          - CONNECTION
          - RETRY
          - RATELIMIT
          - PERMISSION
          - NOTACCEPTABLE
          - MFAVERIFICATION
          - TOKENEXPIRED
        errorCode:
          type: string
        message:
          type: string
        sourceService:
          type: string
    pispgateway.PeriodicLimit:
      type: object
      description: Maximum amount of all payments that can be initiated using this consent in a given period. If the periodAlignment is “Calendar”, the limit is pro-rated in the first period to the remaining number of days.
      properties:
        currency:
          type: string
          description: Currency of the maximum amount. Must be specified in ISO 4217 format.
        amount:
          type: number
          description: The maximum amount of all payments initiated using this consent in the specified period. At least one periodic limit is required - '1' = 1.00 GBP
          example: '100.00'
        periodAlignment:
          type: string
          description: Specifies whether the period starts on the date of consent creation or lines up with a calendar.
        periodType:
          type: string
          description: Period type. Must be one of “DAY”,”WEEK”,”FORTNIGHT”,”MONTH”,”HALF_YEAR”,”YEAR”.
      required:
      - currency
      - periodAlignment
      - periodType
  securitySchemes:
    modulo_security:
      type: apiKey
      name: Authorization
      in: header
    TOKEN:
      type: apiKey
      name: Authorization
      in: header
x-readme:
  proxy-enabled: false