Direct Debit Webhooks

Direct Debit webhooks are triggered when we receive the status of a requested direct debit collection from a financial institution. This includes the initiation of a direct debit collection, the failure of a direct debit for whatever reason, or the successful collection when the money lands in the creditor account.

Please note that it might take T + 2 days to confirm that a direct debit collection has been successful.

We will send you all the direct debit details so that you have maximum context for powering business processes.

Event Type	Description
direct_debit_created	The direct debit has been created by a user.
direct_debit_sent	The direct debit has been sent to the financial institution.
direct_debit_accepted	A direct debit has been accepted by the bank and it is pending collection.
direct_debit_completed	The direct debit has been executed by the bank.
direct_debit_failed	The direct debit failed to be created due to technical issues, insufficient funds in the debtor account.
direct_debit_rejected	The direct debit has been rejected by the bank due to incorrect information, or there is an issue with the mandate.
direct_debit_cancelled	The direct debit has been cancelled by a user.
direct_debit_charge_back_requested	The debtor has requested a reversal of the direct debit.

Example notification:

{
  "id": "dir_ndp7XjILxS8fDvjz7akVOJ7mgV",
  "entity_id": "ent_bjec24xmzi4tr4g7m4lliotzz4",
  "mandate_id": "man_brchlaugcdi4sldmbdlbcsaclu"
  "amount": {
    "value": "100",
    "currency": "GBP"
  },
  "reference": "reference123",
  "due_date": "2022-11-01",
  "status": "completed",
  "created_at": "2023-09-19T08:36:20.126Z",
  "created_by": "usr_ayd8lpm5z2b0xt6gwqo9yr4afc",
  "reason": "xyz"
}

Testing Various Statuses

You can test different payment statuses received from webhooks by creating Payees with special remitter names and initiating Direct Debits against the Test Bank.

Testing rejected payment status

To test a payment being rejected with the Test Bank. Create a Payee with the name Test.Status.Reject. Then use that payee id when initiating a direct debit. The webhook response will look like the following.

{
  "category": "direct_debits",
  "data": {
    "amount": {
      "currency": "GBP",
      "value": "20"
    },
    "created_at": "2024-05-22T09:44:01.021Z",
    "created_by": "usr_a4qesp3t445bkmrnz2uynigq6u",
    "creditor_id": "acc_ar56flcnmvha7jadyqnn3bcbxa",
    "debtor_id": "pye_ans7bmmmovhx5cyhguiunjakdy",
    "due_date": "2024-05-28",
    "entity_id": "ent_b62z7kfws3ykjsz64vh3vnjnt4",
    "id": "ddi_abki7xfye4lzgrcglxmpvqf75m",
    "mandate_id": "man_brchlaugcdi4sldmbdlbcsaclu",
    "organization_id": "org_b256o3j6lpbojoljbvdoixyaaa",
    "reason": "Batch accepted and processed by the bank",
    "reference": "dd-ref-05",
    "status": "failed",
    "updated_at": "2024-05-29T10:05:44.261Z",
    "updated_by": "usr_bqg52gc7rgoqs3uuz2b6vak2f4"
  },
  "id": "whk_auzy4shmec6caq2nejwflx36ke",
  "idempotency_key": "31fde8758016471eb15f73d4a37c3943",
  "organization_id": "org_b256o3j6lpbojoljbvdoixyaaa",
  "request_id": "3a92a8cf0e734a5c80440c5dc92c2466",
  "timestamp": "2024-05-29T10:05:44.499Z",
  "type": "direct_debit_failed"
}

Testing Pending payment status

To test a payment being accepted but not yet comleted with the Test Bank. Create a Payee with the name Test.Status.Pending. Then use that payee id when initiating a direct debit. The webhook response will look like the following.

{
  "category": "direct_debits",
  "data": {
    "amount": {
      "currency": "GBP",
      "value": "20"
    },
    "created_at": "2024-05-22T09:44:01.021Z",
    "created_by": "usr_a4qesp3t445bkmrnz2uynigq6u",
    "creditor_id": "acc_ar56flcnmvha7jadyqnn3bcbxa",
    "debtor_id": "pye_ans7bmmmovhx5cyhguiunjakdy",
    "due_date": "2024-05-28",
    "entity_id": "ent_b62z7kfws3ykjsz64vh3vnjnt4",
    "id": "ddi_abki7xfye4lzgrcglxmpvqf75m",
    "mandate_id": "man_brchlaugcdi4sldmbdlbcsaclu",
    "organization_id": "org_b256o3j6lpbojoljbvdoixyaaa",
    "reason": "Batch accepted and processed by the bank",
    "reference": "dd-ref-05",
    "status": "accepted",
    "updated_at": "2024-05-29T10:05:44.261Z",
    "updated_by": "usr_bqg52gc7rgoqs3uuz2b6vak2f4"
  },
  "id": "whk_auzy4shmec6caq2nejwflx36ke",
  "idempotency_key": "31fde8758016471eb15f73d4a37c3943",
  "organization_id": "org_b256o3j6lpbojoljbvdoixyaaa",
  "request_id": "3a92a8cf0e734a5c80440c5dc92c2466",
  "timestamp": "2024-05-29T10:05:44.499Z",
  "type": "direct_debit_accepted"
}

Testing Processing payment status

To test a payment processing with the Test Bank. Create a Payee with the name Test.Status.Processing. Then use that payee id when initiating a direct debit. The webhook response will look like the following.

{
  "category": "direct_debits",
  "data": {
    "amount": {
      "currency": "GBP",
      "value": "20"
    },
    "created_at": "2024-05-22T09:44:01.021Z",
    "created_by": "usr_a4qesp3t445bkmrnz2uynigq6u",
    "creditor_id": "acc_ar56flcnmvha7jadyqnn3bcbxa",
    "debtor_id": "pye_ans7bmmmovhx5cyhguiunjakdy",
    "due_date": "2024-05-28",
    "entity_id": "ent_b62z7kfws3ykjsz64vh3vnjnt4",
    "id": "ddi_abki7xfye4lzgrcglxmpvqf75m",
    "mandate_id": "man_brchlaugcdi4sldmbdlbcsaclu",
    "organization_id": "org_b256o3j6lpbojoljbvdoixyaaa",
    "reason": "Batch accepted and processed by the bank",
    "reference": "dd-ref-05",
    "status": "processing",
    "updated_at": "2024-05-29T10:05:44.261Z",
    "updated_by": "usr_bqg52gc7rgoqs3uuz2b6vak2f4"
  },
  "id": "whk_auzy4shmec6caq2nejwflx36ke",
  "idempotency_key": "31fde8758016471eb15f73d4a37c3943",
  "organization_id": "org_b256o3j6lpbojoljbvdoixyaaa",
  "request_id": "3a92a8cf0e734a5c80440c5dc92c2466",
  "timestamp": "2024-05-29T10:05:44.499Z",
  "type": "direct_debit_processing"
}

Testing Completed payment status

To test a payment making it to completed with the Test Bank. There is nothing special to do. Create any payee without one of the special names above and just initiate a Direct Debit. You will receive all of the standard direct debit statuses and then the direct debit will enter the final status of completed. The webhook notification will look like the following.

{
  "category": "direct_debits",
  "data": {
    "amount": {
      "currency": "GBP",
      "value": "20"
    },
    "created_at": "2024-05-22T09:44:01.021Z",
    "created_by": "usr_a4qesp3t445bkmrnz2uynigq6u",
    "creditor_id": "acc_ar56flcnmvha7jadyqnn3bcbxa",
    "debtor_id": "pye_ans7bmmmovhx5cyhguiunjakdy",
    "due_date": "2024-05-28",
    "entity_id": "ent_b62z7kfws3ykjsz64vh3vnjnt4",
    "id": "ddi_abki7xfye4lzgrcglxmpvqf75m",
    "mandate_id": "man_brchlaugcdi4sldmbdlbcsaclu",
    "organization_id": "org_b256o3j6lpbojoljbvdoixyaaa",
    "reason": "Batch processed and completed by the bank",
    "reference": "dd-ref-05",
    "status": "completed",
    "updated_at": "2024-05-29T10:19:44.264Z",
    "updated_by": "usr_axuno4wyjgykvxdo3s3yvifxny"
  },
  "id": "whk_ahbr5yoq6xq5gxdmm6rfy6lsxe",
  "idempotency_key": "f62c31f167384de58013b66068f84769",
  "organization_id": "org_b256o3j6lpbojoljbvdoixyaaa",
  "request_id": "3dee9e8958c3468baec30fcb3211ff51",
  "timestamp": "2024-05-29T10:19:45.131Z",
  "type": "direct_debit_completed"
}