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 TypeDescription
direct_debit_createdThe direct debit has been created by a user.
direct_debit_sentThe direct debit has been sent to the financial institution.
direct_debit_acceptedA direct debit has been accepted by the bank and it is pending collection.
direct_debit_completedThe direct debit has been executed by the bank.
direct_debit_failedThe direct debit failed to be created due to technical issues, insufficient funds in the debtor account.
direct_debit_rejectedThe direct debit has been rejected by the bank due to incorrect information, or there is an issue with the mandate.
direct_debit_cancelledThe direct debit has been cancelled by a user.
direct_debit_charge_back_requestedThe 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"
}