> ## 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. # Create a due-date Pix collection (cobv) > Registers a dynamic due-date Pix collection using the due-date calendar defined by the BCB and optional value modifiers (fine, interest, abatement, and discount). The Pix key is validated before creation. The collection includes its EMV payload, location URL, and expiration time. **Replay:** retrying the same request with the same `txId` within the same organization, account, and merchant-document scope returns the original `201` response unchanged and does not create another collection. Using an existing `txId` with a different request body returns `PIX-0012` with status `409`. ## OpenAPI ````yaml /es/openapi/v3-current/pix-lerian-cob.yaml post /collections/duedate openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- Public API for Pix BR Codes and immediate and due-date collections. This release provides a mock-provider integration for testing; live BACEN connectivity is not included. license: name: Lerian Studio General License title: Pix Lerian — Collections version: 1.0.0 servers: - url: https://api.example.com/cob-hub/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, retrieve, list, and decode static Pix BR Codes. name: BR Codes - description: Create, retrieve, list, and cancel due-date Pix collections. name: Due-Date Collections - description: Create, retrieve, list, and cancel immediate Pix collections. name: Immediate Collections paths: /collections/duedate: post: tags: - Due-Date Collections summary: Create a due-date Pix collection (cobv) description: >- Registers a dynamic due-date Pix collection using the due-date calendar defined by the BCB and optional value modifiers (fine, interest, abatement, and discount). The Pix key is validated before creation. The collection includes its EMV payload, location URL, and expiration time. **Replay:** retrying the same request with the same `txId` within the same organization, account, and merchant-document scope returns the original `201` response unchanged and does not create another collection. Using an existing `txId` with a different request body returns `PIX-0012` with status `409`. operationId: createDueDateCollection parameters: - description: >- REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key returns the ORIGINAL response at 200, even when the body differs from the first request under this key -- the key alone decides replay for collection creation. To create a different collection, use a new X-Idempotency key and a new txId. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Receiver merchant account UUID (scopes DICT key validation) in: header name: X-Account-Id required: true schema: description: Receiver merchant account UUID (scopes DICT key validation) examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string requestBody: content: application/json: examples: fictitiousExample: summary: Fictitious example value: abatement: modality: PERCENTAGE value: '5.00' additionalInfo: - key: orderId value: '12345' amount: '100.50' calendar: dueDate: '2030-09-01' validityAfterDue: 30 currency: BRL debtor: document: '39053344705' name: João da Silva description: Fatura de servicos discount: modality: VALUE_PER_CALENDAR_DAY_ADVANCE value: '3.00' fine: modality: FIXED_VALUE value: '10.00' interest: modality: VALUE_CALENDAR_DAYS value: '1.50' keyType: EVP keyValue: 123e4567-e12b-12d1-a456-426655440000 merchantCity: Goiania merchantName: Loja Teste txId: TX1234567890123456789012345 schema: $ref: '#/components/schemas/CreateDueDateCollectionBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/DueDateCollectionOutput' description: >- Replay of an already-completed request under this X-Idempotency key -- the ORIGINAL response, verbatim, even when this request's body or txId differs from the first ( Never re-executes the command and never calls the provider a second time. '201': content: application/json: example: accountId: 0196a7b2-3e5f-7061-ac12-34567890abcd amount: '150.75' calendar: dueDate: '2026-09-01' validityAfterDue: 30 createdAt: '2026-08-02T10:30:00Z' currency: BRL debtor: document: '12345678909' name: Maria Souza emvPayload: >- 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Exemplo6009Sao Paulo62070503***63041D3F expiresAt: '2026-10-01T00:00:00Z' externalId: 0196a7b2-4f60-7172-bd23-4567890abcde id: 0196a7b2-1c3d-7e4f-8a90-1234567890ab isExpired: false keyType: EMAIL keyValue: loja@example.com locationUrl: https://pix.example.com/qr/v2/cobv-abc123 merchantCity: Sao Paulo merchantDocument: '39053344705' merchantName: Loja Exemplo organizationId: 0196a7b2-2d4e-7f50-9b01-234567890abc status: ACTIVE txId: TX1234567890123456789012345 type: DUE_DATE updatedAt: '2026-08-02T10:30:00Z' schema: $ref: '#/components/schemas/DueDateCollectionOutput' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The Idempotency-Key header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0200 title: Bad Request status: 400 detail: Missing or malformed required fields. code: PIX-0200 schema: $ref: '#/components/schemas/Detail' description: >- Missing or malformed headers/body fields, invalid collection input, a due-date/modifier rule failure, or provider-side request validation rejection (PIX-0001-0003, PIX-0017, PIX-0200, PIX-0224, PIX-0260-0267). X-Idempotency absent or longer than 64 bytes (PIX-0030) uses the legacy {code,title,message} envelope; other 400 errors use application/problem+json. Malformed request, a due-date/modifier validation rule failed (PIX-0001-0010, PIX-0200, PIX-0260-0267), or the provider rejected the create request (PIX-0224). '404': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0225 title: Not Found status: 404 detail: >- The requested collection resource was not found at the provider. code: PIX-0225 schema: $ref: '#/components/schemas/Detail' description: >- The provider reports that the addressed collection resource does not exist (PIX-0225). The provider reports the addressed resource as not found (PIX-0225). '409': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0012 title: Conflict status: 409 detail: >- The entity already exists or conflicts with an existing resource. code: PIX-0012 schema: $ref: '#/components/schemas/Detail' description: >- The txId is already claimed, the provider reports a conflicting state, or an earlier create operation is still in progress (PIX-0012, PIX-0226, PIX-0244). txId already claimed by a non-replayable row -- divergent content, a different account, or a different collection type (PIX-0012) -- the provider reports a conflicting state (PIX-0226), or an earlier request for this BACEN key or this X-Idempotency key is still being processed (PIX-0244). '415': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0016 title: Unsupported Media Type status: 415 detail: >- The request body must be sent with Content-Type: application/json. code: PIX-0016 schema: $ref: '#/components/schemas/Detail' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016). '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0245 title: Unprocessable Entity status: 422 detail: >- The creation for this key can no longer be completed; use a new tx_id or contact support. code: PIX-0245 schema: $ref: '#/components/schemas/Detail' description: >- The Pix key is absent or inactive, or an earlier create operation reached a terminal outcome (PIX-0201, PIX-0245). An earlier request for this BACEN key or this X-Idempotency key reached a terminal outcome that can never complete (PIX-0245). Use a new X-Idempotency key and a new txId. '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: >- The server encountered an unexpected error. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: >- Unexpected internal failure comparing, recovering, or persisting the collection (PIX-0000). Unexpected internal failure comparing a replay against the existing row, or persisting the created collection. '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0223 title: Bad Gateway status: 502 detail: Provider adapter is unreachable. code: PIX-0223 schema: $ref: '#/components/schemas/Detail' description: >- The DICT Hub or provider adapter is unreachable, or a successful provider response violates its contract (PIX-0223). The provider adapter is unreachable, or its response failed the contract check (PIX-0223). '504': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0054 title: Gateway Timeout status: 504 detail: The request timed out. Please try again later. code: PIX-0054 schema: $ref: '#/components/schemas/Detail' description: The provider timed out handling the create request (PIX-0054). default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: CreateDueDateCollectionBody: additionalProperties: false properties: abatement: $ref: '#/components/schemas/AbatementTermsRequest' description: Optional abatement (abatimento) modifier additionalInfo: description: Free-form key/value metadata (max 50 entries) items: $ref: '#/components/schemas/AdditionalInfoEntry' type: - array - 'null' amount: description: Collection amount in BRL type: string calendar: $ref: '#/components/schemas/DueDateCalendarRequest' description: Due-date expiration calendar currency: description: Currency (BRL only) examples: - BRL type: string debtor: $ref: '#/components/schemas/DebtorRequest' description: Debtor block (mandatory for due-date collections) description: description: Free-form description examples: - Fatura de servicos type: string discount: description: Optional discount (desconto) modifier oneOf: - additionalProperties: false properties: fixedDates: description: >- Date-anchored discount schedule (*_UNTIL_DATES modalities only, at most 3 entries) items: $ref: '#/components/schemas/DiscountFixedDateRequest' maxItems: 3 minItems: 1 type: array modality: description: Discount calculation modality enum: - FIXED_VALUE_UNTIL_DATES - PERCENT_UNTIL_DATES examples: - FIXED_VALUE_UNTIL_DATES type: string value: description: Discount value (per-day advance modalities only) pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$ type: string required: - modality - fixedDates type: object - additionalProperties: false properties: fixedDates: description: >- Date-anchored discount schedule (*_UNTIL_DATES modalities only, at most 3 entries) items: $ref: '#/components/schemas/DiscountFixedDateRequest' type: - array - 'null' modality: description: Discount calculation modality enum: - VALUE_PER_CALENDAR_DAY_ADVANCE - VALUE_PER_BUSINESS_DAY_ADVANCE - PERCENT_PER_CALENDAR_DAY_ADVANCE - PERCENT_PER_BUSINESS_DAY_ADVANCE examples: - VALUE_PER_CALENDAR_DAY_ADVANCE type: string value: description: Discount value (per-day advance modalities only) pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$ type: string required: - modality - value type: object fine: $ref: '#/components/schemas/FineTermsRequest' description: Optional fine (multa) modifier interest: $ref: '#/components/schemas/InterestTermsRequest' description: Optional interest (juros) modifier keyType: description: Pix key type examples: - EVP type: string keyValue: description: Pix key value examples: - 123e4567-e12b-12d1-a456-426655440000 type: string merchantCity: description: Merchant city examples: - Goiania type: string merchantName: description: Merchant name examples: - Loja Teste type: string txId: description: BACEN transaction identifier examples: - TX1234567890123456789012345 type: string required: - txId - keyType - keyValue - merchantName - merchantCity - amount - calendar - debtor type: object DueDateCollectionOutput: additionalProperties: false properties: abatement: $ref: '#/components/schemas/AbatementTermsDTO' accountId: examples: - 0196a7b2-3e5f-7061-ac12-34567890abcd type: string additionalInfo: items: $ref: '#/components/schemas/KVDTO' type: - array - 'null' amount: examples: - '100.50' type: string calendar: $ref: '#/components/schemas/DueDateCalendarDTO' cancelledAt: examples: - '2026-05-06T10:40:00Z' format: date-time type: string cancelledReason: examples: - Customer requested cancellation type: string createdAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string currency: enum: - BRL examples: - BRL type: string debtor: $ref: '#/components/schemas/DebtorDTO' description: examples: - Fatura de servicos type: string discount: $ref: '#/components/schemas/DiscountTermsDTO' emvPayload: examples: - >- 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Teste6007Goiania62070503***63041D3F type: string expiresAt: examples: - '2026-05-06T11:30:00Z' format: date-time type: string externalId: examples: - 0196a7b2-4f60-7172-bd23-4567890abcde type: string fine: $ref: '#/components/schemas/FineTermsDTO' id: examples: - 0196a7b2-1c3d-7e4f-8a90-1234567890ab type: string interest: $ref: '#/components/schemas/InterestTermsDTO' isExpired: examples: - false type: boolean keyType: enum: - CPF - CNPJ - PHONE - EMAIL - EVP examples: - EVP type: string keyValue: examples: - 123e4567-e12b-12d1-a456-426655440000 type: string locationUrl: examples: - https://pix.example.com/qr/v2/cobv-abc123 type: string merchantCity: examples: - Goiania type: string merchantDocument: examples: - '39053344705' type: string merchantName: examples: - Loja Teste type: string organizationId: examples: - 0196a7b2-2d4e-7f50-9b01-234567890abc type: string payment: $ref: '#/components/schemas/PaymentDTO' status: enum: - ACTIVE - COMPLETED - CANCELLED examples: - ACTIVE type: string txId: examples: - TX1234567890123456789012345 type: string type: enum: - IMMEDIATE - DUE_DATE examples: - DUE_DATE type: string updatedAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string required: - id - organizationId - accountId - merchantDocument - type - status - txId - keyType - keyValue - merchantName - merchantCity - amount - currency - calendar - externalId - locationUrl - emvPayload - expiresAt - createdAt - updatedAt - isExpired type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string required: - code - title - message 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 AbatementTermsRequest: additionalProperties: false properties: modality: description: Abatement calculation modality enum: - FIXED_VALUE - PERCENTAGE examples: - PERCENTAGE type: string value: description: Abatement value examples: - '5.00' pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$ type: string required: - modality - value type: object AdditionalInfoEntry: additionalProperties: false properties: key: description: Metadata key examples: - orderId type: string value: description: Metadata value examples: - '12345' type: string required: - key - value type: object DueDateCalendarRequest: additionalProperties: false properties: dueDate: description: >- BACEN due date (calendario.dataDeVencimento) — a civil date, no time-of-day or timezone examples: - '2026-09-01' format: date type: string validityAfterDue: description: >- Calendar days of validity after the due date. Optional; defaults to 30 (BACEN API default) when omitted. examples: - 30 format: int64 type: integer required: - dueDate type: object DebtorRequest: additionalProperties: false properties: document: description: Debtor CPF (11 digits) or CNPJ (14 chars, digits or alphanumeric) examples: - '39053344705' type: string name: description: Debtor name examples: - João da Silva type: string type: object DiscountFixedDateRequest: additionalProperties: false properties: date: description: Discount cutoff date — a civil date, no time-of-day or timezone examples: - '2026-08-25' format: date type: string value: description: Discount value applicable through Date examples: - '3.00' type: string required: - date - value type: object FineTermsRequest: additionalProperties: false properties: modality: description: Fine calculation modality enum: - FIXED_VALUE - PERCENTAGE examples: - FIXED_VALUE type: string value: description: Fine value examples: - '10.00' pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$ type: string required: - modality - value type: object InterestTermsRequest: additionalProperties: false properties: modality: description: Interest calculation modality enum: - VALUE_CALENDAR_DAYS - PERCENT_PER_DAY_CALENDAR_DAYS - PERCENT_PER_MONTH_CALENDAR_DAYS - PERCENT_PER_YEAR_CALENDAR_DAYS - VALUE_BUSINESS_DAYS - PERCENT_PER_DAY_BUSINESS_DAYS - PERCENT_PER_MONTH_BUSINESS_DAYS - PERCENT_PER_YEAR_BUSINESS_DAYS examples: - VALUE_CALENDAR_DAYS type: string value: description: Interest value examples: - '1.50' pattern: ^[0-9]+(\.[0-9]{1,2}0{0,32})?$ type: string required: - modality - value type: object AbatementTermsDTO: additionalProperties: false properties: modality: examples: - PERCENTAGE type: string value: examples: - '5.00' type: string required: - modality - value type: object KVDTO: additionalProperties: false properties: key: examples: - orderId type: string value: examples: - '12345' type: string required: - key - value type: object DueDateCalendarDTO: additionalProperties: false properties: dueDate: examples: - '2026-09-01' format: date type: string validityAfterDue: examples: - 30 format: int64 minimum: 0 type: integer required: - dueDate - validityAfterDue type: object DebtorDTO: additionalProperties: false properties: document: examples: - '39053344705' type: string name: examples: - João da Silva type: string type: object DiscountTermsDTO: additionalProperties: false properties: fixedDates: items: $ref: '#/components/schemas/DiscountFixedDateDTO' type: - array - 'null' modality: examples: - FIXED_VALUE_UNTIL_DATES type: string value: type: string required: - modality - value type: object FineTermsDTO: additionalProperties: false properties: modality: examples: - FIXED_VALUE type: string value: examples: - '10.00' type: string required: - modality - value type: object InterestTermsDTO: additionalProperties: false properties: modality: examples: - VALUE_CALENDAR_DAYS type: string value: examples: - '1.50' type: string required: - modality - value type: object PaymentDTO: additionalProperties: false properties: amount: examples: - '100.50' type: string endToEndId: examples: - E12345678202605061030abcdef12345 type: string paidAt: examples: - '2026-05-06T10:35:00Z' format: date-time type: string payer: $ref: '#/components/schemas/PayerDTO' required: - endToEndId - amount - paidAt 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 DiscountFixedDateDTO: additionalProperties: false properties: date: examples: - '2026-08-25' format: date type: string value: examples: - '3.00' type: string required: - date - value type: object PayerDTO: additionalProperties: false properties: ispb: examples: - '12345678' type: string name: examples: - João da Silva type: string taxId: examples: - '39053344705' type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````