---
title: "Receives payout reversal notifications from Shinkansen"
method: POST
path: "/reversal-notifications"
tags: ["Payout Reversal Notifications"]
---

# Receives payout reversal notifications from Shinkansen

`POST /reversal-notifications`

## Request

- Base URL: `https://example.customer.url`
- URL: `https://example.customer.url/reversal-notifications`
- Auth: API key in header `Shinkansen-JWS-Signature`

Webhook for receiving notifications when a previously completed payout is reversed (returned by the bank).

## Request body

- ParticipantPayoutReversalNotificationMessage: Payout reversal notifications related to payouts, sent by Shinkansen
  - `document` object, required: Envelops the message content
    - `header` ForwardedMessageHeader, required: Header with meta-data of the forwarded message
      - `message_id` string, uuid, required: UUID Unique identifier of the message. Generated by the participant initiating the transactions, sending the responses or sending notifications.
      - `shinkansen_message_id` string, uuid, required: UUID Unique identifier of the message. Generated by Shinkansen.
      - `creation_date` string, date-time, required: Creation date of the message in ISO 8601 format. Generated by the participant initiating the transactions (or sending the responses).
      - `sender` object, required: The identifier for a financial institution
        - `fin_id_schema` string, required: Identification schema for financial institution, namely, any participant in Shinkansen Network. Use `"SHINKANSEN"` for Shinkansen's native network ids and full support on any participant and service of the Shinkansen network. Other schemas might be used when interfacing with other networks but they are *not* recommended unless you *really* know what you are doing or have been explicitly instructed to do so by Shinkansen.
        - `fin_id` string, required: Identification according to schema. When the `"SHINKANSEN"` schema is used (as recommended), this is the ID assigned by Shinkansen to the participant in the network. In the context of the `header`, it refers to the Shinkansen network participant that sends (Sender) or receives (Receiver) the message. In the context of the `transactions`, it refers to the financial institution from which the resources leave or where the resources arrive. The ID assigned by Shinkansen to the financial institution can be found in https://docs.shinkansen.tech/docs/instituciones-financieras. When sending a transaction to Shinkansen, this value must always be SHINKANSEN. When sending a payout order to Shinkansen Treasury, this value must be SHINKANSEN_TREASURY
      - `receiver` object, required: The identifier for a financial institution
        - `fin_id_schema` string, required: Identification schema for financial institution, namely, any participant in Shinkansen Network. Use `"SHINKANSEN"` for Shinkansen's native network ids and full support on any participant and service of the Shinkansen network. Other schemas might be used when interfacing with other networks but they are *not* recommended unless you *really* know what you are doing or have been explicitly instructed to do so by Shinkansen.
        - `fin_id` string, required: Identification according to schema. When the `"SHINKANSEN"` schema is used (as recommended), this is the ID assigned by Shinkansen to the participant in the network. In the context of the `header`, it refers to the Shinkansen network participant that sends (Sender) or receives (Receiver) the message. In the context of the `transactions`, it refers to the financial institution from which the resources leave or where the resources arrive. The ID assigned by Shinkansen to the financial institution can be found in https://docs.shinkansen.tech/docs/instituciones-financieras. When sending a transaction to Shinkansen, this value must always be SHINKANSEN. When sending a payout order to Shinkansen Treasury, this value must be SHINKANSEN_TREASURY
    - `notifications` PayoutReversalNotification[], required: One or more payout reversal notifications.
      - `shinkansen_notification_id` string, uuid, required: The unique identifier of the notification, set by Shinkansen
      - `notification_type` 'payout_reversal', required: The type of the notification. Always "payout_reversal" for this type of notification.
      - `notification_id` string, uuid, required: The unique identifier of the notification, set by the payment operator
      - `notification_date` string, date-time, required: The timestamp when the notification was created
      - `referenced_shinkansen_transaction_id` string, uuid, required: The Shinkansen identifier of the reversed payout transaction
      - `referenced_transaction_id` string, uuid, required: The original transaction_id of the reversed payout transaction
      - `reversal_reason` 'error_creditor_account_not_found' | 'error_creditor_account_closed' | 'error_creditor_account_currency_mismatch' | 'error_creditor_account_detail_mismatch' | 'error_creditor_account_over_limits' | 'invalid' | 'error', required: Why the payout was reversed. This is a dedicated list of reversal reasons, independent from the payout response `response_status` (though several values coincide by name).
      - `reversal_message` string, required: A human-readable detail of the reversal

## Response `200`

Message correctly received. Does NOT mean the transaction was succesful. Further responses might be sent back on another message.

## Other responses

- `400`: Invalid message (e.g: invalid signature)
- `409`: Message ignored, because it was already seen and processed before by the receiver. Typically happens when a message is re-sent because the sender isn't sure if it was correctly received (e.g: network failure when the 2xx response was in flight)'

---

[API](https://skmtc.dev/shinkansen/apis/payouts-participant-webhooks.md) - [All operations](https://skmtc.dev/shinkansen/apis/payouts-participant-webhooks/llms.txt) - [OpenAPI document](https://skmtc.dev/shinkansen/apis/payouts-participant-webhooks/revisions/be13d993109f?raw)