> ## 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 /pt/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, and queries; bill payments (bankslip, utilities, and DARF) 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 as an RFC 9457 problem document on application/problem+json. Branch on the code member. A license refusal carries an LCS code, listed in the License Manager error list. title: Payments — via BTG API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. 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, and retrieving 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 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: >- Midaz organization the account and the ledger entry live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. in: header name: X-Organization-Id schema: description: >- Midaz organization the account and the ledger entry live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. type: string - description: >- Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012. in: header name: Idempotency-Key required: true schema: description: >- Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) 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. The payment provider acknowledged the DARF payment: it is in status CREATED and carries the provider's `providerId`. Its outcome arrives later; follow it with GET /v1/payments/{id}. A request under an `Idempotency-Key` that already names a DARF payment the provider acknowledged is answered 201 too, with that payment as it stands, in whatever status it has reached. Compare the 202, where the outcome at the provider is not known. '202': content: application/json: schema: $ref: '#/components/schemas/InitiateDARFPaymentResponse' description: >- Accepted. The DARF payment was created, its funds are reserved, and the instruction was sent to the payment provider, but its outcome is NOT known: the provider did not answer in time, failed on its side, dropped the connection or answered in a way that could not be read, or this service could not record the provider's acknowledgement. The payment is in status UNCONFIRMED and carries no `providerId`. ⚠️ Do NOT send it again under a new `Idempotency-Key`: the provider may have it, and a second request can pay the tax twice. Its funds stay reserved until the payment provider's outcome arrives. Read its current state with GET /v1/payments/{id}. A resend under the SAME `Idempotency-Key` is safe: for up to 48 hours it answers this same 202, even after the payment has resolved, so read the payment by id for its current status. A request under a key that already names a DARF payment still UNCONFIRMED is answered 202 too. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Bad Request. Branch on `code`. PBP-0001 means the request is malformed: the body is missing, is not JSON, fails schema validation, contains a member this operation does not accept, has a date or amount that cannot be parsed, or has markup in a text field. Each unexpected member is named in errors[] by its `location`; `personType`, `taxId` and `name` are not accepted. PBP-0200 means a DARF rule was not met: `type` other than S or N, an amount out of range or with more than two decimal places, or `treasuryRevenueCode` or `history` longer than allowed. PBP-0025 means the `X-Organization-Id` header is missing or is not a canonical UUID. PBP-0026 means the `ledgerId` member is missing, blank or not a canonical UUID. PBP-0012 means the `Idempotency-Key` header is missing or is not a UUID. PBP-0204 means the account named in `midazAccountId` has no registered owner, so the taxpayer of the DARF cannot be established. The taxpayer is always taken from the account's registration, so no request field resolves this: register the account's owner, or use an account that has one, and send the request again. In every case no payment was created and nothing was sent to the payment provider. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect. '413': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Request Entity Too Large '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Unprocessable Entity. The request was valid but could not be carried out; branch on `code`. PBP-0300 means the funding account does not have enough available balance, and PBP-0302 means the funds reservation would take the funding account past its overdraft limit. Both are answered BEFORE the payment provider is instructed: the payment is recorded as failed, and nothing was sent to the payment provider or paid. The Idempotency-Key is released, so the request can be sent again, under the same or a new key, once the balance allows. A refusal for the ledger's accounting configuration is not answered with this status: it is PBP-0301 on the 503. PBP-0014 means the payment provider refused the DARF instruction on the only attempt made. Nothing was paid: the payment is recorded as failed and its funds reservation is cancelled. The Idempotency-Key is consumed: a resend under the same key answers this same 422 again and runs nothing. Correct the cause and send the request under a new Idempotency-Key. PBP-0013 means this Idempotency-Key was already used for a different request: another body, or a DARF with another revenue code, reference date, type or amounts, funding account, `X-Organization-Id` or `ledgerId`. Nothing was done. Send this payment under a key of its own. PBP-0202 means account validation is not available on this deployment; no payment was created. Contact support. PBP-0017 means the payment provider account this payment would be paid from could not be established. No payment was created and nothing was sent to the payment provider. Sending the request again does not resolve it. Contact support. PBP-0205 means the registration of the funding account's owner is inconsistent — a tax id that is not a valid CPF or CNPJ, one that contradicts the registered person type, or more than one registered owner — so the taxpayer of the DARF cannot be established. No payment was created. The taxpayer is always taken from the account's registration, not from the request, so correct the owner's registration before sending the request again. PBP-0207 means the registered owner's name is longer than the 80 bytes a DARF accepts (accented characters use more than one byte). The name is never shortened. No payment was created; shorten the registered owner's name, or use a funding account whose owner's name fits, and send the request again. This limit applies only to DARF payments. PBP-0208 means the tax document of the funding account's registered owner is not numeric, for example an alphanumeric CNPJ. The registration is valid, but the payment provider accepts only a numeric CPF or CNPJ. No payment was created; use a funding account whose registered owner has a numeric document. POST /v1/payments answers the same code for the same account. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Internal Server Error. PBP-0002 is an unexpected failure with no classified answer, and it answers at two moments. BEFORE CREATION, a failure this service could not classify before it recorded the payment (for example while it checked whether the request already created a payment, prepared the call to the payment provider or built the payment) leaves nothing behind: the Idempotency-Key is released, and the SAME request under the SAME key runs again. AFTER CREATION, every failure to record the payment before the payment provider is instructed is answered 503 PBP-0301, and every outcome after the instruction is 201, 202, 422 or 503 PBP-0211, so a 500 there is a defect, not a branch to code against: the payment may or may not exist, and in the rare case the failure followed the instruction it may have been sent. The response does not say which moment it was. Before sending the request under a NEW Idempotency-Key, look for it: GET /v1/payments with `idempotencyKey` set to the key this request was sent under. A resend under the SAME key answers 409 PBP-0007 while the first request still holds the key; after that it either replays this 500, with a message that the original may have taken effect, or, when nothing was stored, runs the request again and answers from the payment it recorded, if any. Once the request has been sent under a new Idempotency-Key, never resend it under the old one: if this service could not store this answer, the old key runs the request again after five minutes, and could pay alongside the new one. '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Service Unavailable. Branch on `code`: the `detail` of a 5xx response is a fixed generic text. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed and no payment was created; wait and send the same request again with the same Idempotency-Key. PBP-0211 means the payment provider did not receive the payment instruction: it was closed for the day (outside the hours it accepts), unreachable on every attempt, or calls to it were suspended after repeated failures; it refused the call itself on the only attempt made — not authorized, forbidden, or not received in full in time; or this API could not authenticate with the provider or set up the call to it at all. Nothing was paid. The payment was created, is recorded as failed, and its funds reservation is cancelled shortly after this answer. The Idempotency-Key is consumed: a resend under the same key answers this same 503 again and runs nothing. To try again, send the request under a new Idempotency-Key, which is safe because nothing was paid; until the first reservation is released it may be answered PBP-0300. While the provider is closed, every attempt answers this code until it reopens, and while it refuses these calls, or they cannot be authenticated, every attempt answers it until an operator restores access. PBP-0015 means calls to the payment provider were suspended after repeated failures while the DARF was being prepared, before any payment is created: nothing was created or sent, the Idempotency-Key is released, and the same request can be sent again under the same key once the provider recovers. PBP-0015 is never answered after the payment instruction is sent: an instruction whose outcome is not known is answered 202 with the payment in status UNCONFIRMED, and one the payment provider did not receive is answered PBP-0211. PBP-0206 means the registered owner of the funding account, who is the taxpayer of the DARF, could not be established because the records that identify it could not be reached or are not available on this deployment. No payment was created and the payment provider was not called. Wait and send the request again; if a resend under the same Idempotency-Key is answered 500 PBP-0002, send it under a new key. If the request under a new key answers this code again, contact support. PBP-0301 means the funds could not be reserved in the ledger, or the payment could not be recorded before the payment provider was instructed. On this operation it is always answered BEFORE the payment provider is instructed: nothing was sent to the payment provider and nothing was paid. It is answered at two moments. Before the payment is created, nothing exists: where accounting routes are enabled, the tenant's accounting routes could not be read or are incomplete or inconsistent; and on an instance that resolves a credential per tenant, that credential could not be resolved, or was rejected, while the funding account was being checked. The Idempotency-Key was released, so the same request under the same key runs again, and succeeds once the cause is repaired. After the payment is created, it may exist in status UNCONFIRMED and was not sent. That payment is never sent to the payment provider: the reconciliation marks it FAILED and releases any funds reserved for it. Rarely, that needs an operator; contact support in those cases. This answer is stored, so a resend under the same key answers this same 503 again and runs nothing. The response does not say which of the two moments it was: both carry the same code and status, and no payment id. The remedy is the same: once the cause is repaired, send the request under a NEW Idempotency-Key, which cannot pay twice because a payment answered with this code is never instructed. Once the request has been sent under a new Idempotency-Key, never resend it under the old one: if this service could not store this answer, the old key runs the request again after five minutes, and could pay alongside the new one. Until the first payment's reservation is released, the new request may be answered PBP-0300. To account for a payment the first request may have created, call GET /v1/payments with `idempotencyKey` set to the Idempotency-Key the request was sent under. A payment found there reads UNCONFIRMED until it ends FAILED (follow it with GET /v1/payments/{id}), and it is never paid. 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. examples: - '2026-05-10' format: date 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 ledgerId: description: >- Midaz ledger the account lives in and the entry is posted to. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026. 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. The TAXPAYER of the DARF is the registered owner of this account, read from the Midaz CRM — the request does not state one. A holder whose registered name exceeds 80 bytes cannot be paid on this rail: the name is never shortened to fit, and the refusal is 422 PBP-0207. 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 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 revenue code (código da receita) of the DARF: the four digits of the code, zero-padded, for example 0086. A value in the provider's prefixed form, such as TRC_0086, is also accepted. At most 20 characters. The code is not checked against the revenue code catalogue by this API; the payment provider refuses an unknown code. examples: - '0086' type: string type: description: 'DARF type: S for Simples, N for Normal.' examples: - S type: string required: - referenceDate - treasuryRevenueCode - type - mainAmount - interestAmount - fineAmount - midazAccountId type: object InitiateDARFPaymentResponse: additionalProperties: false properties: createdAt: type: string id: type: string ledgerId: description: Midaz ledger the payment was written with. Always present. type: string organizationId: description: Midaz organization the payment was written with. Always present. type: string providerId: description: >- Identifier the payment provider assigned to this payment. Quote it, together with providerRequestId, when you contact the provider about this payment. Absent while the payment is UNCONFIRMED (the 202 answer): the provider has acknowledged nothing yet. Read the payment by id later to obtain it. type: string providerRequestId: description: >- Reference this API sent to the payment provider when it instructed the payment, exactly as sent. Which of providerId and providerRequestId the provider accepts for a lookup depends on the provider and on the payment type, so quote both when you contact the provider. Absent when the payment carries no such reference. type: string status: description: >- The payment's status when this answer was produced. CREATED on a 201 for a new payment; UNCONFIRMED on a 202, while the outcome at the payment provider is unknown. A request already on record is answered with the payment's status at that moment, which may be any status a payment takes. A replay of the same Idempotency-Key serves the stored answer, whose status may since have changed: read the payment by id for its current state. type: string totalAmount: type: string type: type: string required: - id - type - status - totalAmount - createdAt - organizationId - ledgerId type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). 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 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.