> ## 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 en/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. license: name: Elastic License 2.0 url: https://www.elastic.co/licensing/elastic-license title: Pix Lerian — Collections version: release-candidate 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 immediate Pix collections. name: Immediate Collections - description: Create, retrieve, list, and cancel due-date Pix collections. name: Due-Date 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: Client-generated key used to retry exactly the same request safely. in: header name: Idempotency-Key required: true schema: maxLength: 64 minLength: 1 type: string description: >- Client-generated key used to retry exactly the same request safely. example: pix-demo-20260903-000001 - description: UUID of the account associated with the operation. in: header name: X-Account-Id required: true schema: description: UUID of the account associated with the operation. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string example: 019606a1-3b4c-7d8e-9f01-234567890abc 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: '201': content: application/json: schema: $ref: '#/components/schemas/DueDateCollectionOutput' examples: fictitiousExample: summary: Fictitious example value: abatement: modality: PERCENTAGE value: '5.00' accountId: 019606a1-3b4c-7d8e-9f01-234567890abc additionalInfo: - key: orderId value: '12345' amount: '100.50' calendar: dueDate: '2030-09-01' validityAfterDue: 30 createdAt: '2030-08-20T10:30:00Z' currency: BRL debtor: document: '39053344705' name: João da Silva description: Fatura de servicos discount: modality: VALUE_PER_CALENDAR_DAY_ADVANCE value: '3.00' emvPayload: >- 00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Teste6007Goiania62070503***63041D3F expiresAt: '2030-10-01T23:59:59Z' externalId: 0196a7b2-4f60-7172-bd23-4567890abcde fine: modality: FIXED_VALUE value: '10.00' id: 0196a7b2-1c3d-7e4f-8a90-1234567890ab interest: modality: VALUE_CALENDAR_DAYS value: '1.50' isExpired: false keyType: EVP keyValue: 123e4567-e12b-12d1-a456-426655440000 locationUrl: https://pix.example.com/qr/v2/cobv-abc123 merchantCity: Goiania merchantDocument: '39053344705' merchantName: Loja Teste organizationId: 0196a7b2-2d4e-7f50-9b01-234567890abc status: ACTIVE txId: TX1234567890123456789012345 type: DUE_DATE updatedAt: '2030-08-20T10:30:00Z' 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: >- Idempotency-Key absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT 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 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: >- txId already claimed by a non-replayable row -- divergent content, a different account, or a different collection type (PIX-0012) -- or the provider reports a conflicting state (PIX-0226). '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: The Idempotency-Key was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Idempotency-Key replayed with a divergent request -- a different method, URL or body, or a different X-Account-Id (PIX-0031). Evidence that an earlier request under this key already succeeded. Legacy {code,title,message} envelope, NOT problem+json. '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 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 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 x-codeSamples: - lang: bash label: cURL with fictitious data source: |- curl --request POST \ --url https://api.example.com/cob-hub/v1/collections/duedate \ --header 'Authorization: Bearer demo-access-token' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: pix-demo-20260903-000001' \ --header 'X-Account-Id: 019606a1-3b4c-7d8e-9f01-234567890abc' \ --data '{ "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" }' 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: $ref: '#/components/schemas/DiscountTermsRequest' description: Optional discount (desconto) modifier 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: BCB 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 examples: - PERCENTAGE type: string value: description: Abatement value examples: - '5.00' 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: >- BCB 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 (BCB 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 DiscountTermsRequest: 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 examples: - FIXED_VALUE_UNTIL_DATES type: string value: description: Discount value (per-day advance modalities only) type: string required: - modality type: object FineTermsRequest: additionalProperties: false properties: modality: description: Fine calculation modality examples: - FIXED_VALUE type: string value: description: Fine value examples: - '10.00' type: string required: - modality - value type: object InterestTermsRequest: additionalProperties: false properties: modality: description: Interest calculation modality examples: - VALUE_CALENDAR_DAYS type: string value: description: Interest value examples: - '1.50' 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 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 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 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 ````