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.

POST /collections/duedate

cURL with fictitious data

cURL

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"
}'

201

{
  "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"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

Idempotency-Key · string · required

Client-generated key used to retry exactly the same request safely.

Required string length: 1 - 64

X-Account-Id · string · required

UUID of the account associated with the operation.

Example:

"019606a1-3b4c-7d8e-9f01-234567890abc"

Body

application/json

amount · string · required

Collection amount in BRL

calendar · object · required

Due-date expiration calendar

Show child attributes

debtor · object · required

Debtor block (mandatory for due-date collections)

Show child attributes

keyType · string · required

Pix key type

Example:

"EVP"

keyValue · string · required

Pix key value

Example:

"123e4567-e12b-12d1-a456-426655440000"

merchantCity · string · required

Merchant city

Example:

"Goiania"

merchantName · string · required

Merchant name

Example:

"Loja Teste"

txId · string · required

BCB transaction identifier

Example:

"TX1234567890123456789012345"

abatement · object

Optional abatement (abatimento) modifier

Show child attributes

additionalInfo · object[] | null

Free-form key/value metadata (max 50 entries)

Show child attributes

currency · string

Currency (BRL only)

Example:

"BRL"

description · string

Free-form description

Example:

"Fatura de servicos"

discount · object

Optional discount (desconto) modifier

Show child attributes

fine · object

Optional fine (multa) modifier

Show child attributes

interest · object

Optional interest (juros) modifier

Show child attributes

Response

201

application/json

Created

accountId · string · required

Example:

"0196a7b2-3e5f-7061-ac12-34567890abcd"

amount · string · required

Example:

"100.50"

calendar · object · required

Show child attributes

createdAt · string<date-time> · required

Example:

"2026-05-06T10:30:00Z"

currency · enum<string> · required

Available options: BRL

Example:

"BRL"

emvPayload · string · required

Example:

"00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Teste6007Goiania62070503***63041D3F"

expiresAt · string<date-time> · required

Example:

"2026-05-06T11:30:00Z"

externalId · string · required

Example:

"0196a7b2-4f60-7172-bd23-4567890abcde"

id · string · required

Example:

"0196a7b2-1c3d-7e4f-8a90-1234567890ab"

isExpired · boolean · required

Example:

false

keyType · enum<string> · required

Available options: CPF, CNPJ, PHONE, EMAIL, EVP

Example:

"EVP"

keyValue · string · required

Example:

"123e4567-e12b-12d1-a456-426655440000"

locationUrl · string · required

Example:

"https://pix.example.com/qr/v2/cobv-abc123"

merchantCity · string · required

Example:

"Goiania"

merchantDocument · string · required

Example:

"39053344705"

merchantName · string · required

Example:

"Loja Teste"

organizationId · string · required

Example:

"0196a7b2-2d4e-7f50-9b01-234567890abc"

status · enum<string> · required

Available options: ACTIVE, COMPLETED, CANCELLED

Example:

"ACTIVE"

txId · string · required

Example:

"TX1234567890123456789012345"

type · enum<string> · required

Available options: IMMEDIATE, DUE_DATE

Example:

"DUE_DATE"

updatedAt · string<date-time> · required

Example:

"2026-05-06T10:30:00Z"

abatement · object

Show child attributes

additionalInfo · object[] | null

Show child attributes

cancelledAt · string<date-time>

Example:

"2026-05-06T10:40:00Z"

cancelledReason · string

Example:

"Customer requested cancellation"

debtor · object

Show child attributes

description · string

Example:

"Fatura de servicos"

discount · object

Show child attributes

fine · object

Show child attributes

interest · object

Show child attributes

payment · object

Show child attributes