3. DirectDebit status

3.1 API reference

To retrieve the status of a mandate, we suggest (besides using the exchange calls as trigger) to use the DirectDebit:GET status API call: https://developer.pay.nl/reference/get_directdebits-directdebitid#/

3.2 Request

curl --request GET \
     --url https://rest.pay.nl/v2/directdebits/IL-2212-2978-7294 \
     --header 'accept: application/json' \
     --header 'authorization: Basic QVQtMDExMS03NzAxOmE0Yjg1ODc2ODBmMzQ0NzQ5NjczNmVjMzViMGJjNDhkODZkMjNlZWE

3.3 Response

{
  "id": "IL-####-####-####",
  "description": "gym membership 2025-01-01",
  "url": "http:\\/\\/pay.nl",
  "processDate": "2025-11-01T11:26:21+01:00",
  "orderId": "0000000000X00000",
  "paymentSessionId": "0000000000",
  "type": "FLEXIBLE",
  "amount": {
    "value": 4999,
    "currency": "EUR"
  },
  "status": {
    "code": 91,
    "action": "add",
    "phase": "Added"
  },
  "declined": false,
  "decline": {
    "code": 119,
    "name": "Administrative reason",
    "date": "2025-01-01T11:26:21+01:00"
  },
  "bankAccount": {
    "iban": "NL69INGB0123456789",
    "bic": "INGBNL2A",
    "owner": "John Doe"
  },
  "mandate": {
    "code": "IO-####-####-####",
    "description": "gym membership"
  },
  "service": {
    "code": "SL-####-####",
    "name": "Fictional Super Gym New York."
  },
  "merchant": {
    "code": "M-####-####",
    "name": "Fictional Super Gym.",
    "status": "ACTIVE",
    "incorporationCountry": "NL"
  },
  "stats": {
    "info": "string",
    "tool": "string",
    "object": "object1",
    "extra1": "string",
    "extra2": "string",
    "extra3": "string",
    "domainId": null
  },
  "createdAt": "2025-01-01T11:26:21+01:00",
  "createdBy": "AT-####-####",
  "modifiedAt": "2025-01-01T11:26:21+01:00",
  "modifiedBy": "AT-####-####",
  "deletedAt": null,
  "deletedBy": null,
  "_links": [
    {
      "href": "\\/directdebits\\/IL-####-####-####",
      "rel": "details",
      "type": "GET"
    },
    {
      "href": "\\/directdebits",
      "rel": "self",
      "type": "POST"
    }
  ]
}

3.4 Statuses

Code	Status	Description
94	Processed	The direct debit has been placed in a batch by PAY. and this has been presented to the bank
100	Debited	The amount was successfully debited
106	Declined	The amount was not debited, see reasons for refund for the specification
91	Added	The direct debit order has been received by PAY. and will be processed shortly
526	In Batch	The direct debit order has been placed in a batch
94	Prematurely rejected	The direct debit order was rejected by the PAY. system
103	Removed	The direct debit order has been removed
127	Rejected by bank	The direct debit order was rejected by the bank

If the direct debit has the status 'Declined' (code 106), you can retrieve the reversal reason via decline.code The following reversal reasons apply:

3.5 Reversal reasons

Code	Status	Possible reasons
109	Administrative reason	Insufficient funds; Regulatory non-compliance; Missing IBAN or debtor name; Other reasons
121	Does not accept direct debit	Your debtor has refused this specific direct debit.
274	Account number blocked	The IBAN number from which you want to collect is not suitable for direct debit
277	Selective direct debit block	The IBAN from which you wish to collect the direct debit is blocked for (these) direct debits. The debtor or the debtor's bank may have blocked the account, or it's a saving account.
112	Account number expired	The IBAN from which you want to collect has been cancelled or the debtor is deceased.
115	Account number unknown	The IBAN from which you wish to collect the direct debit is incorrect.
118	Incorrect mandate	There is no correct registration of the mandate or the debtor has withdrawn the mandate or the debtor has specified a lower maximum amount than the amount of your direct debit.
124	Direct debit carried out twice	You have already submitted this direct debit.
271	Name / number do not match	The name of the debtor as submitted does not match the actual name of the account holder.
280	Account number WKA	The IBAN number concerns a WKA account number from which direct debits may not be made.
286	Reason not specified	The direct debit could not be processed but no specific reason was received from the debtor's bank
331	Report incorrect direct debit	The debtor does not recognize the direct debit order and has started the Report incorrect direct debit procedure. (up to 13 months after depreciation)

❗️
Strong Recommendation: Only retry DirectDebits with Status Code 109
We strongly recommend retrying a DirectDebit only when the transaction returns reversal reason code 109. This is the only status that reliably indicates a temporary issue where a retry has a meaningful chance of succeeding.
DirectDebits with any other status code should not be retried, as these typically represent permanent failures (e.g., invalid IBAN, rejected mandate, regulatory issues). Retrying those transactions will not resolve the problem and may lead to unnecessary processing or compliance complications.