--- title: "Sends one or more payout orders to be automated" method: POST path: "/payout_orders" tags: ["Payout orders"] --- # Sends one or more payout orders to be automated `POST /payout_orders` Creates one or more payout orders that are automatically reviewed by the Treasury Copilot system according to predefined organizational rules. This endpoint supports batch processing, allowing you to submit multiple payout orders in a single request. Each payout order is subject to validation against the configured rules. If approved, funds will be moved from the account of one participant of the network to some account on an external network (e.g., traditional bank accounts). ## Request body - PayoutOrderMessage — Payout order message that instructs the Treasury Copilot system to execute one or more payouts if approved. This endpoint supports batch processing, allowing you to submit multiple payout orders in a single request. - `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 - `payout_orders` PayoutOrder[], required — One or more payout orders. - `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. - `currency` string, required — Currency ISO 4217 code (e.g: `"CLP"`) - `amount` string, required — Amount, ISO20022-compatible: Up to 18 integer digits, optional decimal separator ".", up to 5 fraction digits (also optional). By using a string we avoid issues with floating-point arithmetic as well as integer type limits on some JSON implementations. - `description` string, required — Payout order description. Some times shown to the creditor (e.g in email notifications). Will be shown for approvals. - `execution_date` string, date-time — Requested execution date in ISO 8601 format. The execution date can be in the future for delayed transactions or be a current timestamp for regular transactions where the funds are expected to move as soon as possible. Set by the sender. - `reference_number` string — Up to 7 integer digits - `tracking_key` string — Up to 30 alpha numeric characters (letters and digits, no special characters) - `execution_mode` 'default' | 'immediate' | 'deferred' — Execution mode for the transaction. - `payment_purpose_category` 'default' | 'salary_payment' | 'supplier_payment' | 'dividend' | 'confirming' | 'tax_payment' | 'pe_cts' | 'bonus_payment' | 'compensation_payment' | 'holiday_payment' | 'overtime_payment' | 'cash_management_transfer' | 'card_bulk_clearing' | 'credit_card_payment' | 'trade_settlement_payment' | 'debit_card_payment' | 'deliver_against_payment' | 'epayment' | 'fee_collection_and_interest' | 'fee_collection' | 'person_to_person_payment' | 'government_payment' | 'hedging' | 'irrevocable_credit_card_payment' | 'irrevocable_debit_card_payment' | 'intra_company_payment' | 'interest' | 'lockbox_transactions' | 'loan' | 'commercial' | 'consumer' | 'other_payment' | 'pension_payment' | 'represented' | 'reimbursement_received_credit_transfer' | 'receive_against_payment' | 'securities' | 'social_security_benefit' | 'trade' | 'treasury_payment' | 'value_added_tax_payment' | 'with_holding' | 'cash_management_sweep_account' | 'cash_management_top_account' | 'cash_management_zero_balance_account' | 'crossborder_mipayments' | 'foreign_currency_domestic_transfer' | 'cash_in_pre_credit' | 'cash_out_notes_coins' | 'carrier_guarded_wholesale_valuables' | 'saving' | 'profit_sharing_payment' — The payment purpose category of the transaction. - `po_connection` 'default' | 'api' | 'h2h' — The preferable connection type to deliver the transaction. - `payment_rail` 'default' | 'swift' | 'swift_gpi' | 'swift_go' | 'cl_tef' | 'cl_tef_masiva' | 'cl_batch_credito' | 'cl_batch_debito' | 'cl_lbtr' | 'co_ach_batch' | 'co_ach_transfiya' | 'co_cenit_batch' | 'co_redeban' | 'co_breb' | 'co_pse' | 'co_lbtr' | 'mx_spei' | 'mx_spei_b' | 'mx_spid' | 'mx_batch_domiciliation' | 'mx_batch_payroll' | 'mx_batch_referenced' | 'mx_tef' | 'pe_cce_batch' | 'pe_cce_inmediate' | 'pe_visa_direct' | 'pe_lbtr' | 'cashier_back' — Payment rail for the transaction. - `tags` object — Optional key-value metadata attached to the payout order by the sender. Each key maps to a single string value. Tags are stored as sent and returned in the payout order status, allowing the sender to attach custom information (such as internal references or categorization) to the order. - `debtor` PayoutDebtor, required — The origin of the funds movement - `name` string, required — Debtor name. Must refer to the legal name of the participant sending the payout message. - `identification` object, required — The identifier for a legal or natural person - `id_schema` string, required — Identification schema. See https://docs.shinkansen.tech/docs/tipos-de-identificacion - `id` string, required — The actual identification "number" (but not always just numbers). For `"MXRFC"` schema (Mexican RFCs), it can contain numbers and letters (13 for natural persons, 12 for legal entities). For `"MXCURP"` schema (Mexican CURPs) identifying natural persons, it can contain numbers and letters (18 characters). For `"COCC"`, `"COTI"`, `"CONUIP"`, and `"COCE"` schemas (all identifying natural personal in Colombia), use only numbers. For `"CONIT"` schema (Colombian NITs, for legal entities), also use only numbers. For `"PASS"` schema (Passports, used in Colombia for some accounts in name of foreign natural persons), it can contain numbers and letters (and generally whatever is literally printed as a passport number). For `"CLID"` schema (Chilean RUTs, for legal entities and natural persons) you must use the XXXXXXXX-X format: `^\d{8}[-][0-9kK]$`. See https://docs.shinkansen.tech/docs/tipos-de-identificacion for more details. - `financial_institution` object — 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 - `account` string, required — Bank account number of the debtor at the referenced bank or financial institution. - `account_type` string, required — Account type. See https://docs.shinkansen.tech/docs/tipos-de-cuentas for possible values. - `email` string, email, required — E-mail of the legal or natural person sending the funds (some operators will send email notifications to the sender as well as the receiver). - `creditor` PayoutCreditor, required — The destination of the funds movement - `name` string, required — Name of the legal or natural person receiving the funds. - `identification` object, required — The identifier for a legal or natural person - `id_schema` string, required — Identification schema. See https://docs.shinkansen.tech/docs/tipos-de-identificacion - `id` string, required — The actual identification "number" (but not always just numbers). For `"MXRFC"` schema (Mexican RFCs), it can contain numbers and letters (13 for natural persons, 12 for legal entities). For `"MXCURP"` schema (Mexican CURPs) identifying natural persons, it can contain numbers and letters (18 characters). For `"COCC"`, `"COTI"`, `"CONUIP"`, and `"COCE"` schemas (all identifying natural personal in Colombia), use only numbers. For `"CONIT"` schema (Colombian NITs, for legal entities), also use only numbers. For `"PASS"` schema (Passports, used in Colombia for some accounts in name of foreign natural persons), it can contain numbers and letters (and generally whatever is literally printed as a passport number). For `"CLID"` schema (Chilean RUTs, for legal entities and natural persons) you must use the XXXXXXXX-X format: `^\d{8}[-][0-9kK]$`. See https://docs.shinkansen.tech/docs/tipos-de-identificacion for more details. - `financial_institution` object — 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 - `account` string, required — Bank account number of legal or natural person receiving the funds. - `account_type` string, required — Account type. See https://docs.shinkansen.tech/docs/tipos-de-cuentas for possible values. - `email` string, email, required — E-mail of the legal or natural person receiving the funds (for email notifications). - `address` object — Physical address information - `street_name` string — Name of the street - `town_name` string — Name of the town or city - `country_code` string — ISO 3166-1 alpha-2 country code - `building_number` string — Building or house number - `country_subdivision` string — State, province, or region within the country - `postal_code` string — Postal or ZIP code - `address_line` string — Additional address line for extra information - `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 - `batch` object — Optional metadata for the batch created from this request. All the payout orders in a single request are grouped into one batch. - `description` string — Optional human-readable name for the batch, shown in the dashboard (e.g. "Monthly payroll"). Rejected if longer than 255 characters. ## Response `200` Message correctly received. Does NOT mean the payout order will be executed and successful. - PayoutOrderExternalId — Mapping from payout_order_id (external system id) to Shinkansen treasury payout order id. - `payout_orders` object[], required — Array of mappings between original payout_order_id and shinkansen_payout_order_id - `payout_order_id` string, uuid, required — The external system id of the payout order. - `shinkansen_payout_order_id` string, uuid, required — The corresponding shinkansen_transaction_id ## 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)