Send a direct debit request

post/debitAccountHolder

API Version

Sends a direct debit request to an account holder's bank account. If the direct debit is successful, the funds are settled in the accounts specified in the split instructions. Adyen sends the result of the direct debit in a DIRECT_DEBIT_INITIATED notification webhook.

To learn more about direct debits, see Top up accounts.

Endpoint destination URL

https://cal-test.adyen.com/cal/services/Fund/v6/debitAccountHolder

Request Parameters

Required

Optional

The code of the account holder.

The amount to be debited from the account holder's bank account.

The Adyen-generated unique alphanumeric identifier (UUID) of the account holder's bank account.

Max length: 35

A description of the direct debit. Maximum length: 35 characters.

Allowed characters: a-z, A-Z, 0-9, and special characters /?:().,'+ ";.

Your merchant account.

Contains instructions on how to split the funds between the accounts in your platform. The request must have at least one split item.

The unique identifier of the account to which the split amount is booked. Required if type is MarketPlace or BalanceAccount.

Classic Platforms integration: The accountCode of the account to which the split amount is booked.
Balance Platform: The balanceAccountId of the account to which the split amount is booked.

The amount of the split item.

Required for all split types in the Classic Platforms integration.
Required if type is BalanceAccount, Commission, Default, or VAT in your Balance Platform integration.

Your description for the split item.

Your unique reference for the part of the payment booked to the specified account.

This is required if type is MarketPlace (Classic Platforms integration) or BalanceAccount (Balance Platform).

For the other types, we also recommend providing a unique reference so you can reconcile the split and the associated payment in the transaction overview and in the reports.

The part of the payment you want to book to the specified account.

Possible values for the Balance Platform:

BalanceAccount: books part of the payment (specified in amount) to the specified account.
Transaction fees types that you can book to the specified account:
- AcquiringFees: the aggregated amount of the interchange and scheme fees.
- PaymentFee: the aggregated amount of all transaction fees.
- AdyenFees: the aggregated amount of Adyen's commission and markup fees.
- AdyenCommission: the transaction fees due to Adyen under blended rates.
- AdyenMarkup: the transaction fees due to Adyen under Interchange ++ pricing.
- Interchange: the fees paid to the issuer for each payment made with the card network.
- SchemeFee: the fees paid to the card scheme for using their network.
Commission: your platform's commission on the payment (specified in amount), booked to your liable balance account.
Remainder: the amount left over after a currency conversion, booked to the specified account.
TopUp: allows you and your users to top up balance accounts using direct debit, card payments, or other payment methods.
VAT: the value-added tax charged on the payment, booked to your platforms liable balance account.
Commission: your platform's commission (specified in amount) on the payment, booked to your liable balance account.
Default: in very specific use cases, allows you to book the specified amount to the specified account. For more information, contact Adyen support.

Possible values for the Classic Platforms integration: Commission, Default, Marketplace, PaymentFee, VAT.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
accountHolderCodestring
The code of the account holder.
bankAccountUUIDstring
The Adyen-generated unique alphanumeric identifier (UUID) of the account holder's bank account.
invalidFieldsarray[object]
Contains field validation errors that would prevent requests from being processed.
errorCodeinteger
The validation error code.
errorDescriptionstring
A description of the validation error.
fieldTypeobject
The type of error field.
fieldstring
The full name of the property.
fieldNamestring
The type of the field.
shareholderCodestring
The code of the shareholder that the field belongs to. If empty, the field belongs to an account holder.
merchantReferencesarray[string]
List of the reference values from the split array in the request.
pspReferencestring
The reference of a request. Can be used to uniquely identify the request.
resultCodestring
The result code.
202 - Accepted
The request has been accepted for processing, but the processing has not been completed.
accountHolderCodestring
The code of the account holder.
bankAccountUUIDstring
The Adyen-generated unique alphanumeric identifier (UUID) of the account holder's bank account.
invalidFieldsarray[object]
Contains field validation errors that would prevent requests from being processed.
errorCodeinteger
The validation error code.
errorDescriptionstring
A description of the validation error.
fieldTypeobject
The type of error field.
fieldstring
The full name of the property.
fieldNamestring
The type of the field.
shareholderCodestring
The code of the shareholder that the field belongs to. If empty, the field belongs to an account holder.
merchantReferencesarray[string]
List of the reference values from the split array in the request.
pspReferencestring
The reference of a request. Can be used to uniquely identify the request.
resultCodestring
The result code.
400 - Bad Request
A problem reading or understanding the request.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
401 - Unauthorized
Authentication required.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
403 - Forbidden
Insufficient permissions to process the request.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
422 - Unprocessable Entity
A request validation error.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
500 - Internal Server Error
The server could not process the request.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.

Send a direct debit request

HTTP Responses

200 - OK

202 - Accepted

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error