---
title: "Sends a payout message"
method: POST
path: "/messages/payouts"
tags: ["Transactions & Responses"]
---

# Sends a payout message

`POST /messages/payouts`

Sends a new payout message, which — if successful — will move funds from the account of one participant of the network to some account on an external network (e.g: traditional bank accounts)

## Request body

- OriginalPayoutMessage — 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.

## Response `200`

Message correctly received. Does NOT mean the transaction was succesful. Transaction result is communicated back on another message.

- TransactionIdsMapping — Mapping from original transaction ids to shinkansen transaction ids
  - `transactions` object[], required — Array of mappings between original transacion_id and shinkansen_transaction_id
    - `transaction_id` string, uuid, required — The original transaction_id
    - `shinkansen_transaction_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)