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

# Sends a payin message

`POST /messages/payins`

Sends a new payin transaction, requesting or expecting an incoming payment.
If the transaction request/expectaton is successful, it will end up moving funds from an account on a external network (e.g: traditional bank accounts) to an account of a participant of the Shinkansen network.

## Request body

- OriginalPayinMessage — Payin message, as sent originally by the participant requesting or expecting an incoming payment
  - `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` OriginalPayinTransaction[], required — One or more payin transactions.
      - `transaction_type` string, required — Transaction type. Always should be `"payin"` for this type of transaction.
      - `payin_type` 'interactive_payment' | 'expected_payment' | 'automated_payment', required — Payin type. Can be: * `interactive_payment` for requesting payments which will be completed by the debtor/user (redirecting to a web page/view or sending a payment link). * `automated_payment` for pre-approved payments requests (known in different markets as "domiciliacion", "pago automatico de cuentas", "direct debit", "invisible payments", etc.) * `expected_payment` for payments that are expected to be made manually by the debtor/user in the future.
      - `interactive_payment_provider` 'khipu' | 'co_pse' — Specific provider to use for the interactive payment. Useful when more than one provider is available for the country, account type, etc., and you want to force a specific one.
      - `interactive_payment_success_redirect_url` string, uri — URL to redirect the user to after a successful payment. Only required for `interactive_payment` payin type.
      - `interactive_payment_failure_redirect_url` string, uri — URL to redirect the user to after a failed payment. Only required for `interactive_payment` payin type.
      - `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 — 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 — Transaction description. Sometimes shown to the debtor.
      - `expiration_date` string, date-time — The latest expected date-time (in ISO 8601 format) after which Shinkansen can assume that the payment will not be made.
      - `debtor` PayinDebtor — The origin of the funds movement. No field is strictly required and even the whole debtor could be omitted for some interactive payments. Check each field for details.
        - `name` string — Debtor name. The legal name of the legal/natural person sending the funds, if known in advance. Strongly recommended to be present for automated and expected payments. Not required for most interactive payments.
        - `identification` object — 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 — Bank account number of the debtor. Typically used by automated/expected payments. Not required for most interactive payments.
        - `account_type` string — Account type. See https://docs.shinkansen.tech/docs/tipos-de-cuentas for possible values.
        - `email` string, email — E-mail of the legal or natural person sending the funds. Optional.
      - `creditor` PayinCreditor, required — The destination of the fund movement (i.e, the account where the funds will eventually get collected)
        - `name` string, required — Creditor name. Must refer to the legal name of the participant sending the payin 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, 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
        - `account` string, required — Bank account number of the creditor at the referenced bank or financial institution. The account must be previously setup to be able to receive payments of the corresponding `payin_type` (automated, interactive or expected)
        - `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 (some operators will send email notifications there).

## Response `200`

Message correctly received. Does NOT mean the transaction was succesful. Transaction result is communicated back via webhook.
Includes the transaction's `shinkansen_id`s and urls for any transactions of `interactive_payment` type.

- object — 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
    - `interactive_payment_url` string, uri — The url to redirect the user to to initiate payment. Only included for payins with `interactive_payment` type.

## 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/revisions/1e4a6760b7e8/schema)