Memo Bank Mandate signature requests API

openapi: 3.2.0
info:
  title: Memo Bank Mandate signature requests API
  description: '**Welcome!** You can use our Premium Bank API to check your company’s accounts, fetch your transactions, make SEPA transfers, initiate SEPA direct debit collections, create virtual IBANs, and access most of Memo Bank features.

    > info

    > If you are a **third-party payment service provider** complying with PSD2, you may be more interested in our NextGenPSD2 API.'
  version: '2.0'
servers:
- url: https://api.memo.bank
  description: Production
- url: https://api.sandbox.memo.bank
  description: Sandbox
tags:
- name: Mandate signature requests
  description: Mandate signature requests are a way to prepare and send collection mandates for signature. The mandate debtor receives an email with a link so they can complete and sign the mandate. Once it has been signed, the resulting mandate becomes immediately available for making collections. Dedicated webhook events can be used to track mandate signature requests state changes.
paths:
  /v2/mandate_signature_requests:
    get:
      tags:
      - Mandate signature requests
      summary: List the mandate signature requests
      description: '**Scope**: `mandate-signature-requests:read`'
      operationId: listMandateSignatureRequests
      parameters:
      - name: status
        in: query
        description: Filter mandate signature requests by status.
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
            enum:
            - sent
            - expired
            - completed
      - name: page
        in: query
        description: Index of the requested page. Deprecated, use `page_token` instead.
        deprecated: true
        schema:
          minimum: 1
          type: integer
          format: int32
      - name: page_token
        in: query
        description: Token used to fetch a specific page, as returned by the `next_page_token` or `prev_page_token` field of a previous response. Mutually exclusive with `page`.
        schema:
          type: string
      - name: size
        in: query
        description: Number of elements per page in response.
        schema:
          maximum: 100
          minimum: 1
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MandateSignatureRequestPage'
      security:
      - JWT: []
    post:
      tags:
      - Mandate signature requests
      summary: Create a new mandate signature request
      description: 'An email will be sent to the mandate debtor so they can complete and sign the collection mandate.


        **Scope**: `mandate-signature-requests:write`'
      operationId: createMandateSignatureRequest
      requestBody:
        content:
          application/json:
            schema:
              type: object
              discriminator:
                propertyName: mode
                mapping:
                  email: '#/components/schemas/CreateEmailMandateSignatureRequest'
                  redirect: '#/components/schemas/CreateRedirectMandateSignatureRequest'
              oneOf:
              - $ref: '#/components/schemas/CreateEmailMandateSignatureRequest'
              - $ref: '#/components/schemas/CreateRedirectMandateSignatureRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                required:
                - debtor_email
                - id
                - is_deleted
                - language
                - mode
                - reference
                - scheme
                - status
                type: object
                properties:
                  reference:
                    pattern: ^[A-Za-z0-9+?/\-:().,'\s]{1,35}$
                    type: string
                    description: The unique mandate reference.
                    example: ABC123DEF
                  id:
                    type: string
                    description: ID of the mandate signature request.
                    format: uuid
                    example: 61b05c4f-3f72-4951-8c30-a2a9faaa5184
                  scheme:
                    type: string
                    description: The mandate scheme.
                    example: core
                    enum:
                    - b2b
                    - core
                  language:
                    type: string
                    description: The language used for the email and signature page for the debtor.
                    example: french
                    default: french
                    enum:
                    - french
                    - english
                  status:
                    type: string
                    description: Current status of the mandate signature request.
                    example: sent
                    enum:
                    - sent
                    - expired
                    - completed
                  mode:
                    type: string
                    description: Define the delivery strategy of this signature request.
                    enum:
                    - email
                    - redirect
                  contract_reference:
                    type: string
                    description: The contract reference attached to the mandate. This is optional metadata.
                    example: CUST-1234
                  is_deleted:
                    type: boolean
                    description: Whether or not this mandate signature request has been deleted.
                    example: false
                  debtor:
                    $ref: '#/components/schemas/MandateSignatureRequestDebtor'
                  debtor_email:
                    type: string
                    description: The email address of the debtor.
                    example: foo@bar.com
                discriminator:
                  propertyName: mode
                  mapping:
                    email: '#/components/schemas/EmailMandateSignatureRequest'
                    redirect: '#/components/schemas/RedirectMandateSignatureRequest'
                oneOf:
                - $ref: '#/components/schemas/EmailMandateSignatureRequest'
                - $ref: '#/components/schemas/RedirectMandateSignatureRequest'
      security:
      - JWT: []
  /v2/mandate_signature_requests/{id}:
    get:
      tags:
      - Mandate signature requests
      summary: Get a mandate signature request
      description: '**Scope**: `mandate-signature-requests:read`'
      operationId: getMandateSignatureRequest
      parameters:
      - name: id
        in: path
        description: ID of the mandate signature request.
        required: true
        schema:
          type: string
          format: uuid
        example: 45195a6f-daa8-4bc1-9ac4-3979e72bd89d
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                required:
                - debtor_email
                - id
                - is_deleted
                - language
                - mode
                - reference
                - scheme
                - status
                type: object
                properties:
                  reference:
                    pattern: ^[A-Za-z0-9+?/\-:().,'\s]{1,35}$
                    type: string
                    description: The unique mandate reference.
                    example: ABC123DEF
                  id:
                    type: string
                    description: ID of the mandate signature request.
                    format: uuid
                    example: 61b05c4f-3f72-4951-8c30-a2a9faaa5184
                  scheme:
                    type: string
                    description: The mandate scheme.
                    example: core
                    enum:
                    - b2b
                    - core
                  language:
                    type: string
                    description: The language used for the email and signature page for the debtor.
                    example: french
                    default: french
                    enum:
                    - french
                    - english
                  status:
                    type: string
                    description: Current status of the mandate signature request.
                    example: sent
                    enum:
                    - sent
                    - expired
                    - completed
                  mode:
                    type: string
                    description: Define the delivery strategy of this signature request.
                    enum:
                    - email
                    - redirect
                  contract_reference:
                    type: string
                    description: The contract reference attached to the mandate. This is optional metadata.
                    example: CUST-1234
                  is_deleted:
                    type: boolean
                    description: Whether or not this mandate signature request has been deleted.
                    example: false
                  debtor:
                    $ref: '#/components/schemas/MandateSignatureRequestDebtor'
                  debtor_email:
                    type: string
                    description: The email address of the debtor.
                    example: foo@bar.com
                discriminator:
                  propertyName: mode
                  mapping:
                    email: '#/components/schemas/EmailMandateSignatureRequest'
                    redirect: '#/components/schemas/RedirectMandateSignatureRequest'
                oneOf:
                - $ref: '#/components/schemas/EmailMandateSignatureRequest'
                - $ref: '#/components/schemas/RedirectMandateSignatureRequest'
      security:
      - JWT: []
    delete:
      tags:
      - Mandate signature requests
      summary: Delete a mandate signature request
      description: 'A mandate signature request can be deleted in case the collection mandate no longer needs to be completed and signed. This action is only possible while the mandate signature request is not in `completed` status.


        **Scope**: `mandate-signature-requests:write`'
      operationId: deleteMandateSignatureRequest
      parameters:
      - name: id
        in: path
        description: ID of the mandate signature request.
        required: true
        schema:
          type: string
          format: uuid
        example: 45195a6f-daa8-4bc1-9ac4-3979e72bd89d
      responses:
        '200':
          description: OK
      security:
      - JWT: []
  /v2/mandate_signature_requests/{id}/renewals:
    post:
      tags:
      - Mandate signature requests
      summary: Renew a mandate signature request
      description: 'A mandate signature request can be renewed in case it has expired before the collection mandate could be completed and signed. This action is only possible while the mandate signature request is in `expired` status.


        **Scope**: `mandate-signature-requests:write`'
      operationId: renewMandateSignatureRequest
      parameters:
      - name: id
        in: path
        description: ID of the mandate signature request.
        required: true
        schema:
          type: string
          format: uuid
        example: 45195a6f-daa8-4bc1-9ac4-3979e72bd89d
      responses:
        '200':
          description: OK
      security:
      - JWT: []
components:
  schemas:
    Address:
      required:
      - city
      - country
      - postal_code
      - street
      type: object
      properties:
        street:
          type: string
          description: Debtor's street name.
          example: 1 rue Rivoli
        postal_code:
          type: string
          description: Debtor's postal code.
          example: '75004'
        city:
          type: string
          description: Debtor's city.
          example: Paris
        country:
          type: string
          description: Debtor's country code.
          example: FR
      description: Debtor's address.
    CreateMandateSignatureRequestDiscriminator:
      required:
      - debtor_email
      - mode
      - reference
      - scheme
      type: object
      properties:
        reference:
          pattern: ^[A-Za-z0-9+?/\-:().,'\s]{1,35}$
          type: string
          description: The unique mandate reference.
          example: ABC123DEF
        scheme:
          type: string
          description: The mandate scheme.
          example: core
          enum:
          - b2b
          - core
        language:
          type: string
          description: The language used for the email and signature page for the debtor. This is optional.
          example: french
          default: french
          enum:
          - french
          - english
        mode:
          type: string
          description: Define the delivery strategy of this signature request.
          enum:
          - email
          - redirect
        contract_reference:
          maxLength: 256
          minLength: 1
          type: string
          description: The contract reference that will be attached to the mandate. This is optional metadata.
          example: CUST-1234
        debtor:
          $ref: '#/components/schemas/CreateMandateSignatureRequestDebtor'
        debtor_email:
          maxLength: 256
          minLength: 1
          pattern: ^(?!.*\.\.)[a-zA-Z0-9._%+-]{1,250}@[a-zA-Z0-9.-]{2,250}\.[a-zA-Z]{2,63}$
          type: string
          description: The email address of the debtor.
          example: foo@bar.com
    CreateEmailMandateSignatureRequest:
      required:
      - debtor_email
      - mode
      - reference
      - scheme
      type: object
      allOf:
      - $ref: '#/components/schemas/CreateMandateSignatureRequestDiscriminator'
      - type: object
        properties:
          email_custom_message:
            maxLength: 3000
            minLength: 1
            pattern: ^[a-zA-Zà-üÀ-Ü0-9€@&;.,?!()+\-'’"\s]*$
            type: string
            description: Custom text message that will be included in the email sent to the debtor.
            example: Hi John Doe, here's a collection mandate to sign.
    MandateSignatureRequestPage:
      required:
      - has_next
      - has_prev
      - results
      type: object
      properties:
        results:
          type: array
          description: Elements of the page.
          items:
            type: object
            discriminator:
              propertyName: mode
              mapping:
                email: '#/components/schemas/EmailMandateSignatureRequest'
                redirect: '#/components/schemas/RedirectMandateSignatureRequest'
            oneOf:
            - $ref: '#/components/schemas/EmailMandateSignatureRequest'
            - $ref: '#/components/schemas/RedirectMandateSignatureRequest'
        has_prev:
          type: boolean
          description: Flag indicating if there is a previous page. Deprecated, use `prev_page_token` instead.
          deprecated: true
        has_next:
          type: boolean
          description: Flag indicating if there is a next page. Deprecated, use `next_page_token` instead.
          deprecated: true
        next_page_token:
          type: string
          description: Token to fetch the next page, to be passed in subsequent requests as the `page_token` query parameter. `null` when there is no next page.
          nullable: true
          example: eyJwIjozfQ
        prev_page_token:
          type: string
          description: Token to fetch the previous page, to be passed in subsequent requests as the `page_token` query parameter. `null` when there is no previous page.
          nullable: true
          example: eyJwIjoxfQ
    CreateMandateSignatureRequestDebtorAddress:
      type: object
      properties:
        street:
          maxLength: 256
          minLength: 1
          type: string
          description: Name of the street.
          example: rue de la Boétie
        postal_code:
          maxLength: 256
          minLength: 1
          type: string
          description: Postal or zip code.
          example: '75008'
        city:
          maxLength: 256
          minLength: 1
          type: string
          description: Name of the city.
          example: Paris
        country:
          pattern: ^[A-Z]{2}$
          type: string
          description: ISO3166-1 alpha-2 country code.
          example: FR
      description: Debtor address used to prefill the signing form. All fields are optional.
    EmailMandateSignatureRequest:
      required:
      - debtor_email
      - id
      - is_deleted
      - language
      - mode
      - reference
      - scheme
      - status
      type: object
      allOf:
      - $ref: '#/components/schemas/MandateSignatureRequestDiscriminator'
      - type: object
        properties:
          email_custom_message:
            type: string
            description: Custom text message included in the email sent to the debtor.
            example: Hi John Doe, here's a collection mandate to sign.
    MandateSignatureRequestDebtor:
      required:
      - iban
      - name
      type: object
      properties:
        name:
          type: string
          description: Debtor's name.
          example: John Doe
        iban:
          type: string
          description: Debtor's IBAN.
          example: FR2512739000308553756377J95
        address:
          $ref: '#/components/schemas/Address'
      description: Debtor information filled when the request was signed. This is available when the request is completed.
    CreateRedirectMandateSignatureRequest:
      required:
      - debtor_email
      - mode
      - redirect_uri
      - reference
      - scheme
      type: object
      allOf:
      - $ref: '#/components/schemas/CreateMandateSignatureRequestDiscriminator'
      - type: object
        properties:
          redirect_uri:
            maxLength: 2048
            minLength: 1
            pattern: ^https://[a-zA-Z0-9.\-]{1,255}(:[0-9]{1,5})?(/[^\s]*)?$
            type: string
            description: URI to redirect the debtor after signing. Must be an absolute HTTPS URL.
            example: https://example.com/signed
    MandateSignatureRequestDiscriminator:
      required:
      - debtor_email
      - id
      - is_deleted
      - language
      - mode
      - reference
      - scheme
      - status
      type: object
      properties:
        reference:
          pattern: ^[A-Za-z0-9+?/\-:().,'\s]{1,35}$
          type: string
          description: The unique mandate reference.
          example: ABC123DEF
        id:
          type: string
          description: ID of the mandate signature request.
          format: uuid
          example: 61b05c4f-3f72-4951-8c30-a2a9faaa5184
        scheme:
          type: string
          description: The mandate scheme.
          example: core
          enum:
          - b2b
          - core
        language:
          type: string
          description: The language used for the email and signature page for the debtor.
          example: french
          default: french
          enum:
          - french
          - english
        status:
          type: string
          description: Current status of the mandate signature request.
          example: sent
          enum:
          - sent
          - expired
          - completed
        mode:
          type: string
          description: Define the delivery strategy of this signature request.
          enum:
          - email
          - redirect
        contract_reference:
          type: string
          description: The contract reference attached to the mandate. This is optional metadata.
          example: CUST-1234
        is_deleted:
          type: boolean
          description: Whether or not this mandate signature request has been deleted.
          example: false
        debtor:
          $ref: '#/components/schemas/MandateSignatureRequestDebtor'
        debtor_email:
          type: string
          description: The email address of the debtor.
          example: foo@bar.com
    CreateMandateSignatureRequestDebtor:
      type: object
      properties:
        name:
          maxLength: 256
          minLength: 1
          type: string
          description: Name of the debtor.
          example: John Doe
        iban:
          pattern: ^[A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}$
          type: string
          description: IBAN of the debtor.
          example: FR2512739000308553756377J95
        address:
          $ref: '#/components/schemas/CreateMandateSignatureRequestDebtorAddress'
      description: Debtor data used to prefill the signing form. All fields are optional; the debtor can still edit them before signing.
    RedirectMandateSignatureRequest:
      required:
      - debtor_email
      - id
      - is_deleted
      - language
      - mode
      - redirect_uri
      - reference
      - scheme
      - signature_url
      - status
      type: object
      allOf:
      - $ref: '#/components/schemas/MandateSignatureRequestDiscriminator'
      - type: object
        properties:
          signature_url:
            type: string
            description: URL the debtor must visit to sign the mandate.
            example: https://client.memo.bank/mandate/abc123
          redirect_uri:
            type: string
            description: URL the debtor is redirected to after signing.
            example: https://example.com/signed
x-topics:
- title: Getting started
  content: 'To get started with our Premium Bank API, talk to your banker first. He or she needs  to activate the API feature on your Memo Bank workspace.


    Once your banker has granted you API access, you can then set up your authentication using our web interface. To do so, navigate to the  [`API`](https://client.memo.bank/api) section of your Memo Bank workspace.


    Owners and administrators can create applications and manage their permissions. They can also invite collaborators to an application, allowing them to manage certificates, IP allow-lists, and  webhooks.


    Once an application and a certificate have been created, you will have  three pieces of information allowing you to authenticate requests on  the API:

    1. a **certificate** and its SHA256 thumbprint;

    2. a **secret code**;

    3. a cryptographic **private key**.

    '
- title: Authentication
  content: "Our authentication is based on JSON Web Token ([JWT](https://datatracker.ietf.org/doc/html/rfc7519)) and JSON Web Signature ([JWS](https://datatracker.ietf.org/doc/html/rfc7515)).\n\nRegardless of which programming language you are using, there should be [a library](https://jwt.io/libraries) to handle the cryptographic part for you. All you need is to provide the correct header and payload claims. \n\n**In the JWT header:**\n- `alg` must be `RS256`, as we require an RSA-SHA256 signature. \n- `typ` must be `JWT`.\n- `x5t#S256` is the SHA256 thumbprint of the certificate, which you can find in the user interface.\n\n**In the JWT payload:**\n- `sub` must be the request method, followed by a space and the full path, including query parameters.\n- `aud` must be the domain to which you are making the request, e.g., `api.memo.bank`.\n- `iat` must be the timestamp at which you created the token. Note that we accept only a 5-second difference from the server time to mitigate clock skew.\n- `jti` must be a unique identifier for the token. It must be different for each request and follow the UUID format.\n- `sec` must be the secret information you obtained during the setup process in the user interface. This is a custom claim not covered by the JWT specification.\n- `dig#S256` must contain the base64url-encoded SHA-256 hash of the body (`base64url(sha256(body))`, see [`base64url`](https://datatracker.ietf.org/doc/html/rfc7515#appendix-C)). It must be provided only if the request has a body; for example, it is not necessary for `GET` requests. This is a custom claim not covered by the JWT specification.\n\nThe JWT must then be **signed with the private key** you generated during the setup (see [Getting started](#topic-getting-started)), and included in the HTTP headers of the request, as a standard bearer token `Authorization: Bearer <token>`.\n"
  example: "_Example JWT header and payload_\n```json\n{\n  \"alg\": \"RS256\",\n  \"typ\": \"JWT\",\n  \"x5t#S256\": \"3A14ZcxIaasp4RHaYReL7wevm3oDzn7ZqmgqScCMY74\"\n}\n{\n  \"sub\": \"POST /v1/transfers\",\n  \"aud\": \"api.memo.bank\",\n  \"iat\": 1657055009,\n  \"jti\": \"5525620b-9dcd-4562-8c6c-60984f46cb48\",\n  \"sec\": \"a2029d646c94406d2945b7a2b31e4fb3ff09a6d0ae29144380775b5471c4e846\",\n  \"dig#S256\": \"lW6N_kO2gPMsMkzXyn028gWwrnaN0kJaiy7FMJcR0Ek\"\n}\n```\n"
- title: Idempotent requests
  content: "Our Premium Bank API supports **idempotency** to safely retry requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a transfer does not go through due to a network connection error, you can retry the request with the same  idempotency key to guarantee that only the single transfer originally  attempted is created.\n\nTo perform an idempotent request, provide an additional `Idempotency-Key` **request header**. We recommend using a **V4 UUID**. If the API call fails with a network error or responds with a  `5XX`, `409`, or `429` status code, we expect the caller to perform retries with the same `Idempotency-Key` header until it responds differently. For any other response code, especially other `4XX` errors, there is no point in attempting retries, as we will always return the same result. \n\nWhen a previous response is replayed, the response includes an  additional HTTP header: `Idempotent-Replayed: true`.\n\nIf an original request is still being processed when an idempotency key is reused, the API will return a `409 Conflict` error  (which is safe to retry).\n\nSubsequent requests must be identical to the original request, or the API  will return a `422 Unprocessable Entity` error. We do not support setting  an idempotency key on `GET` and `DELETE` requests, as these requests are inherently idempotent.\n"
  example: "```\ncurl --request POST \\\n  --url https://api.memo.bank/v1/transfers \\\n  --header 'Authorization: Bearer ***' \\\n  --header 'Idempotency-Key: 19b390d1-e7d4-4e27-abe2-49cac9b41ba1' \\\n  --header 'Content-Type: application/json' \\\n  --data '{...}'\n```\n"
- title: Errors
  content: 'Our Premium Bank API uses standard HTTP response codes to indicate the success or failure of requests. Codes in the `2xx` range indicate success; codes in the `4xx` and `5xx` ranges indicate errors. The format of error messages is unified and can be distinguished by their `code` key. The `message` provides a plain English explanation of the problem.

    '
  example: "```json\n{\n  \"code\": \"error_code\",\n  \"message\": \"Example error message.\",\n}\n```\n"
- title: Versioning and backwards compatibility
  content: 'Our Premium Bank API is versioned by path (`/v1/...`). When we introduce breaking changes, we will increase this version number. We will, of course, continually make backward-compatible changes without increasing the version number.


    Examples of changes we do **not** consider breaking include:

    * Adding new API resources.

    * Adding new optional request parameters to existing API methods.

    * Adding new properties to existing API responses. We will occasionally move response fields in the API and will continue to return the existing field in its previous location while removing it from this documentation.

    * Changing the order of properties in existing API responses.

    * Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings. Strings that are marked as const or enum in this documentation will not change.

    * Adding new `EventType` or `ResourceType` enum values for webhooks.

    * Adding new `TransactionSource` enum values for transactions.

    '
- title: Rate limiting
  content: "We enforce a rate limit on the number of HTTP requests that can be made in a  given period. When the limit is reached, our Premium Bank API will return a `429 Too Many Requests` error.\n\nTo allow you to handle this rate limiting programmatically, the following headers are sent with every response: \n- `RateLimit-Limit`: total number of available requests between two quota resets;\n- `RateLimit-Remaining`: number of available requests until the quota is reset;\n- `RateLimit-Reset`: time remaining (in seconds) until the quota is reset.\n"
- title: API recipes
  content: 'While our OpenAPI specification provides a comprehensive reference for the Memo Bank API, we''ve created  API recipes to give you practical, hands-on guides for common use cases. These recipes offer step-by-step  examples to help you quickly integrate and leverage our API. You can find them here:  [API Premium - Memo Bank](https://aide.memo.bank/category/349-api)

    '


# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/memo-bank/refs/heads/main/openapi/memo-bank-mandate-signature-requests-api-openapi.yml