Create a due-date Pix collection (cobv)

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/cob-hub/v1/collections/duedate"

	payload := strings.NewReader("{\n  \"abatement\": {\n    \"modality\": \"PERCENTAGE\",\n    \"value\": \"5.00\"\n  },\n  \"additionalInfo\": [\n    {\n      \"key\": \"orderId\",\n      \"value\": \"12345\"\n    }\n  ],\n  \"amount\": \"100.50\",\n  \"calendar\": {\n    \"dueDate\": \"2030-09-01\",\n    \"validityAfterDue\": 30\n  },\n  \"currency\": \"BRL\",\n  \"debtor\": {\n    \"document\": \"39053344705\",\n    \"name\": \"João da Silva\"\n  },\n  \"description\": \"Fatura de servicos\",\n  \"discount\": {\n    \"modality\": \"VALUE_PER_CALENDAR_DAY_ADVANCE\",\n    \"value\": \"3.00\"\n  },\n  \"fine\": {\n    \"modality\": \"FIXED_VALUE\",\n    \"value\": \"10.00\"\n  },\n  \"interest\": {\n    \"modality\": \"VALUE_CALENDAR_DAYS\",\n    \"value\": \"1.50\"\n  },\n  \"keyType\": \"EVP\",\n  \"keyValue\": \"123e4567-e12b-12d1-a456-426655440000\",\n  \"merchantCity\": \"Goiania\",\n  \"merchantName\": \"Loja Teste\",\n  \"txId\": \"TX1234567890123456789012345\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("X-Account-Id", "<x-account-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    'X-Account-Id': '<x-account-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.example.com/cob-hub/v1/collections/duedate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/cob-hub/v1/collections/duedate"

payload = {
    "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"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "X-Account-Id": "<x-account-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

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

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

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0201",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Pix key does not exist or is not active.",
  "code": "PIX-0201"
}

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

{
  "type": "https://errors.lerian.studio/v1/PIX-0223",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "Provider adapter is unreachable.",
  "code": "PIX-0223"
}

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

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/cob-hub/v1/collections/duedate"

	payload := strings.NewReader("{\n  \"abatement\": {\n    \"modality\": \"PERCENTAGE\",\n    \"value\": \"5.00\"\n  },\n  \"additionalInfo\": [\n    {\n      \"key\": \"orderId\",\n      \"value\": \"12345\"\n    }\n  ],\n  \"amount\": \"100.50\",\n  \"calendar\": {\n    \"dueDate\": \"2030-09-01\",\n    \"validityAfterDue\": 30\n  },\n  \"currency\": \"BRL\",\n  \"debtor\": {\n    \"document\": \"39053344705\",\n    \"name\": \"João da Silva\"\n  },\n  \"description\": \"Fatura de servicos\",\n  \"discount\": {\n    \"modality\": \"VALUE_PER_CALENDAR_DAY_ADVANCE\",\n    \"value\": \"3.00\"\n  },\n  \"fine\": {\n    \"modality\": \"FIXED_VALUE\",\n    \"value\": \"10.00\"\n  },\n  \"interest\": {\n    \"modality\": \"VALUE_CALENDAR_DAYS\",\n    \"value\": \"1.50\"\n  },\n  \"keyType\": \"EVP\",\n  \"keyValue\": \"123e4567-e12b-12d1-a456-426655440000\",\n  \"merchantCity\": \"Goiania\",\n  \"merchantName\": \"Loja Teste\",\n  \"txId\": \"TX1234567890123456789012345\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("X-Account-Id", "<x-account-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    'X-Account-Id': '<x-account-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
  })
};

fetch('https://api.example.com/cob-hub/v1/collections/duedate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/cob-hub/v1/collections/duedate"

payload = {
    "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"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "X-Account-Id": "<x-account-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

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

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

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request."
}

{
  "code": "PIX-0016",
  "title": "Unsupported Media Type",
  "message": "The request body must be sent with Content-Type: application/json."
}

{
  "type": "https://errors.lerian.studio/v1/PIX-0201",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Pix key does not exist or is not active.",
  "code": "PIX-0201"
}

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

{
  "type": "https://errors.lerian.studio/v1/PIX-0223",
  "title": "Bad Gateway",
  "status": 502,
  "detail": "Provider adapter is unreachable.",
  "code": "PIX-0223"
}

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

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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. Resending under the same key and X-Account-Id within 1 hour returns the original response, with its original 201 and X-Idempotency-Replayed: true, 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

Created

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"

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

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

API de Pix Automático

Manejo de errores

Create a due-date Pix collection (cobv)

Autorizaciones

Encabezados

Cuerpo

Respuesta