--- title: "Sends a payout response (used by payout operators)" method: POST path: "/messages/responses" tags: ["Transactions & Responses"] --- # Sends a payout response (used by payout operators) `POST /messages/responses` The payout operator reply to the payout transaction using this endpoint ## Request body - OriginalPayoutResponseMessage — Payout response, as sent by the payment financial institution - `document` object, required — Envelops the message content - `header` OriginalMessageHeader, required — Header with meta-data - `message_id` string, uuid, required — UUID Unique identifier of the message. Generated by the participant initiating the transactions (or sending the responses) inside this message. UUID format is required, otherwise the message will be rejected. - `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) inside to this message. - `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 - `options` object — Optional configuration parameters for the message - `responses` OriginalPayoutResponse[], required — One or more payouts responses (one per transaction). - `transaction_type` string, required — Transaction type. Always should be `"payout"` for this type of transaction. - `transaction_id` string, required — UUID Unique identifier of the transaction. Generated by original sender of the payout. - `shinkansen_transaction_id` string, required — UUID Unique identifier of the transaction. Set by Shinkansen on the transaction message. - `response_id` string, uuid, required — UUID Unique identifier of the transaction *response*. Set by the payout operator. - `response_status` 'ok' | 'invalid' | 'error_creditor_account_not_found' | 'error_creditor_account_detail_mismatch' | 'error_creditor_account_over_limits' | 'error_creditor_fi_offline' | 'error_payment_rail_offline' | 'error_debtor_account_over_limits' | 'error_debtor_insufficient_funds' | 'error_delivery_ttl_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_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_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_delivery_ttl_expired`: The transaction could not be delivered to the source bank/institution before the TTL specified on the original payout message. * `error`: Other errors not categorized above - `response_message` string, required — Human-readable message further explaining the status. ## 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) - `403` — Forbidden (e.g: wrong API Key) - `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.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)