Numeral can automatically create payment orders that failed. Use cases include:

Falling back to SEPA credit transfer if a SEPA instant credit transfer fails due to timeout or maximum payment amount
Retrying a SEPA direct debit every 7 days for 4 weeks if it fails due to insufficient funds

1. Understand payment retry rules

Automated payment retries are based on rules that are automatically checked when a payment order fails. A payment retry rule includes:

A name and a description
Retry conditions checked to create a retry, including payment type, direction, statuses, and reason codes
Retries, including payment type and time interval to retry the payment (e.g., 30 seconds, 1 hour, 2 days…)

The originating account, receiving account, amount, currency, and reference of the original payment remain the same. The payment retry rule stops after a first successful payment or all retries have been created.

Below are default payment retry rules:

curl --request GET \
     --url https://sandbox.numeral.io/v1/payment_retry_rules/id \
     --header 'accept: application/json'

{
  "id": "1e5cf32f-c97e-4ca2-a427-63b10eeadfba",
  "object": "payment_retry_rule",
  "name": "Retry SCT Inst once then fall back to SCT",
  "description": "Retry SCT Inst once then fall back to SCT",
  "retry_conditions": {
    "payment_type": "sepa_instant",
    "payment_direction": "credit",
    "statuses": [
      "rejected"
    ],
    "reason_codes": ["AB05" "AB06","AB07","AB08","AB09","AB10","TECH","CNOR"]
  },
  "retries": [
    {
      "retry_to_payment_type": "sepa_instant",
      "retry_after": "15s"
    },
    {
      "retry_to_payment_type": "sepa",
      "retry_after": "15s"
    }
  ],
  "createdAt": "2024-03-29T16:00:02Z"
}

2. Assign a payment retry rule to a payment order

Payment retry rules are assigned to payment orders when creating them in the Numeral dashboard or API:

curl --location 'https://sandbox.numeral.io/v1/payment_orders' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: Your API key' \
--data '
{
  // All other parameters
  "retry_details": {
    "payment_retry_rule_id": "1e5cf32f-c97e-4ca2-a427-63b10eeadfba", // ID of a retry rule, optional.
  }

{
  "id": "5da98f42-5cde-4b88-a962-47abc1eaa556",
  "object": "payment_order",
  // All standard attributes of a payment order
  "retry_details":{
    "payment_retry_rule_id": "1e5cf32f-c97e-4ca2-a427-63b10eeadfba",
    "original_payment_id": null,
    "retried_to_payment_id": null,
    "retried_from_payment_id": null,
    "retry_scheduled_at": null,
  }
}

3. View retries linked to a payment order

Retried payment orders are linked to their retries and vice versa:

retried_from_payment_id refers to the payment order the payment order has been retried from, either the original payment order or the previous payment order in a retry sequence
retried_to_payment_id refers to the payment order the payment order has been retried to
original_payment_id refers to the original payment order

Below is how these fields are populated for a payment order (payment order A) retried twice (payment orders B and C):

	Original payment order	Original payment order	Payment order retry #1	Payment order retry #1	Payment order retry #1	Payment order retry #2
id	A	A	B	B	B	C
status	rejected	retried	approved	rejected	retried	approved
retry_details.original_payment_id	-	-	A	A	A	A
retry_details.retried_to_payment_id	-	B	-	-	C	-
retry_details.retried_from_payment_id	-	-	A	A	A	B

You can view related payments in the dashboard:

You can also list payment orders related to the same original payment with the API:

curl --request GET \
     --url https://sandbox.numeral.io/v1/payment_orders?retry_details.original_payment_id=6cfb067e-4d21-427f-95f0-43b75252589f \
     --header 'accept: application/json'
}

{
  "records":[
    {
      "id":"5da98f42-5cde-4b88-a962-47abc1eaa556",
      "object":"payment_order",
      // All standard attributes of a payment order
    },
    {
      "id":"6cfb067e-4d21-427f-95f0-43b75252589f",
      "object":"payment_order",
      // All standard attributes of a payment order
    }
  ]
}