---
title: "Create payables"
method: POST
path: "/payables"
tags: ["Payables"]
---

# Create payables

`POST /payables`

Creates one or more payables, atomically, for the signed sender's entity. Each payable may carry its full payment instruction (`debtor`, `creditor`, routing/policy hints) or be completed later with a `PATCH`. The pair (entity, `external_id`) is unique, so a retry cannot duplicate a commitment: a repeated `external_id` is a `409` and rolls the whole batch back.

The request body is a signed envelope; the `Shinkansen-JWS-Signature` header must carry a JWS detached signature over the raw body, validated against the customer's certificates.

## Request body

- PayableMessage — Signed envelope to create one or more payables, atomically, for the sender's entity. Mirrors the payout order message: a `document` with a `header` wrapping a `payables` array. The whole body is signed with a JWS detached signature (`Shinkansen-JWS-Signature` header). The entity is derived from the signed `document.header.sender.fin_id` and authorized against the authenticated customer — never from an unsigned field. If any payable in the batch fails validation the whole request is rolled back.
  - `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
    - `payables` Payable[], required — One or more payables to create.
      - `external_id` string, required — Identifier of the commitment in the source system. Together with the sender's entity it forms the uniqueness key `(local_entity_id, external_id)`.
      - `payable_type` string — Optional type of the payable, configured per entity (e.g. `redemption`, `contribution`). Selects the ledger accounts used on accrual.
      - `amount` string, required — Amount owed, as a decimal string. Must be greater than 0.
      - `currency` string, required — ISO 4217 currency code (3 letters, e.g. `CLP`).
      - `state` 'waiting_order' | 'taken' — Optional initial state. Defaults to `waiting_order`. Use `taken` to record a commitment that the core has already taken to pay itself (Treasury only observes; no PayoutOrder is generated).
      - `due_date` string, date — Optional due date of the commitment.
      - `description` string — Optional human-readable description.
      - `metadata` object — Optional free-form metadata (escape hatch for client-specific data, e.g. a core edit-lock flag). Not interpreted by Treasury.
      - `debtor` PayableDebtor — Paying account (debtor) of the payment instruction. This is a reduced block: the paying party IS the signed sender's entity, so only the account reference travels (no name or identification). It is resolved against the sender entity's own bank accounts, matching the account number with leading zeros stripped. An unknown or foreign account — or an account whose currency does not match the payable's currency (accounts are mono-currency) — is rejected as a per-item 422.
        - `financial_institution` object, required — The paying bank, in the Shinkansen network.
          - `fin_id_schema` 'SHINKANSEN', required — Identification schema of the paying bank. Must be `SHINKANSEN`.
          - `fin_id` string, required — Shinkansen id of the paying bank. See https://docs.shinkansen.tech/docs/instituciones-financieras.
        - `account` string, required — Account number of the paying account. Matched against the sender entity's bank accounts with leading zeros stripped.
        - `account_type` string — Optional account type (e.g. `current_account`).
      - `creditor` PayableCreditor — Payee (creditor) of the payment instruction, in ISO 20022 vocabulary. Every inner field is optional — a payable may arrive before its instruction is complete, and is completed later with a `PATCH`. An all-empty block is treated as no creditor. On `PATCH` the whole block is replaced (never merged); an explicit `null` clears it.
        - `name` string — Payee name.
        - `email` string — Payee email. Required by the PayoutOrder generated to settle this payable before it can execute.
        - `account` string — Destination account number.
        - `account_type` string — Destination account type (e.g. `current_account`).
        - `identification` object — Payee identification. Both fields are needed before the payable can be ordered, unless the payee is international (`financial_institution .fin_id_schema` of `BIC` or `USABA`).
          - `id` string — Identifier value (e.g. a RUT).
          - `id_schema` string — Identification schema (e.g. `CLID`).
        - `financial_institution` object — Destination bank, in the Shinkansen network.
          - `fin_id` string — Shinkansen id of the destination bank. See https://docs.shinkansen.tech/docs/instituciones-financieras.
          - `fin_id_schema` string — Identification schema of the destination bank — `SHINKANSEN` for banks in the network, `BIC` or `USABA` for an international payee.
      - `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_mode` 'default' | 'immediate' | 'deferred' — Execution mode for the transaction.
      - `dispatch_policy` 'automatic' | 'manual' — Declares whether the PayoutOrder settling this payable is meant to be generated automatically (`automatic`) or by an operator from the dashboard (`manual`). Stored and reported as sent; omitting it leaves it unset.
      - `execution_hint` 'internal' | 'external' — Who executes the payment: `internal` (Shinkansen pays it) or `external` (the client pays it another way). Orthogonal to `dispatch_policy`. An `external` payable is settled by a non-automated PayoutOrder and is exempt from the `payment_rail` completeness check.

## Response `201`

Payables successfully created. Returns the created batch with their system-assigned fields.

- object
  - `payables` PayableResult[], required — The created payables.
    - `id` integer, required — System-assigned identifier of the payable.
    - `external_id` string, required — Identifier of the commitment in the source system.
    - `local_entity_id` integer, required — Entity that owns the payable (resolved from the signed sender).
    - `payable_type` string, nullable — Type of the payable, configured per entity.
    - `amount` string, required — Amount owed, as a decimal string. Values read back from storage carry the column's scale (5 decimals, e.g. `150000.00000`); the creation response echoes the amount as it was sent.
    - `currency` string, required — ISO 4217 currency code.
    - `state` 'waiting_order' | 'ordered' | 'taken' | 'paid' | 'wont_pay', required — Current state of the payable.
    - `due_date` string, date, nullable — Due date of the commitment.
    - `description` string, nullable — Human-readable description.
    - `metadata` object — Free-form metadata.
    - `debtor` object, nullable — Paying account, rebuilt from the resolved bank account (reflects the account the payable will actually charge). `null` when no paying account is set yet.
      - `financial_institution` object
        - `fin_id_schema` string — Always `SHINKANSEN`.
        - `fin_id` string — Shinkansen id of the paying bank.
      - `account` string — Account number of the paying account.
      - `account_type` string, nullable — Account type.
    - `creditor` object, nullable — Payee, in ISO 20022 vocabulary. `null` when no payee is set yet.
      - `name` string, nullable
      - `email` string, nullable
      - `account` string, nullable
      - `account_type` string, nullable
      - `identification` object, nullable — Present only when an id was supplied.
        - `id` string
        - `id_schema` string
      - `financial_institution` object, nullable — Present only when a destination bank was supplied.
        - `fin_id` string
        - `fin_id_schema` string
    - `payment_rail` string, nullable — Routing hint carried by the payable. Same values as the `payment_rail` request field.
    - `execution_mode` 'default' | 'immediate' | 'deferred' | 'null', nullable — Routing hint carried by the payable.
    - `dispatch_policy` 'automatic' | 'manual' | 'null', nullable — Declared PayoutOrder generation policy.
    - `execution_hint` 'internal' | 'external' | 'null', nullable — Who executes the payment.
    - `inserted_at` string, date-time — Creation timestamp.
    - `updated_at` string, date-time — Last update timestamp.

## Other responses

- `401` — The `Shinkansen-Treasury-Api-Key` header is missing or does not match a Treasury customer. The body is the plain text `Unauthorized`.
- `403` — The JWS signature is missing, unparseable or invalid. The body names which case occurred. The same status is returned — with the plain text body `Forbidden` instead of a JSON payload — when the API key lacks the `payables:all` scope.
- `404` — Not found. The sender `fin_id` is unknown or not owned by the caller, or (on `PATCH`) the payable does not exist. A foreign `fin_id` is deliberately a 404 (no existence leak). On `POST /payables/validate_signature` an invalid signature is also reported as 404, with an `{ "error": "Invalid signature" }` body.
- `409` — A payable with the same `external_id` already exists for the entity (the uniqueness key `(local_entity_id, external_id)` is violated). The whole batch is rolled back.
- `422` — Validation error. The `errors` object holds the failing fields. On create, per-item errors are keyed by the item's `external_id`; on update, by field name; on list, by the invalid query parameter.

---

[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)