Create bulk collections

POST /v2/collections/bulks

This endpoint allows to create up to 5000 collections with a single call. It acts exactly as if you called the POST /v2/collections endpoint 5000 times yourself, except you don't need to worry about rate limiting. It also allows you to get an aggregated state for this bulk.

This endpoint does not perform the collections synchronously, a 200 OK response means the bulk will be handled in the near future. You can either poll the GET endpoint or use the webhooks to follow its progress.

Note that the completion of a bulk does not mean all collections are settled, it only means the collections were initiated (the equivalent of a call to POST /v2/collections).

application/json

Body Required

  • collections array[object] Required

    Collection creations to execute. There should not be more than 5000 collections in a single bulk, and there should be at least one.

    Hide collections attributes Show collections attributes object
    • amount integer(int64) Required

      Amount to be collected, in cents. The currency is always EURO.

      Minimum value is 1.

    • mandate object Required

      The SEPA Direct Debit collection mandate to be used.

      Hide mandate attributes Show mandate attributes
      • reference string Required

        The unique mandate reference.

        Format should match the following pattern: [A-Za-z0-9+?/\-:().,'\s]{1,35}.

      • scheme string Required

        The mandate scheme.

        Values are b2b or core.

      • signature_date string(date)

        The mandate signature date, in ISO8601 format. The date must not be in the future. This field is only required in case of a new mandate. If there is an existing mandate matching the scheme and with the same reference, this field will be ignored.

      • debtor object

        The debtor associated with this mandate.This field is only required in case of a new mandate. If there is an existing mandate matching the scheme and with the same reference, this field will be ignored.

        Hide debtor attributes Show debtor attributes
        • name string Required

          Name of the debtor.

          Minimum length is 1, maximum length is 256.

        • iban string Required

          IBAN of the debtor.

          Format should match the following pattern: [A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}.

        • address object

          The debtor's address. Mandatory only when the the debtor's bank — more specifically, its BIC — is located in a non-EEA SEPA country or territory.

          Hide address attributes Show address attributes
          • street string Required

            Name of the street.

            Minimum length is 1, maximum length is 256.

          • Number of the building or house.

            Minimum length is 1, maximum length is 256.

          • postal_code string Required

            Postal or zip code.

            Minimum length is 1, maximum length is 256.

          • city string Required

            Name of the city.

            Minimum length is 1, maximum length is 256.

          • country string Required

            ISO3166-1 alpha-2 country code.

            Format should match the following pattern: [A-Z]{2}.

      • The contract reference attached to this mandate. This is optional metadata.If there is an existing mandate matching the scheme and with the same reference, this field will be ignored when provided.

        Minimum length is 1, maximum length is 256.

    • scheduled_date string(date) Required

      The ISO8601 formatted date on which the direct debit collection will be submitted. This date must not be in the past. If your direct debit is scheduled to be submitted on a non-business day, it will be effectively submitted on the next business day. The execution will then happen on the following business day. For example, a direct debit scheduled on a Saturday will be submitted on the following Monday and executed on the Tuesday (assuming that both week days are business days).

    • local_iban string Required

      Existing IBAN to be credited. It can be the main IBAN of an account or a virtual IBAN.

      Format should match the following pattern: [A-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}.

    • message string

      Message attached to this collection, visible by all involved parties.

      Minimum length is 1, maximum length is 256.

    • Unique identification to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. It can be used for reconciliation or to link tasks relating to the transaction.

      Minimum length is 1, maximum length is 35. Format should match the following pattern: [a-zA-Z0-9\-\?\:\(\)\.\,\'\+\ ]{1,35}.

    • Internal note attached to this collection, visible only in your Memo Bank workspace.

      Minimum length is 1, maximum length is 256.

    • Custom identifier that will be attached to the transaction resulting from this collection. It will not be transmitted nor visible in your Memo Bank workspace. It can only be retrieved or used to search for transactions via Memo Bank API.

      Minimum length is 1, maximum length is 256.

    • Custom metadata that will be attached to the transaction resulting from this collection. It will not be transmitted nor visible in your Memo Bank workspace and can only be retrieved via API.

      Minimum length is 1, maximum length is 2048.

Responses

  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • id string(uuid) Required

      ID of the bulk.

    • collections_total integer(int32) Required

      Total number of collections in the bulk.

    • collections_confirmed integer(int32) Required

      Number of collections that were processed and confirmed.

    • collections_canceled integer(int32) Required

      Number of collections canceled before processing.

    • collections_failed integer(int32) Required

      Number of collections that were processed and failed.

    • status string Required

      Aggregated status of the bulk.

      Values are pending or completed.

POST /v2/collections/bulks
curl \
 -X POST https://api.memo.bank/v2/collections/bulks \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"collections":[{"amount":500,"mandate":{"reference":"ABC123DEF","scheme":"core","signature_date":"2022-12-01","debtor":{"name":"John Doe","iban":"FR2512739000308553756377J95","address":{"street":"rue de la Boétie","building_number":"42","postal_code":"75008","city":"Paris","country":"FR"}},"contract_reference":"CUST-1234"},"scheduled_date":"2022-12-05","local_iban":"FR6430003000509825397888D64","message":"invoice no12345","end_to_end_id":"b0bfb42baa2642c2af0ca3e880fcd590","internal_note":"phone bill","custom_id":"637406efda8534de8c0e","custom_metadata":"This is some metadata"}]}'
Request example
{
  "collections": [
    {
      "amount": 500,
      "mandate": {
        "reference": "ABC123DEF",
        "scheme": "core",
        "signature_date": "2022-12-01",
        "debtor": {
          "name": "John Doe",
          "iban": "FR2512739000308553756377J95",
          "address": {
            "street": "rue de la Boétie",
            "building_number": "42",
            "postal_code": "75008",
            "city": "Paris",
            "country": "FR"
          }
        },
        "contract_reference": "CUST-1234"
      },
      "scheduled_date": "2022-12-05",
      "local_iban": "FR6430003000509825397888D64",
      "message": "invoice no12345",
      "end_to_end_id": "b0bfb42baa2642c2af0ca3e880fcd590",
      "internal_note": "phone bill",
      "custom_id": "637406efda8534de8c0e",
      "custom_metadata": "This is some metadata"
    }
  ]
}
Response examples (200)
{
  "id": "fe98f29d-5165-45ff-83f9-d7aa83e970b5",
  "collections_total": 3000,
  "collections_confirmed": 1552,
  "collections_canceled": 2,
  "collections_failed": 57,
  "status": "pending"
}