NAV Navbar
  • Receive a Payment Recall
  • Receive a Payment Recall

    This tutorial explains how to receive a recall and respond with a recall decision in SEPA Instant using the Form3 API.

    In this tutorial, we provide an overview of the recall functionality in SEPA Instant and offer a step-by-step guide on how to receive a recall request and respond accordingly. Each step can be simulated using Form3's transaction simulator in the Staging environment.

    Recall Overview

    SEPA Instant offers the recall feature to request the reversal of completed transactions. The debited party of a previous transaction can issue the recall to request a recipient of that transaction to return it.

    A recall can be issued up to 15 days after the submission of the initial payment if the request is initated by the debtor bank. Recall requests initiated by the customer directly can be filed up to 13 months after the transaction has been completed.

    The recipient of the recall (the credited party of the original transaction that is being recalled) can either accept or reject the recall request. A decision has to be returned to the sender within 15 days from receiving the recall request.

    If the recall is accepted, the recipient can decide to return the entire payment amount or keep part of it (e.g. for processing costs or to cover the costs of the return). When declining a recall request, the recipient is required to provide a reason for declining from a list of allowed reasons.

    If no decision is made by the recipient, Form3 will automatically respond with a negative decision at the last possible moment. The reason code in this decision will be "No Response from Customer (NOAS)".

    In the rare event that a positive recall decision cannot be processed by the scheme, the transaction is reversed through a recall reversal. This can happen if the recall decision is submitted very close to the 15-day deadline and there is not enough time for the scheme to process the request in time.

    SEPA Instant receive recall high level flow

    Recalls in the Form3 API

    Form3 models the recall process using the Recall and Recall Decision resources. The Recall resource represents the request for the recall. The Recall Decision resource contains the decision the recipient of the recall has made regarding the request.

    The Recall Admission resource is created to indicate the arrival of an inbound recall, while the Recall Decision Submission resource is used to send a recall decision.

    Step by step guide

    In this section, we'll walk you through each step of receiving a recall and submitting a recall decision.

    Following the guide, you will:

    Prerequisites

    Before getting started, make sure you have the following things ready to follow along:

    Subscribe to Payment Admissions and Recall Admissions

    In order to be notified when inbound payments and recalls arrive, you can subscribe to the create event for Payment Admission and Payment Recall Admission resources.

    You can use Form3's Notification API to be notified when inbound payments and recalls arrive. The API allows you to create a subscription for an event type and record type to be notified through a webhook or SQS queue when this event occurs for a type of resource.

    See this tutorial to learn how to create a subscription and receive notifications.

    Create a Payment Admission subscription

    When an inbound payment arrives, Form3 creates a Payment resource and a Payment Admission resource. In order to be notified when this happens, subscribe to the creation of Payment Admission resources using the following parameters:

    Create a Recall Admission subscription

    Similarly, when an inbound recall arrives, a Recall resource and a Recall Admission resource are created. Create a subscription for the creation of Recall Admission resources using the following parameters:

    Receive a payment and recall

    Form3's transaction simulator can be used to trigger an inbound payment and subsequent recall by sending a payment with the amount 400.00 in the sandbox environment.

    This will trigger the creation of an inbound payment followed by a recall for that payment.

    Send a trigger payment

    To send a trigger payment, first create a Payment resource. Note the following key attributes:

    Take a look at this tutorial and example to learn how to create a Payment resource.

    Finally, to send the trigger payment, create a Payment Submission resource. See here to learn how.

    Receive a payment

    When the transaction simulator receives the payment above, it will trigger an inbound payment of the same amount. Take a look at the URL you registered for notifications, you should have received an event notification for the creation of a Payment Admission resource.

    Note the relationships.payment.data section contains the Payment resource of the created inbound payment.

    The notification will look like this:

    New Payment Admission created notification

    {
      "id": "aeb2d6f5-a196-4ade-bae2-39108575a1fd",
      "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
      "event_type": "created",
      "record_type": "payment_admissions",
      "version": 0,
      "data": {
        "data": {
          "type": "payment_admissions",
          "id": "e8d3a965-d050-4274-a0b8-d65ec4afb778",
          "version": 0,
          "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
          "attributes": {
            "status": "confirmed",
            "status_reason": "accepted",
            "admission_datetime": "2019-09-05T13:37:29.544Z"
          },
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "f9079754-c73e-4ba2-894a-6beabe5cc133",
                  "version": 0,
                  "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
                  "created_on": "2019-09-05T13:37:29.493Z",
                  "modified_on": "2019-09-05T13:37:29.493Z",
                  "attributes": {
                    "amount": "400.00",
                    "beneficiary_party": {
                      "account_name": "Herr Sending Test",
                      "account_number": "GB02FTHR04001333667685",
                      "account_number_code": "IBAN",
                      "account_with": {
                        "bank_id": "FTHRGBL1",
                        "bank_id_code": "SWBIC"
                      },
                      "address": [
                        "Knesebeckstrasse 4, Breitscheidt",
                        "Rheinland-Pfalz, 57539"
                      ],
                      "country": "DE"
                    },
                    "charges_information": {
                      "bearer_code": "SLEV"
                    },
                    "currency": "EUR",
                    "debtor_party": {
                      "account_name": "Mdm Receiving Test",
                      "account_number": "GB02FTHR40000124720741",
                      "account_number_code": "IBAN",
                      "account_with": {
                        "bank_id": "FTHRGBL1",
                        "bank_id_code": "SWBIC"
                      },
                      "country": "GB"
                    },
                    "end_to_end_reference": "00151519632ZCBBBJQ",
                    "payment_acceptance_datetime": "2019-09-05T13:37:29.383Z",
                    "scheme_transaction_id": "125683376199085090",
                    "payment_scheme": "SEPAINSTANT",
                    "payment_type": "ImmediatePayment",
                    "processing_date": "2019-09-05"
                  }
                }
              ]
            }
          }
        }
      }
    }
    

    Receive a recall

    Shortly after the inbound payment, the transaction simulator sends a request to recall the transaction. Since you subscribed to the created event of Recall Admission resources, your will receive a notification that a new Recall Admission has been created.

    Check your notification URL and find the Recall Admission message. It will look like this:

    New Recall Admission created notification

    {
      "id": "8c54bfc4-6f11-436c-9995-04c8196f82f2",
      "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
      "event_type": "created",
      "record_type": "recall_admissions",
      "version": 0,
      "data": {
        "data": {
          "type": "recall_admissions",
          "id": "ab9b8422-7c07-4dc0-9a49-b72c708217f9",
          "version": 0,
          "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
          "attributes": {
            "admission_datetime": "2019-09-05T13:37:29.837Z",
            "status": "confirmed"
          },
          "relationships": {
            "recall": {
              "data": [
                {
                  "type": "recalls",
                  "id": "3ea16db1-8468-4672-b5c0-016dd1344990",
                  "version": 0,
                  "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
                  "created_on": "2019-09-05T13:37:29.729Z",
                  "modified_on": "2019-09-05T13:37:29.729Z",
                  "attributes": {
                    "reason_code": "DUPL",
                    "status": "pending"
                  }
                }
              ]
            },
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "f9079754-c73e-4ba2-894a-6beabe5cc133",
                  "version": 0,
                  "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
                  "created_on": "2019-09-05T13:37:29.493Z",
                  "modified_on": "2019-09-05T13:37:29.493Z",
                  "attributes": {
                    "amount": "400.00",
                    "beneficiary_party": {
                      "account_name": "Herr Sending Test",
                      "account_number": "GB02FTHR04001333667685",
                      "account_number_code": "IBAN",
                      "account_with": {
                        "bank_id": "FTHRGBL1",
                        "bank_id_code": "SWBIC"
                      },
                      "address": [
                        "Knesebeckstrasse 4, Breitscheidt",
                        "Rheinland-Pfalz, 57539"
                      ],
                      "country": "DE"
                    },
                    "charges_information": {
                      "bearer_code": "SLEV"
                    },
                    "currency": "EUR",
                    "debtor_party": {
                      "account_name": "Mdm Receiving Test",
                      "account_number": "GB02FTHR40000124720741",
                      "account_number_code": "IBAN",
                      "account_with": {
                        "bank_id": "FTHRGBL1",
                        "bank_id_code": "SWBIC"
                      },
                      "country": "GB"
                    },
                    "end_to_end_reference": "00151519632ZCBBBJQ",
                    "payment_acceptance_datetime": "2019-09-05T13:37:29.383Z",
                    "scheme_transaction_id": "125683376199085090",
                    "payment_scheme": "SEPAINSTANT",
                    "payment_type": "ImmediatePayment",
                    "processing_date": "2019-09-05"
                  }
                }
              ]
            }
          }
        }
      }
    }
    


    The notification contains the Recall Admission resource as well as the related Recall resource and the Payment resource in its relationships section.

    Note that the reason_code attribute of the Recall resource is set to DUPL, meaning the payment is recalled because of a duplicate payment. The status attribute says pending, which means that the recall has not been resolved yet.

    To match the recall to the payment it is recalling, use the Payment resource that is referenced in the relationships section of the notification.

    Create a Recall Decision Resource

    When receiving a recall request, you have 15 banking business days to respond with a recall decision. The recall decision will either accept or reject the request. It is recommended that you respond before the final minutes of the 15th day to avoid the risk of missing the time window because of processing delays.

    To respond to a recall request, create a Recall Decision resource: POST v1/transaction/payments/{payment_id}/recalls/{recall_id}/decisions

    The ID of the Payment resource of the original payment and the ID of the Recall resource are required to create the Recall Decision resource, they can be found in the inbound recall notification above.

    The Recall Decision resource contains the answer attribute, which can either be accepted or rejected.

    Reject a Recall

    To reject a recall request, set the answer attribute to rejected. When rejecting a recall request, you need to provide a valid reason code for the rejection in the reason_code attribute. Optionally, you can also provide a free-text reason in the reason attribute.

    The example below shows a negative recall decision. The reason code is NNOR, indicating that the original transaction has never been received by the recipient of the recall.

    Negative Recall Decision resource

    {
      "data": {
        "id": "32d1a864-a704-47d3-a7a5-ba2ce567a128",
        "type": "recall_decisions",
        "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
        "attributes": {
          "answer": "rejected",
          "reason_code": "NOOR"
        }
      }
    }
    

    Accept a Recall

    To acccept a recall request, set the answer attribute to accepted. When accepting the recall request, you need to specify the amount of money you are returning to the originator of the recall in the recall_amount.amount attribute. This can be entire amount of the original payment or a part of it.

    If you don't return the entire amount, the withheld amount needs to be added to the charges_amount.amount attribute. The sum of the two amount values always needs to equal the amount of the original payment.

    The recall_amount.currency attribute is required, the charges_amount.currency attribute is required if a charge is specified. Note that the currency has to be the same as in the original payment.

    You do not need to provide a reason or reason code when accepting a recall.

    In the example below, the recall request is accepted and of the 400.00 Euros from the original payment, 396.00 Euros are returned while 4.00 Euros are kept as charges.

    Positive Recall Decision resource

    {
      "data": {
        "id": "fd8d1162-4f5e-48a3-b09d-d01f6cb5a714",
        "type": "recall_decisions",
        "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
        "attributes": {
          "answer": "accepted",
          "recall_amount": {
            "currency": "EUR",
            "amount": "396.00"
          },
          "charges_amount": {
            "currency": "EUR",
            "amount": "4.00"
          }
        }
      }
    }
    

    Create a Recall Decision Submission Resource

    To submit the recall decision, create a Recall Decision Submission resource: POST v1/transaction/payments/{payment_id}/recalls/{recall_id}/decisions/{decision_id}/submissions

    The ID of the original Payment resource, the recall ID and the ID of the Recall Decision resource are required for the call.

    Recall Reversals

    If a positive recall decision cannot be processed by the scheme, a recall reversal will be triggered. In this rare scenario, a Recall Reversal resource and the Recall Reversal Admission resource are created to indicate an inbound recall reversal.

    To be notified when this happens, you can subscribe to receive notification when a new Recall Reversal Admission resource is created. Use the following attribute values:

    Trigger the Recall Reversal Scenario

    The Form3 transaction simulator allows you to simulate a recall reversal scenario. Sending a payment with the amount 400.01 will trigger an inbound payment and a recall for it. A positive response to this recall will be answered with a recall reversal.

    Use the following attributes for the payment resource to trigger the reversal scenario:

    To send the trigger payment, create a Payment Submission resource.

    Follow the Scenario

    Assuming your subscriptions and webhooks for inbound payments and recalls from above are active, you will receive a notification for a new Payment Admission resource, followed by a notification for a new Recall Admission resource.

    Create a Recall Decision resource with a positive response. Send the decision by creating a Recall Decision Submission resource.

    If you subscribed to the creation of Recall Reversal Admission resources above, you should now receive a notification that a resource of this kind has been created:

    New Recall Reversal Admission created notification

    {
      "id": "607cc791-bbe1-4491-be95-a6f13ba974e7",
      "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
      "event_type": "created",
      "record_type": "recall_reversal_admissions",
      "version": 0,
      "data": {
        "data": {
          "type": "recall_reversal_admissions",
          "id": "6127a1c3-7ac8-49e8-9f06-3f9aa892b20e",
          "version": 0,
          "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
          "attributes": {},
          "relationships": {
            "payment": {
              "data": [
                {
                  "type": "payments",
                  "id": "f9079754-c73e-4ba2-894a-6beabe5cc133",
                  "version": 0,
                  "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
                  "attributes": {
                    "amount": "400.01",
                    "beneficiary_party": {
                      "account_name": "Herr Sending Test",
                      "account_number": "GB02FTHR04001333667685",
                      "account_number_code": "IBAN",
                      "account_with": {
                        "bank_id": "FTHRGBL1",
                        "bank_id_code": "SWBIC"
                      },
                      "address": [
                        "Knesebeckstrasse 4, Breitscheidt",
                        "Rheinland-Pfalz, 57539"
                      ],
                      "country": "DE"
                    },
                    "charges_information": {
                      "bearer_code": "SLEV"
                    },
                    "currency": "EUR",
                    "debtor_party": {
                      "account_name": "Mdm Receiving Test",
                      "account_number": "GB02FTHR40000124720741",
                      "account_number_code": "IBAN",
                      "account_with": {
                        "bank_id": "FTHRGBL1",
                        "bank_id_code": "SWBIC"
                      },
                      "country": "GB"
                    },
                    "end_to_end_reference": "00151519632ZCBBBJQ",
                    "payment_acceptance_datetime": "2019-09-05T18:18:16.525Z",
                    "scheme_transaction_id": "120099596729776000",
                    "payment_scheme": "SEPAINSTANT",
                    "payment_type": "ImmediatePayment",
                    "processing_date": "2019-09-05",
                    "remittance_information": "Remittance information"
                  }
                }
              ]
            },
            "recall": {
              "data": [
                {
                  "type": "recalls",
                  "id": "02c7767a-89dc-41b8-8f95-dfacf2814bdf",
                  "version": 0,
                  "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
                  "attributes": {
                    "reason_code": "DUPL",
                    "status": "pending"
                  }
                }
              ]
            },
            "recall_reversal": {
              "data": [
                {
                  "type": "recall_reversals",
                  "id": "393a6c4d-8115-4c8a-ae39-2a7c41b7c870",
                  "version": 0,
                  "organisation_id": "7af0d077-e900-488d-a0b8-7f788ce61b02",
                  "attributes": {}
                }
              ]
            }
          }
        }
      }
    }
    


    The notification contains the related Payment resource, the Recall resource and the Recall Reversal resource. The Recall Reversal resource itself does not have any attributes, it just serves as an information that the recall has been reversed. There is no need for further action.

    Further Reading

    This tutorial explained how to receive and respond to recalls in SEPA Instant. For more information on using SEPA Instant with Form3, see our other tutorials and documents: