--- title: "Receives a Result Webhook from Shinkansen Treasury for a final state of a Payout Order." method: POST path: "/responses" tags: ["Results"] --- # Receives a Result Webhook from Shinkansen Treasury for a final state of a Payout Order. `POST /responses` ## Request - Base URL: `https://example.customer.url` - URL: `https://example.customer.url/responses` - Auth: API key in header `Shinkansen-JWS-Signature` Webhook for receiving transaction responses ## Request body - ParticipantResponseMessage: Responses to Shinkansen Treasury customers, sent by Shinkansen Treasury - `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 - `payout_order_results` PayoutOrderResult[]: One or more payout order results (one per payout order). - `shinkansen_payout_order_id` string, uuid, required: UUID Unique identifier of the payout order. Set by Shinkansen on the transaction message. - `payout_order_result_id` string, uuid, required: UUID Unique identifier of the payout order result. Set by Shinkansen Treasury - `payout_order_id` string, uuid, required: UUID Unique identifier of the payout order. Generated by sender. UUID format is required, otherwise the message will be rejected. - `payout_order_status` 'succeeded' | 'partially_succeeded' | 'cancelled' | 'rejected' | 'failed', required: Final Status of the payout order, can't be modified: * `succeeded`: The payout order has been executed and payout was successful. * `partially_succeeded`: The payout order was split into chunks and some succeeded while others failed (only for chunked orders). * `cancelled`: The payout order has been cancelled. * `rejected`: The payout order has been rejected manually or by Shinkansen Copilot. * `failed`: The payout order has failed while executing. - `payout_response_statuses` ResponseStatus[], required: None, 1 or more payout responses (one per payout executed). They are ordered by time of execution. If the payout order is not executed, the array will be empty. - `payout_response_messages` ResponseMessage[], required: None, 1 or more payout responses (one per payout executed). They are ordered by time of execution. If the payout order is not executed, the array will be empty. - `split_details` SplitDetails: **Payout Order Split Details** Information about payout orders that have been divided into multiple chunks (partial payments). **When This Field Is Present?** This field only appears when a payout order has been automatically split into multiple chunks. Not all payout orders are split - this depends on factors such as transaction amount limits and client-specific configuration managed by Shinkansen. **Understanding Split Orders** When a payout order is split: - The total amount is divided into multiple smaller transactions (chunks) - Each chunk is processed independently - Each chunk can have its own status: `succeeded`, `failed`, or `pending` - The `transferred_amount` reflects the sum of amounts from successful chunks only - You can track the progress and status of each individual chunk **Important Notes** - LBTR orders are never split due to regulatory restrictions - If this field is absent, the payout order was processed as a single transaction - Contact Shinkansen if you need chunking enabled or configured for your account - `total_chunks` integer: Total number of chunks this payout order was split into - `succeeded_chunks` integer: Number of chunks that completed successfully - `failed_chunks` integer: Number of chunks that failed - `currency` string: Currency ISO 4217 code (e.g: `"CLP"`) - `original_amount` string: Original amount before splitting (as a string to preserve precision) - `transferred_amount` string: Actual amount transferred (sum of successful chunks, as a string to preserve precision) - `chunks` object[]: Array of individual chunk details - `index` integer: Zero-based index of this chunk - `amount` string: Amount for this specific chunk (as a string to preserve precision) - `currency` string: Currency ISO 4217 code (e.g: `"CLP"`) - `status` 'succeeded' | 'failed' | 'pending': Status of this chunk: - succeeded: chunk was processed successfully - failed: chunk processing failed - pending: chunk is awaiting processing - `payout_response_status` string, nullable: Response status from the payout provider for this chunk - `payout_response_message` string, nullable: Response message from the payout provider for this chunk - `payouts` PayoutResultPayout[]: Structured per-payout information. Each element represents an individual payout executed as part of this order. For chunked orders, each payout includes `chunk_index` and `chunk_amount`. For non-chunked orders those fields are omitted. The flat arrays `payout_response_statuses`, `payout_response_messages`, etc. are kept for backwards compatibility. This field provides the same data in a structured, per-payout format. - `shinkansen_transaction_id` string, uuid, required: Shinkansen unique identifier for this payout transaction. - `transaction_id` string, uuid, required: Unique identifier for the payout transaction assigned by the payment operator. - `state` 'ok' | 'error' | 'invalid', required: State of this individual payout: - `ok`: payout succeeded - `error`: payout failed - `invalid`: payout was rejected due to validation errors - `response_status` 'ok' | 'invalid' | 'error_creditor_account_not_found' | 'error_creditor_account_detail_mismatch' | 'error_creditor_account_over_limits' | 'error_creditor_account_closed' | 'error_creditor_account_currency_mismatch' | 'error_creditor_reject' | 'error_creditor_fi_offline' | 'error_payment_rail_offline' | 'error_debtor_account_not_found' | 'error_debtor_account_detail_mismatch' | 'error_debtor_account_over_limits' | 'error_debtor_insufficient_funds' | 'error_debtor_reject' | 'error_debtor_fi_offline' | 'error_delivery_ttl_expired' | 'error_expired' | 'error', required: Status as reported by the payout operator (or Shinkansen if the operator is down): * `ok`: The payout was successful. * `invalid`: The request failed some validation * `error_creditor_account_not_found`: The destination account doesn't exist * `error_creditor_account_detail_mismatch`: Something is wrong with the destination account details * `error_creditor_account_over_limits`: The destination account is over the limits set by the creditor bank/institution * `error_creditor_account_closed`: The destination account is closed, cancelled or blocked * `error_creditor_account_currency_mismatch`: The payout currency doesn't match the currency of the destination account * `error_creditor_reject`: The payout was returned or rejected by the creditor bank/institution * `error_creditor_fi_offline`: The creditor bank/institution is temporarily offline * `error_payment_rail_offline`: The payment rail used by Shinkansen/PO is temporarily offline * `error_debtor_account_not_found`: The origin account doesn't exist * `error_debtor_account_detail_mismatch`: Something is wrong with the origin account details * `error_debtor_account_over_limits`: The origin account is over the limits set by the debtor bank/institution or the payout operator. * `error_debtor_insufficient_funds`: The origin account doesn't have enough funds to cover the payout amount. * `error_debtor_reject`: The debtor bank/institution rejected the debit * `error_debtor_fi_offline`: The debtor bank/institution is temporarily offline * `error_delivery_ttl_expired`: The transaction could not be delivered to the source bank/institution before the TTL specified on the original payout message. * `error_expired`: The payout expired at the bank/institution before it could be processed (for example, a cut-off time or an acceptance window was exceeded) * `error`: Other errors not categorized above - `response_message` string, required: Human-readable message further explaining the status. - `error_codes` string[]: Error codes returned by the payment operator, if any. - `error_messages` string[]: Error messages returned by the payment operator, if any. - `chunk_index` integer, nullable: 1-based index of this payout within the split order. Only present for chunked payout orders. - `chunk_amount` string, nullable: Amount assigned to this specific chunk (as a string to preserve precision). Only present for chunked payout orders. ## 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/treasury-participant-webhooks.md) - [All operations](https://skmtc.dev/shinkansen/apis/treasury-participant-webhooks/llms.txt) - [OpenAPI document](https://skmtc.dev/shinkansen/apis/treasury-participant-webhooks/revisions/4f5eb0bcf64f?raw)