Receives payout reversal notifications from Shinkansen

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

Body

application/json

Payout reversal notifications related to payouts, sent by Shinkansen

document
Type: object
required

Envelops the message content

Properties: 2

Responses

200

Message correctly received. Does NOT mean the transaction was succesful. Further responses might be sent back on another message.
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)'

post/reversal-notifications

curl https://example.customer.url/reversal-notifications \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Shinkansen-JWS-Signature: YOUR_SECRET_TOKEN' \
  --data '{
  "document": {
    "header": {
      "message_id": "d562602e-2fec-4072-81a0-d84b6b0ea5d3",
      "shinkansen_message_id": "0421c147-1d4a-484c-b855-9dcd8b9b67d9",
      "creation_date": "2026-06-30T14:41:00-04:00",
      "sender": {
        "fin_id_schema": "SHINKANSEN",
        "fin_id": "SHINKANSEN"
      },
      "receiver": {
        "fin_id_schema": "SHINKANSEN",
        "fin_id": "SHINKANSEN_SPA"
      }
    },
    "notifications": [
      {
        "shinkansen_notification_id": "0421c147-1d4a-484c-b855-9dcd8b9b67d9",
        "notification_type": "payout_reversal",
        "notification_id": "4e0309bd-7228-46ae-887e-41764f9d5ac7",
        "notification_date": "2026-06-30T14:41:00Z",
        "referenced_shinkansen_transaction_id": "6f11ea4d-d2fa-4da3-b102-8c07112c1635",
        "referenced_transaction_id": "6adf8e53-ab35-4573-9073-f902d9e00580",
        "reversal_reason": "error_creditor_account_not_found",
        "reversal_message": "Cuenta de destino inexistente"
      }
    ]
  }
}'

No Body

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

Payout Reversal Notifications

Introduction