> ## 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. # Initiate a DARF payment > Initiates a DARF (federal tax) payment with specific tax fields. ## OpenAPI ````yaml /en/openapi/v3-current/payments.yaml post /v1/payments/darf openapi: 3.1.0 info: description: >- API for the Lerian Payments interface via BTG. It covers boleto issuance, cancellation, installments, and queries; bill payments (bankslip, utilities, and DARF), cancellation, and queries; aggregated boleto and payment dashboards; provider connection and outbound webhook configuration; and the provider webhook receiver for settlement events. ERROR BODIES. A failed request arrives in one of three shapes, and which one you get depends on where the service catches the failure, not on which endpoint you called. The authentication and authorization layer runs ahead of everything else and answers plain text with a bare reason and no error code. A failure that the request pipeline catches next, before the API layer sees it, answers a flat JSON body on application/json; the idempotency check is the pipeline rule you meet most often. Everything the API layer catches answers an RFC 9457 problem document on application/problem+json. Read the media type to tell the two JSON bodies apart. The code member holds the same PBP-NNNN value in both, so branch on it, and handle 401 and 403 by status because a refusal from the authentication layer carries no code. One pipeline refusal is not listed on the operations below: while a first request under the same idempotency key is still in flight, a retry is answered 409 with code PBP-0007 and the flat body. title: Payments — via BTG API version: 1.0.0 servers: - url: https://payments.sandbox.lerian.net security: [] tags: - description: >- Tenant-level setup: connecting the banking provider and configuring where status notifications are delivered. name: Admin - description: >- Issuing, querying and cancelling boletos, including installment series and the rendered PDF. name: Boletos - description: >- Aggregated counts, amounts and breakdowns over a period, for boletos and for payments. name: Dashboards - description: >- Paying bankslips, utility bills and DARF tax slips, and querying or cancelling those payments. name: Payments - description: >- The webhook the payment provider posts settlement events to. Authenticated with a credential agreed with the provider, not with the platform identity used by the rest of this API. name: Settlement paths: /v1/payments/darf: post: tags: - Payments summary: Initiate a DARF payment description: Initiates a DARF (federal tax) payment with specific tax fields. operationId: initiateDARFPayment parameters: - description: >- Tenant organization ID. Accepted but ignored: the tenant is determined by the credentials you authenticate with, so sending this header, or sending a different value in it, changes nothing. in: header name: X-Organization-Id schema: description: >- Tenant organization ID. Accepted but ignored: the tenant is determined by the credentials you authenticate with, so sending this header, or sending a different value in it, changes nothing. type: string - description: >- Client-supplied idempotency key. Required in practice even though the schema marks it optional: a request that omits this header is refused with 400 PBP-0012. in: header name: Idempotency-Key schema: description: >- Client-supplied idempotency key. Required in practice even though the schema marks it optional: a request that omits this header is refused with 400 PBP-0012. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/InitiateDARFPaymentRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/InitiateDARFPaymentResponse' description: Created '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' application/json: schema: $ref: '#/components/schemas/PipelineError' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' text/plain: schema: type: string application/json: schema: $ref: '#/components/schemas/PipelineError' description: >- Authentication failed. Two shapes are possible and a client must accept both: the authentication middleware answers `text/plain` with a bare reason (for example `Missing Token`) and carries no error code, while a refusal raised inside the service answers `application/problem+json` with code `PBP-0003`. '403': content: text/plain: schema: type: string description: >- The authenticated principal is not permitted to perform this action. Answered as `text/plain` by the authorization middleware, with no error code. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' application/json: schema: $ref: '#/components/schemas/PipelineError' description: >- Unprocessable Entity. The request was well-formed but could not be carried out, and the branches are told apart by `code`. PBP-0300 means the ledger refused the reservation because the funding account does not have enough available balance. PBP-0302 means the ledger refused the reservation under another of its own rules; the reason is recorded on the payment rather than published here. Both are TERMINAL: the payment is recorded as failed and nothing will complete it. ⚠️ Do NOT resend with the same `Idempotency-Key` expecting to read this answer again. A 4xx RELEASES the key, so the resend re-runs the whole operation and instructs the provider a SECOND time. Resolve the cause and submit a NEW request under a NEW key. PBP-0014 means the payment provider rejected the instruction. PBP-0202 means account validation is not configured on this instance, which needs an operator rather than a retry. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' application/json: schema: $ref: '#/components/schemas/PipelineError' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' application/json: schema: $ref: '#/components/schemas/PipelineError' description: >- Service Unavailable. FIVE branches answer with this status, told apart by `code` and never by `detail` — except for the last two, which share one code; see the warning at the end. PBP-0008 means this instance could not resolve the tenant database; the request was NOT accepted and is safe to retry with the same Idempotency-Key. PBP-0015 covers TWO branches with DIFFERENT remedies: the payment provider did not carry out the write — it is temporarily unreachable (open circuit or exhausted retries), or it refused the write for arriving outside the hours it accepts, a cut-off window this contract does not publish — which is safe to retry with the same Idempotency-Key, a cut-off only once the window reopens; or DARF payments are not configured on this instance, which no amount of retrying resolves and which needs an operator. PBP-0301 is different in kind from all of the above: the payment WAS created and carries an id, but the ledger did not answer the funds reservation, so its outcome is unknown. A background reconciliation completes the reservation on its own. Read the payment by its id to observe the outcome — do NOT submit the request again. A new Idempotency-Key creates a SECOND payment; the same key is held but its stored response is discarded on a 5xx, so a resend is answered PBP-0002 rather than with a replay. Neither route gives you this payment's outcome — reading it by id does. ⚠️ PBP-0301 also answers a second, PERMANENT condition: an instance running with no ledger configured, where the reservation step has nothing to call and NO payment is created at all. The two are not distinguishable on the wire, only by incidence — if EVERY request to this operation answers this code, it is the instance fault and it needs an operator. ⚠️ The `detail` member of the response body is the static "internal error": the shared RFC 9457 model scrubs it for every status >= 500 so that no server-side cause reaches a client. Branch on `code`, and treat a persistent PBP-0015 as a configuration problem rather than an outage. security: - BearerAuth: [] components: schemas: InitiateDARFPaymentRequest: additionalProperties: false properties: description: description: Optional free-text description carried on the payment. type: string dueDate: description: Optional due date, YYYY-MM-DD. type: string fineAmount: description: >- Fine amount as a decimal string, up to two decimal places. Must be non-negative. examples: - '5.00' maxLength: 32 type: string history: description: Optional free-text history carried on the payment. type: string interestAmount: description: >- Interest amount as a decimal string, up to two decimal places. Must be non-negative. examples: - '10.00' maxLength: 32 type: string mainAmount: description: >- Principal amount as a decimal string, up to two decimal places. Must be positive. examples: - '100.00' maxLength: 32 type: string midazAccountId: description: Midaz account the payment settles from. type: string name: description: >- Taxpayer name, up to 80 bytes (UTF-8; accented characters count as more than one byte). examples: - Fulano de Tal type: string personType: description: >- Taxpayer person type: F for an individual (CPF, 11 digits) or J for a legal entity (CNPJ, 14 digits). It must agree with taxId: a length that does not match the person type, or a failing check digit, is refused with 400 PBP-0200. examples: - F type: string referenceDate: description: Tax period reference date, YYYY-MM-DD. examples: - '2026-04-01' format: date type: string referenceNumber: description: Optional reference number carried to the tax authority. format: int64 type: integer taxId: description: >- Taxpayer CPF or CNPJ, digits only. Its length and check digits are validated against personType. examples: - '12345678909' type: string totalIncomeAmount: description: Optional total income amount as a decimal string. maxLength: 32 type: string totalIncomePercent: description: Optional total income percentage as a decimal string. maxLength: 32 type: string treasuryRevenueCode: description: >- Federal treasury revenue code (codigo da receita): the four zero-padded digits listed in the tax code catalogue the provider publishes as TaxMessageCodes.pdf. Send the four digits alone — the service prefixes them with TRC_ on the way to the provider, and a value that already carries that prefix is forwarded unchanged. The code is not checked against the catalogue here; an unknown code is refused by the provider. examples: - '0086' type: string type: description: 'DARF type: S for Simples, N for Normal.' examples: - S type: string required: - personType - taxId - name - referenceDate - treasuryRevenueCode - type - mainAmount - interestAmount - fineAmount - midazAccountId type: object InitiateDARFPaymentResponse: additionalProperties: false properties: createdAt: type: string id: type: string providerId: type: string status: type: string totalAmount: type: string type: type: string required: - id - providerId - type - status - totalAmount - createdAt type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object PipelineError: additionalProperties: false description: >- The flat error body. A failure caught before the API layer sees the request answers this shape on the application/json media type, instead of the RFC 9457 problem document. Read the media type to tell the two apart. The idempotency check is the rule that answers this way most often. properties: code: description: >- Stable, machine-readable error code, in the form PBP-NNNN. Branch on this value. It carries the same meaning as the code member of the problem document. examples: - PBP-0013 type: string details: additionalProperties: true description: Optional object carrying further facts about this occurrence. type: - object - 'null' message: description: A human-readable explanation specific to this occurrence. examples: - >- The request body does not match the original request for this idempotency key. type: string title: description: Short label for the condition. examples: - Idempotency Key Conflict type: string required: - code - title - message type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````