> ## 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 /pt/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,
cancellation, and returns.
version: 3.4.0
servers:
- url: https://api.example.com
description: >-
Replace the example host with the URL provided during environment
onboarding.
security:
- BearerAuth: []
- OAuth2ClientCredentials:
- api
- OAuth2Password:
- api
tags:
- name: Transfers API
description: >-
Endpoints for initiating, processing, tracking, cancelling, and returning
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.
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':
description: >-
BTF-0201: the initiation was not found or belongs to a different
organization.
BTF-1092: the signing artifact was not found.
BTF-0404: `X-Organization-Id` names an organization that this tenant
does not operate.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
examples:
initiationNotFound:
summary: Invalid initiation ID
value:
type: https://errors.lerian.studio/v1/BTF-0201
title: Not Found
status: 404
detail: payment initiation not found
code: BTF-0201
category: deterministic
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
'409':
description: >-
BTF-0203: this initiation has already been processed into a
transfer.
BTF-0112: the initiation was created before ledger-scoped routing
and cannot be processed. No signing artifact was written. Initiate
the transfer again.
BTF-0016: a request under this `X-Idempotency` key still holds the
in-flight lease, because it is still running or because it already
ended 5xx and recorded no outcome. `Retry-After` carries a poll
interval, not the lease. While the first request is still running,
resend the identical request after that interval; the answer replays
from the first request as soon as it finishes. If an earlier request
under this key answered 5xx without `X-Idempotency-Fenced: true`, no
answer will ever be served from it: stop resending, read the
resource this route acts on, and send the work under a new
`X-Idempotency` key only if it did not land. The detail also names
the 15-minute bound after which the lease lapses and a resend runs
the work a second time; a poll still unanswered by then ends the
same way.
BTF-0018: the request under this `X-Idempotency` key already
completed, and its response was too large to store for replay. Read
the resource. Do not resend under a new key, because that runs the
work a second time. This answer carries no `Retry-After`, because no
wait produces the missing receipt.
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'410':
$ref: '#/components/responses/InitiationExpired'
'422':
description: >-
BTF-0002: the request failed domain validation.
BTF-0003: the STR0008 payload is missing a required field. BTF-0004:
signing prepare supports only TED OUT transfers.
BTF-0013: a database constraint refused the write.
BTF-0014: an earlier request under this `X-Idempotency` key answered
5xx, so the key is fenced for the retention window. Read the
resource and, only if the work did not land, send the identical
request under a new key.
BTF-0015: this service cannot read the idempotency record under this
key. The remedy is the same.
BTF-0017: this `X-Idempotency` key was already used for a different
request. A repeat must be byte-identical, and a new request needs
its own new key. BTF-0017 is decided before BTF-0014, so a fenced
key resent with a changed body gets BTF-0017.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
examples:
payloadFieldInvalid:
summary: Required payload field missing
value:
type: https://errors.lerian.studio/v1/BTF-0003
title: Unprocessable Entity
status: 422
detail: >-
str0008: transfer purpose is missing — provide a valid
transfer purpose code in the transfer request
code: BTF-0003
category: deterministic
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
unsupportedType:
summary: Unsupported transfer type
value:
type: https://errors.lerian.studio/v1/BTF-0004
title: Unprocessable Entity
status: 422
detail: signing prepare is supported only for ted out transfers
code: BTF-0004
category: deterministic
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/IdempotentInternalServerError'
'502':
description: >-
BTF-0501: the CRM returned a response that this service could not
read.
headers:
X-Idempotency-Fenced:
$ref: '#/components/headers/XIdempotencyFenced'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'503':
description: >-
BTF-9005, BTF-9007, BTF-9008: a dependency or the repository is
unavailable.
BTF-9016: this tenant's database cannot record the signing artifact.
Nothing was written and nothing was sent. Apply the pending
migrations to this tenant and send the identical request again under
a new `X-Idempotency` key.
BTF-9018: this tenant binds more than one ISPB, so its
clearing-house identity cannot be decided. Nothing was written, no
hold was placed and nothing reached JD. Once the binding names
exactly one ISPB, send the identical request under a new
`X-Idempotency` key.
BTF-9000: the idempotency store was unavailable before the handler
ran, so nothing ran. Send the same request again under the same
`X-Idempotency` key.
BTF-0019: the work under this `X-Idempotency` key ran, and neither
its response nor its outcome fence could be stored, so the key
protects nothing and a resend can run the operation a second time.
Read the resource before you send anything else.
BTF-0020: the work under this `X-Idempotency` key ran and its
response could not be stored for replay, but the key is still held.
This answer is not the outcome of that work. Read the resource, and
resend under a new key only if the work did not land.
BTF-9017: the tenant organization list is absent or unreadable.
Retry with the same idempotency key once it is configured.
headers:
X-Idempotency-Fenced:
$ref: '#/components/headers/XIdempotencyFenced'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
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 a unique
business identifier, made of letters, digits, `.`, `_`, and `-`. If the
same key is sent again and the original request was already processed,
the cached response is returned.
See [Retries and idempotency](/pt/reference/retries-idempotency) for
details.
schema:
type: string
maxLength: 255
pattern: ^[a-zA-Z0-9._-]+$
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'
ProblemDocument:
type: object
description: >-
The RFC 9457 problem document that the service answers every error with,
on `application/problem+json`. Route-specific members (for example
`refusalCode`, `transactionId`, `ledgerStatus`, `systemplaneKey`) appear
flat at the top level beside these.
additionalProperties: true
required:
- type
- title
- status
- detail
- code
- requestId
- service
- category
properties:
type:
type: string
description: >-
A URI that names the error code:
`https://errors.lerian.studio/v1/`.
example: https://errors.lerian.studio/v1/BTF-0200
title:
type: string
description: The HTTP status text.
example: Not Found
status:
type: integer
description: The HTTP status code.
example: 404
detail:
type: string
description: A human-readable explanation of this occurrence.
example: transfer not found
instance:
type: string
description: The trace ID of this request, when one was recorded.
example: 4bf92f3577b34da6a3ce929d0e0e4736
errors:
type: array
description: Each rejected field. Present on field validation errors only.
items:
type: object
properties:
message:
type: string
description: Why the value was rejected.
example: transferId must be a valid UUID
location:
type: string
description: 'Where the value sits: `body.` or `query.`.'
example: body.senderAccountId
code:
type: string
description: The stable BTF error code.
example: BTF-0200
upstream:
type: object
description: >-
The error that an upstream provider (JD SPB, Midaz) reported. Absent
unless surfaced.
properties:
code:
type: string
description: The provider's own error code, verbatim.
example: AAC90
message:
type: string
description: The provider's own error message, bounded.
example: Assinatura invalida
requestId:
type: string
description: The request correlation ID. Present even when empty.
example: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service:
type: string
description: The system that produced the error.
example: plugin
category:
type: string
description: The machine-readable error category.
example: deterministic
responses:
BadRequest:
description: Indicates that the request contains invalid input.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
examples:
invalidInput:
summary: Validation error
value:
type: https://errors.lerian.studio/v1/BTF-0001
title: Bad Request
status: 400
detail: invalid request body
code: BTF-0001
category: deterministic
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
Unauthorized:
description: Indicates that the request is missing a valid authentication token.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
examples:
unauthorized:
summary: Missing authorization
value:
type: https://errors.lerian.studio/v1/BTF-0401
title: Unauthorized
status: 401
detail: Missing Token
code: BTF-0401
category: plugin
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
Forbidden:
description: >-
Indicates that the caller is authenticated but lacks permission for this
operation.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
examples:
permissionDenied:
summary: Caller lacks permission
value:
type: https://errors.lerian.studio/v1/BTF-0405
title: Forbidden
status: 403
detail: >-
the credential is not allowed to perform transfers:create on
this request
code: BTF-0405
category: plugin
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
InitiationExpired:
description: >-
Indicates that the initiation has expired after 24 hours. A new
initiation must be created.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
examples:
expired:
summary: Initiation too old
value:
type: https://errors.lerian.studio/v1/BTF-0202
title: Gone
status: 410
detail: >-
initiation expired after 24 hours. please create a new
initiation.
code: BTF-0202
category: deterministic
expiresAt: '2026-01-31T15:30:00-03:00'
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
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/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
examples:
rateLimitExceeded:
summary: Too many requests
value:
type: https://errors.lerian.studio/v1/BTF-0429
title: Too Many Requests
status: 429
detail: Rate limit exceeded
code: BTF-0429
category: rate_limit
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
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.
IdempotentInternalServerError:
description: Indicates that an unexpected internal error occurred.
headers:
X-Idempotency-Fenced:
$ref: '#/components/headers/XIdempotencyFenced'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
examples:
internalError:
summary: Internal error
value:
type: https://errors.lerian.studio/v1/BTF-9000
title: Internal Server Error
status: 500
detail: Internal server error
code: BTF-9000
category: plugin
requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f
service: plugin
headers:
RetryAfter:
description: The number of seconds to wait before you send the request again.
schema:
type: integer
XIdempotencyFenced:
description: >-
`true` when this 5xx fenced the `X-Idempotency` key, so a resend is
refused with 422 BTF-0014. `false` when the fence write itself failed
and only the in-flight lease holds the key, so a resend is refused with
409 BTF-0016 until that lease lapses. On a 503 BTF-0019, `false` means
the handler succeeded and both its receipt and its fence were lost.
The header is absent when nothing fenced the key. On a 500 raised by a
panic, the protection of the key is unknown: read the resource and
reconcile before you resend. On a 503 BTF-9000 answered while the
idempotency store was down before the handler, nothing ran: send the
same request again under the same key.
schema:
type: string
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.
OAuth2ClientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: /v1/login/oauth/access_token
scopes:
api: TED transfer API access
OAuth2Password:
type: oauth2
flows:
password:
tokenUrl: /v1/login/oauth/access_token
scopes:
api: TED transfer API access
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.