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

Create a due-date Pix collection (cobv)

cURL

curl --request POST \
  --url https://api.example.com/cob-hub/v1/collections/duedate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --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"
}
'

200

{
  "accountId": "0196a7b2-3e5f-7061-ac12-34567890abcd",
  "amount": "100.50",
  "calendar": {
    "dueDate": "2026-09-01",
    "validityAfterDue": 30
  },
  "createdAt": "2026-05-06T10:30:00Z",
  "currency": "BRL",
  "emvPayload": "00020126360014br.gov.bcb.pix2562https://pix.example.com/qr/v2/cobv-abc1235204000053039865802BR5910Loja Teste6007Goiania62070503***63041D3F",
  "expiresAt": "2026-05-06T11:30:00Z",
  "externalId": "0196a7b2-4f60-7172-bd23-4567890abcde",
  "id": "0196a7b2-1c3d-7e4f-8a90-1234567890ab",
  "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": "2026-05-06T10:30:00Z",
  "abatement": {
    "modality": "PERCENTAGE",
    "value": "5.00"
  },
  "additionalInfo": [
    {
      "key": "orderId",
      "value": "12345"
    }
  ],
  "cancelledAt": "2026-05-06T10:40:00Z",
  "cancelledReason": "Customer requested cancellation",
  "debtor": {
    "document": "39053344705",
    "name": "João da Silva"
  },
  "description": "Fatura de servicos",
  "discount": {
    "modality": "FIXED_VALUE_UNTIL_DATES",
    "value": "<string>",
    "fixedDates": [
      {
        "date": "2026-08-25",
        "value": "3.00"
      }
    ]
  },
  "fine": {
    "modality": "FIXED_VALUE",
    "value": "10.00"
  },
  "interest": {
    "modality": "VALUE_CALENDAR_DAYS",
    "value": "1.50"
  },
  "payment": {
    "amount": "100.50",
    "endToEndId": "E12345678202605061030abcdef12345",
    "paidAt": "2026-05-06T10:35:00Z",
    "payer": {
      "ispb": "12345678",
      "name": "João da Silva",
      "taxId": "39053344705"
    }
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

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.

Required string length: 1 - 64

X-Account-Id · string · requerido

Receiver merchant account UUID (scopes DICT key validation)

Ejemplo:

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

Cuerpo

application/json

amount · string · requerido

Collection amount in BRL

calendar · object · requerido

Due-date expiration calendar

Show child attributes

debtor · object · requerido

Debtor block (mandatory for due-date collections)

Show child attributes

keyType · string · requerido

Pix key type

Ejemplo:

"EVP"

keyValue · string · requerido

Pix key value

Ejemplo:

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

merchantCity · string · requerido

Merchant city

Ejemplo:

"Goiania"

merchantName · string · requerido

Merchant name

Ejemplo:

"Loja Teste"

txId · string · requerido

BACEN transaction identifier

Ejemplo:

"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)

Ejemplo:

"BRL"

description · string

Free-form description

Ejemplo:

"Fatura de servicos"

discount · object

Optional discount (desconto) modifier

Option 1

Option 2

Show child attributes

fine · object

Optional fine (multa) modifier

Show child attributes

interest · object

Optional interest (juros) modifier

Show child attributes

Respuesta

200

application/json

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.

accountId · string · requerido

Ejemplo:

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

amount · string · requerido

Ejemplo:

"100.50"

calendar · object · requerido

Show child attributes

createdAt · string<date-time> · requerido

Ejemplo:

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

currency · enum<string> · requerido

Opciones disponibles: BRL

Ejemplo:

"BRL"

emvPayload · string · requerido

Ejemplo:

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

expiresAt · string<date-time> · requerido

Ejemplo:

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

externalId · string · requerido

Ejemplo:

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

id · string · requerido

Ejemplo:

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

isExpired · boolean · requerido

Ejemplo:

false

keyType · enum<string> · requerido

Opciones disponibles: CPF, CNPJ, PHONE, EMAIL, EVP

Ejemplo:

"EVP"

keyValue · string · requerido

Ejemplo:

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

locationUrl · string · requerido

Ejemplo:

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

merchantCity · string · requerido

Ejemplo:

"Goiania"

merchantDocument · string · requerido

Ejemplo:

"39053344705"

merchantName · string · requerido

Ejemplo:

"Loja Teste"

organizationId · string · requerido

Ejemplo:

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

status · enum<string> · requerido

Opciones disponibles: ACTIVE, COMPLETED, CANCELLED

Ejemplo:

"ACTIVE"

txId · string · requerido

Ejemplo:

"TX1234567890123456789012345"

type · enum<string> · requerido

Opciones disponibles: IMMEDIATE, DUE_DATE

Ejemplo:

"DUE_DATE"

updatedAt · string<date-time> · requerido

Ejemplo:

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

abatement · object

Show child attributes

additionalInfo · object[] | null

Show child attributes

cancelledAt · string<date-time>

Ejemplo:

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

cancelledReason · string

Ejemplo:

"Customer requested cancellation"

debtor · object

Show child attributes

description · string

Ejemplo:

"Fatura de servicos"

discount · object

Show child attributes

fine · object

Show child attributes

interest · object

Show child attributes

payment · object

Show child attributes