---
title: "Update a payable"
method: PATCH
path: "/payables/{external_id}"
tags: ["Payables"]
---

# Update a payable

`PATCH /payables/{external_id}`

Updates the mutable attributes of a single payable and/or triggers the integrator state transition to `taken`. The payable is named by the `external_id` path parameter; the signed envelope's `payables` array must carry exactly one element with the fields to change.

Attributes may only be edited while the payable is `waiting_order`. The only state transition an integrator may trigger here is `waiting_order → taken` (the core takes the record to pay it itself); any other value for `state` is rejected. The request is signed with the `Shinkansen-JWS-Signature` header.

## Path parameters

- `external_id` string, required

## Request body

- PayableUpdateMessage — Signed envelope to update a single payable. Same shape as the create message, but the `payables` array must carry exactly one element — the payable named by the `external_id` path parameter. 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 caller.
  - `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` PayableUpdate[], required — Exactly one payable, carrying the fields to update.
      - `payable_type` string — Type of the payable, configured per entity.
      - `amount` string — Amount owed, as a decimal string. Must be greater than 0.
      - `currency` string — ISO 4217 currency code (3 letters).
      - `state` 'taken' — Optional state transition. The only transition an integrator may trigger through this endpoint is taking the record (`waiting_order → taken`), so the only accepted value is `taken`. Any other value is rejected.
      - `due_date` string, date — Due date of the commitment.
      - `description` string — Human-readable description.
      - `metadata` object — Free-form metadata (not interpreted by Treasury).
      - `debtor` object — 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` object — 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 or by an operator.
      - `execution_hint` 'internal' | 'external' — Who executes the payment. An `external` payable is settled by a non-automated PayoutOrder.

## Response `200`

The payable was successfully updated. Returns the updated payable.

- object
  - `payable` PayableResult, required — A payable as returned by the API.
    - `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.
- `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)