> ## 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 payment > Initiates a bankslip or utilities bill payment. The type is classified automatically from the digitable line. The payment is executed immediately; this operation does not accept a scheduling date. A request that sends scheduledDate is refused with 400 PBP-0001, naming body.scheduledDate as an unexpected property. ## OpenAPI ````yaml /pt/openapi/v3-current/payments.yaml post /v1/payments 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 in one of two shapes, and which one you get depends on where the service catches the failure. A failure that the request pipeline catches 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. Authentication and authorization refusals follow the response contract documented by the operation. Everything the API layer catches answers an RFC 9457 problem document on application/problem+json. Read the media type to tell the two apart. 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: post: tags: - Payments summary: Initiate a payment description: >- Initiates a bankslip or utilities bill payment. The type is classified automatically from the digitable line. The payment is executed immediately; this operation does not accept a scheduling date. A request that sends scheduledDate is refused with 400 PBP-0001, naming body.scheduledDate as an unexpected property. operationId: initiatePayment 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, or with a value that is not a UUID, 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, or with a value that is not a UUID, is refused with 400 PBP-0012. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/InitiatePaymentRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/InitiatePaymentResponse' description: >- Created. The payment provider acknowledged the 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 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/InitiatePaymentResponse' description: >- Accepted. The 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 slip twice. It resolves without you: the reconciliation reads it from the provider and moves it to the status the provider reports, or to FAILED, with its funds released, when the provider still has no record of it. 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 payment still UNCONFIRMED is answered 202 too. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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, or contains a member this operation does not accept. Each unexpected member is named in errors[] by its `location`; `payer`, `payeeName`, `payeeTaxId` and `scheduledDate` are not accepted. 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 payer cannot be established. The payer 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/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' text/plain: schema: type: string description: >- Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is either `application/json` with error code `PBP-0003` or `application/problem+json` (RFC 9457); read the `Content-Type` to parse it. The `text/plain` media type listed for this status is not returned. Obtain a valid bearer token and send the request again. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' text/plain: schema: type: string description: >- The authenticated principal is not allowed to perform this request. The error body is `application/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. The `text/plain` media type listed for this status is not returned. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Not Found. Two branches, told apart by `code`. PBP-0005 means the funding account named in the request was not found or is not accessible to the caller. PBP-0110 means the source of the payment slip has no bill under this digitable line: the provider's pre-payment consult answered that it does not exist. Check the line. For both, nothing was created and the payment provider was not instructed, so the `Idempotency-Key` is released and a resend is the first instruction. '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 payment 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 payment with another digitable line, funding account, `X-Organization-Id` or `ledgerId`. Nothing was done. Send this payment under a key of its own. PBP-0210 means the payment provider's pre-payment check found that this slip cannot be paid: it is not valid for payment (already paid, cancelled or expired; the provider does not say which), or its amount is zero or less. No payment was created and the payment provider was not instructed, so the request can be sent again under the same or a new Idempotency-Key, but it keeps answering this code until the slip's state changes. 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 payer cannot be established. No payment was created. The payer is always taken from the account's registration, not from the request, so correct the owner's registration before sending the request again. 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. PBP-0111 means the source of the payment slip refused it in the payment provider's pre-payment check, for the reason whose provider code the `detail` names — for example an amount that differs from the registered one. No payment was created and the payment provider was not instructed, so the request can be sent again under the same or a new Idempotency-Key; it only succeeds once the cause the code names is resolved. '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Bad Gateway. Branch on `code`: the `detail` of a 5xx response is a fixed generic text. PBP-0113 means the payment provider's pre-payment check for this slip returned an answer that cannot be used: no amount, an amount outside the minimum and maximum the same answer declares, the provider's internal error (PIE002) reported inside the `errors[]` of an answer, a refusal reason this API does not recognize, or a body that cannot be read. A provider that fails without answering, PIE002 included, is 503 PBP-0015, not this. No payment was created and the payment provider was not instructed. The Idempotency-Key is released, so the same request can be sent again under the same key; a later check may return a usable answer. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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-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 the payment provider's pre-payment consult of the slip, which runs before any payment is created, gave no usable answer: it could not be reached, did not answer in time, refused the call, failed on its side, or calls to it were suspended after repeated failures. No payment was created and the payment provider was not instructed. The Idempotency-Key is released, so send the same request again under the same key. 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-0008 means the tenant's storage could not be resolved. The request was not processed and no payment was created; wait and send the same request again with the same Idempotency-Key. PBP-0206 means the registered owner of the funding account, who is the payer, 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: InitiatePaymentRequest: additionalProperties: false properties: description: description: Free-text description carried on the payment. type: string digitableLine: description: Bankslip or utilities digitable line, digits only. examples: - '00190500954014481606906809350314337370000000100' 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 midazAccountId: description: >- Midaz account the payment settles from. Who PAYS is the registered owner of this account, read from the Midaz CRM — the request does not state a payer. type: string required: - digitableLine - midazAccountId type: object InitiatePaymentResponse: additionalProperties: false properties: amount: type: string createdAt: type: string digitableLine: type: string dueDate: 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 type: type: string required: - id - type - status - digitableLine - amount - createdAt - organizationId - ledgerId type: object ErrorResponse: additionalProperties: false properties: code: type: string details: additionalProperties: {} type: object message: type: string title: type: string required: - code - title - message 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.