Receives a Result Webhook from Shinkansen Treasury for a final state of a Payout Order.

Webhook for receiving transaction responses.

Shinkansen Treasury sends one request to each webhook URL configured for your account. Every request carries the Shinkansen-JWS-Signature header and Content-Type: application/json. If a webhook key is configured for your account, it is also sent in the x-api-key header.

Only a 200, 201 or 409 response marks the message as delivered. Any other response is retried, including other 2xx codes such as 202 or 204, and 400, and so is any connection error. The retry is made with the same message (same body, same signature and same message_id), up to 20 attempts per URL with increasing waits, about 10 hours in total. Each attempt waits at most 15 seconds for the response. Webhook URLs that point to localhost or 127.0.0.1 are ignored; use a URL reachable from the internet.

Headers

x-api-key
Type: string

Sent only if a webhook key is configured for the customer.

Body

application/json

Responses to Shinkansen Treasury customers, sent by Shinkansen Treasury

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. The message is considered delivered.
400

Invalid message (e.g: invalid signature). The message is considered not delivered and is retried.
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). The message is considered delivered and is not retried.

post/responses

curl https://example.customer.url/responses \
  --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": "2024-04-08T18:25:45-04:00",
      "sender": {
        "fin_id_schema": "SHINKANSEN",
        "fin_id": "SHINKANSEN_TREASURY"
      },
      "receiver": {
        "fin_id_schema": "SHINKANSEN",
        "fin_id": "MONSTER_INC"
      }
    },
    "payout_order_results": [
      {
        "shinkansen_payout_order_id": "8ddfed18-4e75-47ef-ae42-716cbe97d5a0",
        "payout_order_result_id": "1eace19d-189a-4a5c-812c-a2b741dd4ba5",
        "payout_order_id": "c3a3194a-3a31-45ff-91f0-d1025aa11eb8",
        "payout_response_statuses": [
          "ok"
        ],
        "payout_response_messages": [
          "ok"
        ],
        "payout_order_status": "succeeded",
        "split_details": {
          "total_chunks": 3,
          "succeeded_chunks": 3,
          "failed_chunks": 0,
          "currency": "CLP",
          "original_amount": "2994012.00",
          "transferred_amount": "2994012.00",
          "chunks": [
            {
              "index": 1,
              "amount": "998004.00",
              "currency": "CLP",
              "status": "succeeded",
              "payout_response_status": "ok",
              "payout_response_message": "ok"
            },
            {
              "index": 2,
              "amount": "998004.00",
              "currency": "CLP",
              "status": "succeeded",
              "payout_response_status": "ok",
              "payout_response_message": "ok"
            },
            {
              "index": 3,
              "amount": "998004.00",
              "currency": "CLP",
              "status": "succeeded",
              "payout_response_status": "ok",
              "payout_response_message": "ok"
            }
          ]
        }
      }
    ]
  }
}'

No Body

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

Results

Introduction