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.

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 object
  
  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 with this reference and scheme, all information in this field will be ignored except for the debtor IBAN which needs to be the same as the one in the existing mandate. Providing a different IBAN will produce a 400 error with the code outgoing_collection_mandate_iban_mismatch.
  
  Hide debtor attributes Show debtor attributes object
  
  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 debtor's bank — more specifically, its BIC — is located in a non-EEA SEPA country or territory.
  
  Hide address attributes Show address attributes object
  
  street string Required
  
  Name of the street.
  
  Minimum length is 1, maximum length is 256.
  
  building_number string
  
  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}$.
  
  contract_reference string
  
  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 to all involved parties.
  
  Minimum length is 1, maximum length is 140.
- end_to_end_id string
  
  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 string
  
  Internal note attached to this collection, visible only in your Memo Bank workspace.
  
  Minimum length is 1, maximum length is 140.
- custom_id string
  
  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 string
  
  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 \
 --request POST 'https://api.memo.bank/v2/collections/bulks' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"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 examples

{
  "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"
}