Receeve AccountMandate API

openapi: 3.0.3
info:
  title: InDebted Receive API Documentation Account AccountMandate API
  description: 'This is the API definition for interacting with InDebted''s Receive debt servicing platform. For more details please visit the [Integration Documentation](https://docs.indebted.co/docs/receive/receive-knowledge-base).


    **Using this spec in code generators, Postman, or other tooling?** Fetch the raw document at [https://receive-api.indebted.co/openapi/apiSchema.yaml](https://receive-api.indebted.co/openapi/apiSchema.yaml) — that is the canonical OpenAPI file. Prefer it over the in-page download button, which re-serialises the document and can alter value types (e.g. date-formatted strings).'
  contact:
    email: techteam@indebted.co
  version: 1.53.1
servers:
- url: /
  description: API base path
tags:
- name: AccountMandate
paths:
  /v1/{clientId}/create_account_mandates:
    post:
      tags:
      - AccountMandate
      summary: Create account mandates in the platform
      operationId: createAccountMandates
      parameters:
      - $ref: '#/components/parameters/ClientIdParameter'
      - $ref: '#/components/parameters/AuthorizationParameter'
      - $ref: '#/components/parameters/TriggerNameParameter'
      - $ref: '#/components/parameters/SequentialParameter'
      - $ref: '#/components/parameters/AsyncParameter'
      - $ref: '#/components/parameters/MinorVersionParameter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AccountMandateInput'
            example:
            - mandateId: MANDATE-7f257450
              accountReference: ACC-DE-5567
              providerName: trustly
              debtorReference: CUST-88213
              productReferences:
              - BROADBAND_PLAN_A
      responses:
        '200':
          $ref: '#/components/responses/200SuccessCreateAccountMandates'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429LimitsReached'
        '500':
          $ref: '#/components/responses/500InternalError'
      security:
      - api_key: []
  /v1/{clientId}/delete_account_mandates:
    post:
      tags:
      - AccountMandate
      summary: Delete account mandates in the platform
      operationId: deleteAccountMandates
      parameters:
      - $ref: '#/components/parameters/ClientIdParameter'
      - $ref: '#/components/parameters/AuthorizationParameter'
      - $ref: '#/components/parameters/TriggerNameParameter'
      - $ref: '#/components/parameters/SequentialParameter'
      - $ref: '#/components/parameters/AsyncParameter'
      - $ref: '#/components/parameters/MinorVersionParameter'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AccountMandateDeleteInput'
            example:
            - accountReference: ACC-DE-5567
              mandateId: MANDATE-7f257450
      responses:
        '200':
          $ref: '#/components/responses/200Success'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429LimitsReached'
        '500':
          $ref: '#/components/responses/500InternalError'
      security:
      - api_key: []
  /v1/{clientId}/get_account_mandates:
    get:
      tags:
      - AccountMandate
      summary: Get account mandates
      operationId: getAccountMandates
      parameters:
      - $ref: '#/components/parameters/ClientIdParameter'
      - $ref: '#/components/parameters/AuthorizationParameter'
      - $ref: '#/components/parameters/AccountReferenceParameter'
      - $ref: '#/components/parameters/TriggerNameParameter'
      responses:
        '200':
          $ref: '#/components/responses/200SuccessGetAccountMandates'
        '400':
          $ref: '#/components/responses/400BadRequest'
        '401':
          $ref: '#/components/responses/401Unauthorized'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '429':
          $ref: '#/components/responses/429LimitsReached'
        '500':
          $ref: '#/components/responses/500InternalError'
      security:
      - api_key: []
components:
  parameters:
    SequentialParameter:
      name: sequential
      in: query
      required: false
      description: The request body items are executed one after another one
      schema:
        type: boolean
    AsyncParameter:
      name: async
      in: query
      required: false
      description: The request is added to the queue without expecting the response
      schema:
        type: boolean
    ClientIdParameter:
      name: clientId
      in: path
      required: true
      description: 'A Receive system identifier that will be assigned automatically.

        It will be used for situations like Support related interventions or data segmentation.

        '
      example: ec702157-705b-42a0-b70e-a60a63dd24ab
      schema:
        type: string
        format: uuid
    AuthorizationParameter:
      in: header
      name: Authorization
      required: true
      description: 'OAuth2 Token (obtained from /oauth2/token )

        Reference: https://docs.indebted.co/docs/receive/integration/use-cases/authentication-use-case

        '
      example: Bearer <access_token>
      schema:
        type: string
    MinorVersionParameter:
      name: minorVersion
      in: query
      required: false
      description: Optional minor version identifier for message versioning. This value is passed as additional metadata with emitted messages.
      schema:
        type: string
    TriggerNameParameter:
      name: triggerName
      in: query
      required: false
      description: This is name of Custom Trigger that should be triggered when this API is called.
      schema:
        type: string
      example: customTrigger1
    AccountReferenceParameter:
      name: accountReference
      in: query
      required: true
      example: ACC
      description: Account reference in your system
      schema:
        type: string
  schemas:
    FerratumV2AccountMandateInput:
      allOf:
      - $ref: '#/components/schemas/BaseAccountMandateInput'
      - type: object
        required:
        - providerName
        properties:
          providerName:
            type: string
            enum:
            - ferratumCheckoutCreditCardV2
    ProductReference:
      type: string
      minLength: 1
      example: PRODUCT_REFERENCE_1
      description: Identifier for a product in your system. It is used for grouping purposes.
    AccountMandateDeleteInput:
      description: Input for delete_account_mandates endpoint.
      type: object
      required:
      - accountReference
      - mandateId
      properties:
        accountReference:
          $ref: '#/components/schemas/AccountReference'
        mandateId:
          type: string
          description: mandate id (can be the mandate id of external system)
          example: d34b443e-968e-4647-80ec-292ee38c8b34
          minLength: 1
    AccountReference:
      type: string
      minLength: 1
      example: ACCOUNT_REFERENCE_002
      description: Account reference in your system
    AccountMandate:
      type: object
      required:
      - mandateId
      - accountReference
      - providerName
      properties:
        mandateId:
          type: string
          description: mandate id (can be the mandate id of external system)
          example: d34b443e-968e-4647-80ec-292ee38c8b34
          minLength: 1
        accountReference:
          $ref: '#/components/schemas/AccountReference'
        providerName:
          type: string
          description: Name of payment provider
          example: trustly
        debtorReference:
          $ref: '#/components/schemas/DebtorReference'
        productReferences:
          type: array
          description: Product References
          items:
            $ref: '#/components/schemas/ProductReference'
        mandateRepresentation:
          oneOf:
          - $ref: '#/components/schemas/MandateAccountTypeRepresentation'
          - $ref: '#/components/schemas/MandateCardTypeRepresentation'
    CreateAccountMandates:
      allOf:
      - $ref: '#/components/schemas/ActionResponse'
      - type: object
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/AccountMandateInput'
    DebtorReference:
      type: string
      minLength: 1
      example: EXTERNAL_DEBTOR_REF_002
      description: Your customer ID for this person or company
    TrustlyAccountMandateInput:
      allOf:
      - $ref: '#/components/schemas/BaseAccountMandateInput'
      - type: object
        required:
        - providerName
        properties:
          providerName:
            type: string
            enum:
            - trustly
    SplitAccountMandateInput:
      allOf:
      - $ref: '#/components/schemas/BaseAccountMandateInput'
      - type: object
        required:
        - providerName
        properties:
          providerName:
            type: string
            enum:
            - split
    BaseAccountMandateInput:
      type: object
      required:
      - mandateId
      - accountReference
      - providerName
      - debtorReference
      - productReferences
      properties:
        mandateId:
          type: string
          description: mandate id (can be the mandate id of external system)
          example: d34b443e-968e-4647-80ec-292ee38c8b34
          minLength: 1
        accountReference:
          $ref: '#/components/schemas/AccountReference'
        providerName:
          type: string
          description: Name of payment provider
          example: trustly
        debtorReference:
          $ref: '#/components/schemas/DebtorReference'
        productReferences:
          type: array
          description: Product References
          items:
            $ref: '#/components/schemas/ProductReference'
        mandateRepresentation:
          oneOf:
          - $ref: '#/components/schemas/MandateAccountTypeRepresentation'
          - $ref: '#/components/schemas/MandateCardTypeRepresentation'
    ActionResponse:
      type: object
      description: Response of any action that causes any side effect in the platform (e.g. create, update, delete)
      required:
      - success
      - messages
      - messageIds
      properties:
        success:
          type: boolean
          example: false
          description: Status of the action
        messages:
          type: array
          items:
            type: string
            example: Successfully created claim claim1
            description: Human-friendly message about the action
        messageIds:
          type: array
          description: Identifier of the messages (used for tracing)
          items:
            type: string
            format: uuid
            example: 32638681-bb15-400d-acc8-15bf8e38661e
      example:
        success: true
        messages:
        - Successfully processed action
        messageIds:
        - e66d62ed-2331-4ced-8c03-5e729e984adc
    MandateAccountTypeRepresentation:
      type: object
      required:
      - bankName
      - accountNumber
      properties:
        holderName:
          type: string
        bankName:
          type: string
        accountNumber:
          type: string
    PaylandsAccountMandateInput:
      allOf:
      - $ref: '#/components/schemas/BaseAccountMandateInput'
      - type: object
        required:
        - providerName
        - clientIpAddress
        properties:
          providerName:
            type: string
            enum:
            - paylandsenBizum
            - paylandsenCards
          clientIpAddress:
            type: string
            description: The customer ip address is needed for Paylands mandate to work
    AccountMandateInput:
      oneOf:
      - $ref: '#/components/schemas/FerratumV2AccountMandateInput'
      - $ref: '#/components/schemas/PaylandsAccountMandateInput'
      - $ref: '#/components/schemas/SplitAccountMandateInput'
      - $ref: '#/components/schemas/TrustlyAccountMandateInput'
    MandateCardTypeRepresentation:
      type: object
      required:
      - cardIssuer
      - lastDigits
      properties:
        cardIssuer:
          type: string
          example: VISA
        lastDigits:
          type: string
          example: '1404'
        holderName:
          type: string
        expiryMonth:
          type: string
          example: 5
        expiryYear:
          type: string
          example: 2023
        bankName:
          type: string
  responses:
    403Forbidden:
      description: Access is denied
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Forbidden
    500InternalError:
      description: Internal error occured
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Internal error
    200SuccessGetAccountMandates:
      description: Request for get_account_mandates is successful
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/AccountMandate'
          example:
          - mandateId: MANDATE-7f257450
            accountReference: ACC-DE-5567
            providerName: gocardless
            debtorReference: CUST-88213
            productReferences:
            - BROADBAND_PLAN_A
    200Success:
      description: Request was successful
      content:
        application/json:
          schema:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/ActionResponse'
          example:
            REFERENCE_1:
              success: true
              messages:
              - Successfully processed action
              messageIds:
              - e66d62ed-2331-4ced-8c03-5e729e984adc
    401Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized
    200SuccessCreateAccountMandates:
      description: Response of creating a set of account mandates
      content:
        application/json:
          schema:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/CreateAccountMandates'
          example:
            MANDATE-7f257450:
              success: true
              messages:
              - Successfully created mandate MANDATE-7f257450
              messageIds:
              - a1b2c3d4-0000-4a8b-9c6d-2e5f8a1b0c44
    400BadRequest:
      description: Incorrectly formed request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: 'Missing required request parameters: [Authorization]'
    429LimitsReached:
      description: Request was throttled
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Too Many Requests
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header