🚧

Upgrade to the latest version

These docs are for version 2023-12-01. We encourage you to upgrade to version 2024-10-16 to access new features. Please see the changelog for more information.

What is a replaced payment method?

Payment methods can become out of date or incorrect. When the payment method information changes, Rainforest will replace the payment method with a new payment method. Processes such as ACH Notification of Change (NOC) and Card Account Updater (CAU) can trigger the replacement of a payment method.

When this process occurs, the original payment method status will become REPLACED and a new payment method will be activated and linked to the original payment method.

You can create payins from a stored payment method with the original (replaced) payment method or the new (linked) payment method. Rainforest will automatically use the new payment method regardless of which payment method was passed into the request.

For example, let's say payment method IDmtd_1 is replaced with mtd_2.

• If creating a payin with mtd_1 is requested, Rainforest will automatically use mtd_2 to process the payin.
• If creating a payin with mtd_2 is requested, Rainforest will use mtd_2 to process the payin.

Linked payment methods

The original payment method will be linked to the new payment method by a set of fields that will be populated on the get payment method response in the API and webhooks. The original payment method will provide details for the reason of the replacement, such as a NOC C01 reason code for an incorrect account number on an ACH payment method. The replaced_by_payment_method_id will indicate the new payment method. The up-to-date payment method information, such as the correct account number, can be found on the new payment method.

Example

In this example, the ACH payment method was replaced due to an incorrect account number. The original payment method status is now REPLACED and with details on why it was replaced.

{
    “payment_method_id”: “mtd_1”,
+   “status”: “REPLACED”,
    “ach”: {
+       "account_number_last_4": "1111",
        ...
    },
    "replaces_payment_method_id": null,
+   "replaced_by_payment_method_id": "mtd_2",
+   "replaced_at": "2024-05-15T21:19:10.008222Z",
+   "replaced_reason_code": "C01",
+   "replaced_reason_desc": "Incorrect account number",
    ...
}

The new payment method status will be ACTIVE and include a reference to the original payment method in replaces_payment_method_id field.

{
    “payment_method_id”: “mtd_2”,
+   “status”: “ACTIVE”,
    “ach”: {
+      "account_number_last_4": "2222",
       ...
    },
+   "replaces_payment_method_id": "mtd_1",
    "replaced_by_payment_method_id": null,
    "replaced_at": null,
    "replaced_reason_code": null,
    "replaced_reason_desc": null,
    ...
}

Replaced reason codes

When a payment method is replaced, a reason code is provided on the original payment method to indicate what payment method information changed.

Most common replaced reason codes

Listen to webhooks

Listen to the payment method webhooks to understand when a payment method is replaced. You should expect the following webhooks for the replacement process:

• payment_method.created webhook for the new payment method when it's created
• payment_method.replaced webhook for the original payment method indicating it's been replaced
• payment_method.active webhook for the new payment method indicating this is now the active payment method