Direct Debit Accounts
Methods
Section titled “Methods”Retrieve Single Direct Debit Account
Section titled “Retrieve Single Direct Debit Account”/backend/api/v1/directDebitAccounts/ID - fetch direct debit account with specified ID.
List Direct Debit Accounts
Section titled “List Direct Debit Accounts”/backend/api/v1/directDebitAccounts/ - list all direct debit accounts.
/backend/api/v1/customers/ID/directDebitAccounts/ - list direct debit accounts belonging to customer with specified ID.
/backend/api/v1/customers/ID/directDebitAccounts/ - add a new direct debit account to the specified customer, the newly-added account will be returned.
/backend/api/v1/directDebitAccounts/ID - update direct debit account with specified ID. The modified account will be returned.
DELETE
Section titled “DELETE”/backend/api/v1/directDebitAccounts/ID - delete direct debit account with specified ID.
Fields
Section titled “Fields”| Field | Name | Type | Description |
|---|---|---|---|
| ourReference | Our Reference | Text | Internal reference number for the direct debit account |
| customerReference | Customer's Reference | Text | Customer-provided reference for the direct debit account |
| customerMandateReference | Customer's Mandate Reference | Text | Customer mandate reference number for the direct debit authorization |
| directDebitAccountPriority | Account Collection Order | Preset Value | Priority order for payment collection when customer has multiple direct debit accounts |
| accountName | Account Name | Text | Name of the account holder for the direct debit account |
| sortCode | Sort Code | Text | Bank sort code for the direct debit account |
| accountNumber | Account Number | Text | Bank account number for the direct debit account |
| bankName | Bank Name | Text | Name of the bank holding the direct debit account |
| bankAddress | Bank Address | Text (Multiline) | Address of the bank branch for the direct debit account |
| directDebitStorageType | Account Storage Method | Preset Value | Method used to store and process the direct debit account information |
| useForPaymentTypes | Use For Payment Types | Preset Value(s) | Array of payment type names this account supports Send "All Payment Types" (or null) for All Payment Types; an empty list means none. |
| directDebitCollectionTypes | Use For Collection | Preset Value(s) | Array of collection type names this account can be used for |
| providerCustomerReference | Provider Customer Reference | Text | Customer reference used by the direct debit payment provider |
| providerAccountReference | Provider Account Reference | Text | Account reference used by the direct debit payment provider |
| providerSubscriptionReference | Provider Subscription Reference | Text | Subscription reference used by the direct debit payment provider |
| providerReference | Provider Reference | Text | General reference used by the direct debit payment provider |
| status | Account Status | Preset Value | Current status of the direct debit account |
| providerStatus | Provider Status | Text | Status information from the direct debit payment provider |
| providerStatusDetail | Provider Status Detail | Text | Detailed status information from the direct debit payment provider |
| directDebitSetupDate | Set-Up Date | Date | Date when the direct debit account was set up with the provider |
| directDebitTakenDate | Last Taken Date | Date | Date when a payment was last successfully taken from this account |
| directDebitAccountEndedStamp | Account Ended Date | Date | Date when the direct debit account was ended or cancelled |
Use For Payment Types
Section titled “Use For Payment Types”useForPaymentTypes controls which payment types the account can collect for. The API distinguishes an unrestricted account from one used for no payment type:
| Meaning | Returned as | Send |
|---|---|---|
| Any payment type (unrestricted) | "All Payment Types" | "All Payment Types" or null |
| No payment type | null | [] or "" |
| Specific payment types | Comma-separated payment type names | An array of names, or a comma-separated string |
{ "useForPaymentTypes": "All Payment Types"}Sending "All Payment Types" together with specific payment types returns HTTP 400 with error code 400201. Leaving useForPaymentTypes out of a PATCH leaves it unchanged.
Provider-Specific Fields
Section titled “Provider-Specific Fields”GoCardless
Section titled “GoCardless”When creating a direct debit account with directDebitStorageType set to GoCardless, supply the following provider field:
| Field | Required | Description |
|---|---|---|
providerReference | Yes | The GoCardless mandate ID (beginning MD) |
The remaining provider fields are populated automatically from GoCardless once the mandate is linked:
| Field | Auto-populated | Description |
|---|---|---|
providerCustomerReference | Yes | GoCardless customer ID (beginning CU) |
providerAccountReference | Yes | GoCardless bank account ID (beginning BA) |
providerSubscriptionReference | Yes | GoCardless subscription ID, if applicable |
If the auto-populated fields remain empty after saving, the platform was unable to match the mandate in GoCardless. Check the mandate ID is correct.