---
title: "Send a payout message to be processed as a payout order"
method: POST
path: "/messages/payouts/as_payout_order"
tags: ["Payout orders"]
---

# Send a payout message to be processed as a payout order

`POST /messages/payouts/as_payout_order`

## Request

- Base URL: `https://api.treasury.shinkansen.finance/v1`
- URL: `https://api.treasury.shinkansen.finance/v1/messages/payouts/as_payout_order`
- Auth: API key in header `Shinkansen-Treasury-Api-Key` and API key in header `Shinkansen-JWS-Signature`

Accepts a payout message written in the Payouts `document.transactions` format and processes it as a payout order, so senders already integrated with the Payouts API can reach Treasury without reshaping their payload.

The body must carry `document.transactions`; a body without it is rejected with 400. Once accepted, the request follows exactly the same validation and signing as `POST /payout_orders`.

The response, however, stays in the Payouts vocabulary: the id mapping comes back under `transactions`, with `transaction_id` and `shinkansen_transaction_id`, and not under `payout_orders`.

## Request body

- AsPayoutOrderMessage: Payout message, as sent originally by the participant instructing the payout
  - `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
    - `transactions` OriginalPayoutTransaction[], required: One or more payouts transactions.
      - `transaction_type` string, required: Transaction type. Always should be `"payout"` for this type of transaction.
      - `transaction_id` string, uuid, required: UUID Unique identifier of the transaction. 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: Optional transaction description. May be empty. Some times shown to the creditor (e.g in email notifications). For BANCO_BICE_CL transactions, maximum length is 70 characters.
      - `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.
      - `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.
      - `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
      - `ttl` string, date-time: Optional time to live for the transaction. The transaction will be rejected by Shinkansen if it can't be *delivered* to the payout operator before this time. The operator (bank or institution) might or might not support the TTL feature, so if the transaction has been delivered but no response has been received by Shinkansen, the transaction will remain pending until a response by the operator is received.
  - `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 orders will be executed and successful.

This endpoint answers in the Payouts vocabulary it accepts, so the mapping is returned under `transactions` with `transaction_id` and `shinkansen_transaction_id`, not under `payout_orders`.

- object
  - `transactions` TransactionIdMapping[], required: Array of mappings between the original transaction_id and the shinkansen_transaction_id
    - `transaction_id` string, uuid, required: The external system id of the transaction.
    - `shinkansen_transaction_id` string, uuid, required: The id assigned by Shinkansen to the transaction.

## Other responses

- `400`: The request was rejected before or during validation. Two bodies are possible: a single error string when the body does not carry `document.transactions`, which is what this endpoint translates, and the list of validation errors once the body is accepted for processing.
- `403`: Forbidden (e.g: wrong API Key)
- `404`: The receiver in `document.header.receiver.fin_id` is not a valid Shinkansen receiver.
- `409`: The request was already seen and processed before, so nothing new was created. Typically happens when a request is re-sent because the sender isn't sure it was correctly received (e.g. a network failure while the 2xx response was in flight). Two bodies are possible. When the whole message is a duplicate, the response carries only an error string. When the message is new but the transactions in it were already created, the response carries the id mapping for the ones already known, in the same shape as the 200, which is how the `shinkansen_transaction_id` assigned on the first attempt can be recovered. That array can be empty. Neither body replays the rest of the original payload.

---

[API](https://skmtc.dev/shinkansen/apis/treasury-shinkansen-endpoints.md) - [All operations](https://skmtc.dev/shinkansen/apis/treasury-shinkansen-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/shinkansen/apis/treasury-shinkansen-endpoints/revisions/2d3ec7684af3?raw)