---
title: "Receives reversals (synchronously)"
method: POST
path: "/reversals"
tags: ["Participant Webhooks"]
---

# Receives reversals (synchronously)

`POST /reversals`

Webhook for receiving reversals. The reversal notification is sent when a transfer is reversed by the Switch (CCA). ⚠️ This is a special case becase you need to respond syncronously to the reversal.

## Request body

- ParticipantReversalMessage — Reversal notifications to transfers participants, sent by Shinkansen (Originated by Switch or IFO)
  - `document` object, required — Envelops the message content
    - `header` TransferFwMessageHeader, required — Header for original transfer messages
      - `shinkansen_message_id` string, uuid, required — UUID Unique identifier of the message. Generated by Shinkansen initiating the transactions (or sending the responses) inside this message. UUID format is required.
      - `creation_date` string, date-time, required — Creation date of the message in ISO 8601 format. Generated by Shinkansen initiating the transactions (or sending the responses) inside this message.
      - `sender` string, required — Shinkansen sending this message. For forwarded transfers, responses or reversals.
      - `receiver` string, required — The receiver of this message for this case, the Participant (your financial institution)
    - `reversals` TransactionReversal[] — One or more transfer reversals (one per transaction).
      - `reversal_code` 'reversal_switch_timeout' | 'reversal_switch_delivery_failure' | 'reversal_debtor_fi_rejected_by_mac' | 'reversal_conditional_timeout' | 'reversal_conditional', required — This is the possible reversal codes from the underlying network. For more information, see the [Shinkansen documentation](https://docs.shinkansen.tech/reference/response-codes). * `reversal_switch_timeout`: Generated when an IFR's "Approved" response arrives after the timeout window has expired. * `reversal_switch_delivery_failure`: Generated when an approved response from IFR cannot be delivered to the IFO. * `reversal_debtor_fi_rejected_by_mac`: Generated when the IFO rejects an approved response due to a MAC error. * `reversal_conditional_timeout`: Generated (optionally) by the Switch when the IFR does not respond to a request in time. * `reversal_conditional`: Generated by the IFO when it cannot determine the outcome of a transaction.
      - `reversal_message` string, required — Reason message for the reversal.
      - `transaction_id` string, required — Transaction ID of the transfer that was reversed (your original transaction ID)
      - `shinkansen_transaction_id` string, required — Shinkansen transaction ID of the transfer that was reversed (original Shinkansen transaction ID)
      - `shinkansen_reversal_id` string, required — Reversal ID generated by Shinkansen for this reversal (for idempotency purposes and tracking)

## Response `200`

Message correctly received and accepted to be processed by Participant, this is a notification with the status of the reversals You need to respond syncronously to the reversal. If you dont respond, the reversal will be considered as approved by default.

- StatusAcceptedFwReversal — Status accepted reversal HTTP 200
  - `message_id` string, uuid, required — Message ID generated by Participant receiving the reversal
  - `reversals` object[], required — Array of mappings between original reversal_id and shinkansen_reversal_id
    - `reversal_id` string, uuid, required — The reversal_id - Generated by the Participant (your internal identifier for the response).
    - `shinkansen_reversal_id` string, uuid, required — The original shinkansen_response_id - Generated by Shinkansen
    - `response_status` 'approved' | 'error_reversal_insufficient_balance', required — The response status of the reversal - Responded by Participant - Only can reject the reversal if the reversal_type is 'reversal_conditional' if the reversal_type is not 'reversal_conditional' the reversal will be considered as approved by default. This is mandatory to respond to the reversal. by Switch Policy (CCA)

## Other responses

- `400` — Invalid message (e.g: invalid payload) - Maybe you want to respond with detailed error message for tracking purposes
- `401` — Invalid signature JWS (e.g: invalid certificate or expired)
- `409` — Duplicate message or reversal ID (e.g: Send same message twice)

---

[API](https://skmtc.net/shinkansen/apis/payouts-shinkansen-endpoints.md) · [All operations](https://skmtc.net/shinkansen/apis/payouts-shinkansen-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shinkansen/payouts-shinkansen-endpoints/versions/1e4a6760b7e8/schema)