> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Prepare Transfer Signing Payload
> Use this endpoint to freeze the canonical STR0008 payload for a previously initiated TED OUT transfer and obtain the exact bytes that must be signed before calling Process Transfer. The response includes a `signingArtifactId` and a reserved `transferId`. The reserved `transferId` is not queryable until Process Transfer succeeds.
Use the `X-Idempotency` header for guaranteed deduplication. Repeated calls with the same key replay the cached response.
## OpenAPI
````yaml /en/openapi/v3-current/ted.yaml post /v1/transfers/signing/prepare
openapi: 3.0.3
info:
title: Bank Transfer (TED) Plugin API
description: >-
Complete API for Brazilian bank transfers (TED OUT, TED IN, P2P) through the
Lerian platform, including transfer initiation, processing, status tracking,
and cancellation.
version: 3.3.1
servers:
- url: https://plugin-br-bank-transfer.sandbox.lerian.net
description: Sandbox (placeholder — not yet available for public access)
security:
- BearerAuth: []
tags:
- name: Transfers API
description: Endpoints for initiating, processing, tracking, and cancelling transfers.
- name: Webhooks
description: >-
Endpoints for registering and managing tenant-scoped webhook subscriptions
for transfer events.
- name: Webhook DLQ
description: Endpoints for inspecting and retrying webhook dead-letter queue messages.
- name: Health API
description: Endpoints for checking service liveness and readiness.
paths:
/v1/transfers/signing/prepare:
post:
tags:
- Transfers API
summary: Prepare Transfer Signing Payload
description: >-
Use this endpoint to freeze the canonical STR0008 payload for a
previously initiated TED OUT transfer and obtain the exact bytes that
must be signed before calling Process Transfer. The response includes a
`signingArtifactId` and a reserved `transferId`. The reserved
`transferId` is not queryable until Process Transfer succeeds.
Use the `X-Idempotency` header for guaranteed deduplication. Repeated
calls with the same key replay the cached response.
operationId: prepareSigning
parameters:
- $ref: '#/components/parameters/XOrganizationId'
- $ref: '#/components/parameters/XIdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PrepareSigningRequest'
examples:
prepare:
summary: Prepare signing for an initiation
value:
initiationId: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b
responses:
'200':
description: >-
Indicates that the canonical payload was generated and is ready to
be signed.
content:
application/json:
schema:
$ref: '#/components/schemas/PrepareSigningResponse'
examples:
success:
summary: Signable payload returned
value:
signingArtifactId: 019c96a0-bb10-7def-a1b2-3c4d5e6f7a8b
transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d
controlNumber: '202602010001'
algorithm: RSA_PKCS1_V15_SHA256
payload: ...
payloadHash: >-
8f0c7f5c1c7b4d9f2f5c7d1a0d4c9a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f
expiresAt: '2026-02-02T15:30:00-03:00'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/InitiationNotFound'
'409':
$ref: '#/components/responses/AlreadyProcessed'
'410':
$ref: '#/components/responses/InitiationExpired'
'422':
$ref: '#/components/responses/SigningPayloadInvalid'
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalServerError'
'502':
$ref: '#/components/responses/BadGateway'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
parameters:
XOrganizationId:
name: X-Organization-Id
in: header
required: true
description: >-
Midaz organization scope for the request, used for downstream CRM, Fees,
and Midaz calls. Required on org-scoped transfer routes in every
deployment mode; a missing or non-UUID value returns 400. This is not
the tenant identifier — tenantId is derived from the bearer JWT or
authenticated context, never from this header. Background workers (TED
IN poller, reconciliation) have no request header and, in single-tenant
mode, fall back to the deployment's `ORGANIZATION_ID` env.
schema:
type: string
format: uuid
example: 019c96a0-0a98-7287-9a31-786e0809c769
XIdempotencyKey:
name: X-Idempotency
in: header
required: true
description: >-
Required idempotency key for safe retries. Use a UUID v4 or unique
business identifier. If the same key is sent again and the original
request was already processed, the cached response is returned.
See [Retries and idempotency](/en/reference/retries-idempotency) for
details.
schema:
type: string
maxLength: 255
example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b
schemas:
PrepareSigningRequest:
type: object
required:
- initiationId
properties:
initiationId:
type: string
format: uuid
description: The initiation ID returned by the Initiate Transfer endpoint.
example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b
PrepareSigningResponse:
type: object
required:
- signingArtifactId
- transferId
- controlNumber
- algorithm
- payload
- payloadHash
- expiresAt
properties:
signingArtifactId:
type: string
format: uuid
description: >-
Identifier of the frozen signing artifact. Pass this value to
Process Transfer along with the signature.
example: 019c96a0-bb10-7def-a1b2-3c4d5e6f7a8b
transferId:
type: string
format: uuid
description: >-
The transfer ID reserved for the eventual TED OUT. Not queryable
until Process Transfer succeeds.
example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d
controlNumber:
type: string
maxLength: 20
description: The JD SPB control number reserved for this transfer.
example: '202602010001'
algorithm:
type: string
enum:
- RSA_PKCS1_V15_SHA256
description: >-
The signing algorithm. Pinned per JD SPB contract; any other value
is rejected at Process Transfer.
example: RSA_PKCS1_V15_SHA256
payload:
type: string
description: >-
The canonical STR0008 payload, exactly as it will be submitted to JD
SPB.
example: ...
payloadHash:
type: string
description: >-
Hex-encoded SHA-256 digest of the payload. Echo this value at
Process Transfer for integrity validation.
example: 8f0c7f5c1c7b4d9f2f5c7d1a0d4c9a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f
signableContent:
type: string
description: >-
The `ConteudoAssinado` extraction for external signers. Present only
when an external signing builder is configured.
example: ...
expiresAt:
type: string
format: date-time
description: >-
The time when the signing artifact expires. Process Transfer must be
called before this timestamp.
example: '2026-02-02T15:30:00-03:00'
ErrorResponse:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- service
- category
- message
- requestId
properties:
code:
type: string
description: >-
The stable error code. Plugin errors use the `BTF-XXXX` format;
JD SPB business/auth rejections pass through the raw vendor code
verbatim (e.g. `AAC90`, `ACE95`, `DVE01`), and transport-level
JD failures surface the synthetic markers `TRANSPORT` or
`JD_MISSING_CODE`. Match on this value rather than on the HTTP
status.
example: BTF-0010
service:
type: string
description: The service or domain that produced the error.
example: plugin
category:
type: string
description: Machine-readable error category used for retry decisions.
enum:
- deterministic
- transient
- rate_limit
- plugin
example: deterministic
message:
type: string
description: A human-readable error summary.
example: >-
Transfers can only be initiated Monday-Friday between 06:30 and
17:00 Brasília time
requestId:
type: string
description: The request correlation ID. Present even when empty.
example: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
fields:
type: object
additionalProperties: true
description: >-
Structured validation or retry metadata when available.
Field-level, header, path, and query validation details are all
returned here.
example:
currentTime: '2026-02-01T18:30:00-03:00'
operatingHours: Mon-Fri 06:30-17:00 UTC-3
responses:
BadRequest:
description: >-
Indicates that the request contains invalid input. Check the field
details for specific validation errors.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidInput:
summary: Validation error
value:
error:
code: BTF-0001
service: plugin
category: deterministic
message: >-
The request contains invalid fields. Check the field details
below.
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
fields:
recipientIspb: must be 8 digits
amount: must be positive
Unauthorized:
description: Indicates that the request is missing a valid authentication token.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Missing authorization
value:
error:
code: BTF-0401
service: plugin
category: deterministic
message: Missing or invalid authentication token
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
Forbidden:
description: >-
Indicates that the caller is authenticated but lacks permission for this
operation, or the tenant is not licensed for this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
notLicensed:
summary: Tenant not licensed
value:
error:
code: BTF-0403
service: plugin
category: deterministic
message: Tenant is not licensed to use this endpoint
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
permissionDenied:
summary: Caller lacks permission
value:
error:
code: BTF-0405
service: plugin
category: deterministic
message: Caller lacks permission for this resource
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
InitiationNotFound:
description: >-
Indicates that the initiation was not found or belongs to a different
organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
initiationNotFound:
summary: Invalid initiation ID
value:
error:
code: BTF-0201
service: plugin
category: deterministic
message: Initiation not found or belongs to different organization
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
AlreadyProcessed:
description: >-
Indicates that this initiation has already been processed into a
transfer.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
alreadyProcessed:
summary: Initiation used
value:
error:
code: BTF-0203
service: plugin
category: deterministic
message: This initiation has already been processed
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
fields:
transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d
InitiationExpired:
description: >-
Indicates that the initiation has expired after 24 hours. A new
initiation must be created.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
expired:
summary: Initiation too old
value:
error:
code: BTF-0202
service: plugin
category: deterministic
message: Initiation expired after 24 hours. Create a new initiation.
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
fields:
expiresAt: '2026-01-31T15:30:00-03:00'
SigningPayloadInvalid:
description: >-
Indicates that the signing payload could not be prepared due to a domain
or payload constraint violation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
payloadFieldInvalid:
summary: Required payload field missing
value:
error:
code: BTF-0003
service: plugin
category: deterministic
message: STR0008 payload is missing a required field
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
unsupportedType:
summary: Unsupported transfer type
value:
error:
code: BTF-0004
service: plugin
category: deterministic
message: Signing prepare only supports TED_OUT initiations
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
RateLimitExceeded:
description: >-
Indicates that the rate limit has been exceeded. Retry after the number
of seconds specified in the Retry-After header.
headers:
Retry-After:
description: Seconds until rate limit resets
schema:
type: integer
example: 60
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
rateLimitExceeded:
summary: Too many requests
value:
error:
code: BTF-0429
service: plugin
category: rate_limit
message: >-
Too many requests. Retry after the interval indicated by the
`Retry-After` header.
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
description: >
Rate-limit responses use the dedicated `BTF-0429` code with the
`rate_limit` category. Clients should back off using the HTTP
status `429` and the `Retry-After` header.
InternalServerError:
description: Indicates that an unexpected internal error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internalError:
summary: Internal error
value:
error:
code: BTF-9000
service: plugin
category: plugin
message: Unexpected error while processing the request
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
BadGateway:
description: >-
Indicates that JD SPB rejected the request at the authentication or
configuration layer (signing certificate, credentials, or
configuration). The raw JD vendor code (AAC*, AAE*) passes through
verbatim on the `code` field.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
jdAuthRejected:
summary: JD SPB auth rejection
value:
error:
code: AAC90
service: jd_spb
category: deterministic
message: JD SPB rejected the signing certificate or credentials
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
ServiceUnavailable:
description: >-
Indicates that an external service (CRM, JD SPB, Midaz, or Fees) is
temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
crmUnavailable:
summary: CRM service down
value:
error:
code: BTF-0502
service: crm
category: transient
message: >-
Unable to validate account. The CRM service is temporarily
unavailable. Try again later.
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
jdUnavailable:
summary: JD SPB unavailable
value:
error:
code: TRANSPORT
service: jd_spb
category: transient
message: >-
Unable to submit transfer. The JD SPB service is temporarily
unavailable. Try again later.
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
midazUnavailable:
summary: Midaz ledger unavailable
value:
error:
code: BTF-2000
service: midaz
category: transient
message: >-
Unable to process transfer. The Midaz ledger service is
temporarily unavailable. Try again later.
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
feeServiceUnavailable:
summary: Fee service unavailable (fail-closed mode)
value:
error:
code: BTF-3000
service: fees
category: transient
message: >-
Unable to calculate fee. The fee service is temporarily
unavailable. Try again later.
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
dlqInspectorUnavailable:
summary: DLQ inspector not configured
value:
error:
code: BTF-9005
service: plugin
category: deterministic
message: DLQ inspector is not configured
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Bearer token authentication. The tenantId is derived from the bearer
token or authenticated request context and is not supplied through
X-Organization-Id.
````