Asynchronous Cancellations

Depending on cancellation conditions or if a booking is flagged as potentially fraudulent on the SNCF side, a cancellation request might not be confirmed immediately. Instead, its status may be marked as "pending". To support this scenario, an asynchronous cancellation process must be implemented and managed on the retailer side to check for the final status of the cancellation.

Creating a Cancellation

The process begins similarly to a standard cancellation. After confirming the cancellation policies using the /cancellations/conditions endpoint, you create a cancellation using /cancellations/create.

However, for this asynchronous flow, the response will include a state of "pending" and a confirmation_expected_at timestamp. This timestamp indicates the earliest time you should check for a final update from the carrier.

Sample Response from /cancellations/create (Pending State)

{
  "data": {
    "id": "hlvxV2GfWcRCHUxa-MFUwg",
    "type": "cancellations",
    "attributes": {
      "state": "pending",
      "total_price": 13300,
      "fee": 0,
      "total_refund": 13300,
      "monetary_refund": 13300,
      "voucher_refund": 0,
      "created_at": "2024-02-15T13:43",
      "confirmation_expected_at": "2024-02-15T14:14+01:00"
    }
  }
}{
  "data": {
    "id": "hlvxV2GfWcRCHUxa-MFUwg",
    "type": "cancellations",
    "attributes": {
      "state": "pending",
      "total_price": 13300,
      "fee": 0,
      "total_refund": 13300,
      "monetary_refund": 13300,
      "voucher_refund": 0,
      "created_at": "2024-02-15T13:43",
      "confirmation_expected_at": "2024-02-15T14:14+01:00"
    }
  }
}

Checking the Cancellation Status

To get the final status of a pending cancellation, you must schedule a follow-up call.

1. Schedule the Check: Use the confirmation_expected_at timestamp from the previous response to schedule a call to check the booking's status.
2. Poll the Booking Endpoint: Make a request to the /bookings/{booking_id} endpoint, using the ID of the original booking.
3. Check the Final State: The updated status is available in the cancellation-related attributes within the booking response. The possible final values for the state field are: confirmed, pending, rejected, and failed.
4. Check for Rejection Reason: If the cancellation status is rejected, the error message will appear in the rejected_reason field.

By implementing this polling mechanism, you can reliably manage SNCF cancellations that require an asynchronous confirmation process.