---
title: "Validate a signature without persisting"
method: POST
path: "/payables/validate_signature"
tags: ["Payables"]
---

# Validate a signature without persisting

`POST /payables/validate_signature`

Verifies the JWS signature of a signed envelope against the sender's certificates without persisting anything — useful to test the signing setup before sending real payables. Mirrors `POST /payout_orders/validate_signature`.

Responds 200 when the signature is valid, and 404 when it is not (or when the sender `fin_id` is unknown or not owned by the caller — no existence leak). A malformed envelope — one that carries no `document.header.sender.fin_id` — is a 422 instead: there is nothing to resolve the sender against.

## 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 `200`

The JWS signature is valid.

- object
  - `message` string

## 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 API key is valid but lacks the `payables:all` scope. The body is the plain text `Forbidden`.
- `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/revisions/1e4a6760b7e8/schema)