Schedule a SEPA Direct Debit collection

POST /v2/collections

This endpoint allows you to schedule a SEPA Direct Debit collection to be credited on one of your accounts.

application/json

Body Required

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.

Additional properties are allowed.
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.
  
  Additional properties are allowed.
  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.
  
  Additional properties are allowed.
  
  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 256.
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 256.
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 collection.
- reference string(uuid) Required
  
  Unique reference, can be used to correlate with the resulting Transaction.
- amount integer(int64) Required
  
  The collection amount, in cents.
- currency string Required
  
  Currency of the amount, in ISO 4217 format.
- mandate object Required
  
  The SEPA Direct Debit collection mandate used.
  
  Additional properties are allowed.
  
  Hide mandate attributes Show mandate attributes object
  
  reference string Required
  
  The unique mandate reference.
  
  scheme string Required
  
  The mandate scheme.
  
  Values are b2b or core.
- scheduled_date string(date) Required
  
  The collection scheduled date, in ISO8601 format.
- local_iban string Required
  
  IBAN credited or to be credited. It can be the main IBAN of an account or a virtual IBAN.
- account_id string(uuid)
  
  ID of the account this collection belongs to, it can be missing while we process it according to the local IBAN.
- status string Required
  
  Current status of the collection.
  
  Values are pending, scheduled, confirmed, canceled, or failed.
- failure_code string
  
  Code that represents the failure reason when the collection has failed:
  
  invalid_mandate_iban: The mandate's IBAN is invalid.
  
  unreachable_mandate_iban: The mandate's IBAN is unreachable for the given scheme.
  
  missing_debtor_address: The debtor address is missing and required for non-EEA SEPA countries.
  
  core_limit_exceeded: The limit for CORE collections was exceeded.
  
  debtor_refusal: The debtor has refused the collection.
  
  debtor_bank_account_closed: The debtor's bank account is closed.
  
  debtor_bank_insufficient_funds: The debtor's bank account has insufficient funds.
  
  debtor_bank_error: The debtor's bank sent us an error.
  
  debtor_bank_invalid_bank_details: The debtor's bank account does not exist or no longer exists.
  
  debtor_bank_refusal: The debtor's bank has refused the collection.
  
  intermediary_system_error: The interbank network sent us an error.
  
  memo_error: Something went wrong on our side.
  
  memo_refusal: We had to reject the collection.
  
  execution_failure: Other or undefined pre-settlement execution failures.
  
  The following codes can only be present on collections initiated as part of a bulk. When initiating a single collection, those codes will be returned as an error response and the collection won’t be created at all:
  
  account_cannot_receive_collections: The account cannot receive collections.
  
  current_account_not_found: The provided local IBAN does not exist.
  
  creditor_is_saving_account: The provided local IBAN is a Booster account.
  
  no_sepa_creditor_identifier: You need to setup a SEPA creditor identifier with your banker.
  
  mandate_info_missing: New mandate information must be complete.
  
  mandate_iban_mismatch: The mandate reference already exists but with a different IBAN.
  
  collection_to_same_account: The local IBAN and the debtor IBAN can not be the same.
  
  Values are invalid_mandate_iban, unreachable_mandate_iban, missing_debtor_address, core_limit_exceeded, execution_failure, current_account_not_found, no_sepa_creditor_identifier, creditor_is_saving_account, mandate_info_missing, mandate_iban_mismatch, collection_to_same_account, debtor_refusal, debtor_bank_account_closed, debtor_bank_error, debtor_bank_insufficient_funds, debtor_bank_invalid_bank_details, debtor_bank_refusal, intermediary_system_error, memo_error, memo_refusal, or account_cannot_receive_collections.
- message string
  
  Message attached to this collection, visible to all involved parties.
- 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.
- internal_note string
  
  Internal note attached to this collection, visible only in your Memo Bank workspace.
- custom_id string
  
  Custom identifier attached to the transaction resulting from this collection. It is not transmitted nor visible in your Memo Bank workspace. It can only be retrieved or used to search for transactions via Memo Bank API.
- custom_metadata string
  
  Custom metadata attached to the transaction resulting from this collection. It is not transmitted nor visible in your Memo Bank workspace and can only be retrieved via API.

POST /v2/collections

curl \
 --request POST 'https://api.memo.bank/v2/collections' \
 --header "Content-Type: application/json" \
 --data '{"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

{
  "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": "61b05c4f-3f72-4951-8c30-a2a9faaa5184",
  "reference": "ab004cfc-99fb-4ba9-bc9c-70982f853cb1",
  "amount": 500,
  "currency": "EUR",
  "mandate": {
    "reference": "ABC123DEF",
    "scheme": "core"
  },
  "scheduled_date": "2022-12-05",
  "local_iban": "FR6430003000509825397888D64",
  "account_id": "708683cb-60f6-464a-a62f-be2e339c34aa",
  "status": "failed",
  "failure_code": "invalid_mandate_iban",
  "message": "invoice no12345",
  "end_to_end_id": "b0bfb42baa2642c2af0ca3e880fcd590",
  "internal_note": "phone bill",
  "custom_id": "637406efda8534de8c0e",
  "custom_metadata": "This is some metadata"
}