GoCardless mandate_replaced: the mandate has a replacement (the connector texts are in English)

What GoCardless says

The event documentation explains it like this: “The mandate has been cancelled and replaced by a new mandate (for example, because the creditor has moved to a new Service User Number).”. And what the event carries: “The event will include links[new_mandate] with the ID of the new mandate.”.

mandate_replaced is an invalid_state error: the action is not valid in the resource's current state. For these errors GoCardless asks you to inform the user and not retry (“invalid_state → inform the end user, do not allow retry.”).

When it appears

The customer and their bank do not cause this change: the replaced event has origin gocardless, and the documented cause is that the creditor, the account you collect with in GoCardless, has moved to a different scheme identifier. GoCardless cancels the old mandate and creates a new one in its place.

mandate_replaced only appears if Odoo tries to charge the old mandate: a subscription renewal being charged, or a payment registered with the customer's saved payment method, before Odoo has applied the event.

What the connector does in Odoo

With the replaced event:

1. It takes the new mandate from links.new_mandate.
2. It assigns the customer's saved payment method to that new mandate and keeps it as valid, instead of treating it as lost. If the method was archived, it reactivates it; Odoo 17 does not allow unarchiving a payment method, so there the connector creates a new one for the new mandate.
3. It writes this note on the customer record: “The GoCardless mandate is usable again (replaced).”.

The connector writes that note when it applies the event, with no one involved. The connector writes these texts in English, so in an English-language Odoo they appear exactly as quoted here, whether a user or a scheduled action triggers them: “The GoCardless mandate is usable again (replaced).”.

With mandate_replaced on a payment, the connector does nothing special: when creating a payment it only handles mandate_is_inactive separately. The transaction goes to “Error” with “GoCardless rejected the request.” and, below it, the GoCardless message with mandate_replaced and the request_id in brackets. It takes the new mandate from the event, not from the error. The connector writes these texts in English, so in an English-language Odoo they appear exactly as quoted here, whether a user or a scheduled action triggers them: “GoCardless rejected the request.”.

What to do

1. If a payment is stuck in error with mandate_replaced, open the transaction from the invoice, with the “Payment Transaction” button at the top; the transactions menu only shows in developer mode, and it does not exist in Odoo 20.
2. Check the customer record for the note that the mandate is usable again (replaced). If it is there, the payment method already points to the new mandate.
3. If it is not there, the event has not arrived yet. The hourly task that recovers missed events brings it in; if it takes longer than that, check that GoCardless webhooks reach Odoo.
4. With the payment method up to date, charge the invoice again.

With our connector

In Odoo 17, 18, 19 and 20 the connector follows the new mandate as soon as GoCardless reports the replacement: the customer keeps their payment method, and the next invoice is charged against the mandate GoCardless put in its place.

Keep reading