Criar cobrança imediata.

PUT

/cob/{txid}

Cob

Endpoint para criar uma cobrança imediata.

Request Example

Shell

JavaScript

Java

Swift

cURL

Exemplo de criação de cobrança imediata 1Exemplo de criação de cobrança imediata com Saque PixExemplo de criação de cobrança imediata com Saque Pix 2Exemplo de criação de cobrança imediata com Saque Pix 3

curl --location --request PUT 'https://infopago.apidog.io//cob/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "calendario": {
        "expiracao": 3600
    },
    "devedor": {
        "cnpj": "12345678000195",
        "nome": "Empresa de Serviços SA",
        "contas": [
            {
                "numero": "123456",
                "agencia": "0001",
                "ispb": "11112222"
            }
        ]
    },
    "valor": {
        "original": "37.00",
        "modalidadeAlteracao": 1
    },
    "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
    "solicitacaoPagador": "Serviço realizado.",
    "infoAdicionais": [
        {
            "nome": "Campo 1",
            "valor": "Informação Adicional1 do PSP-Recebedor"
        },
        {
            "nome": "Campo 2",
            "valor": "Informação Adicional2 do PSP-Recebedor"
        }
    ]
}'

Response Example

201 - Exemplo de cobrança imediata 1

{
    "calendario": {
        "criacao": "2020-09-09T20:15:00.358Z",
        "expiracao": 3600
    },
    "txid": "7978c0c97ea847e78e8849634473c1f1",
    "revisao": 0,
    "loc": {
        "id": 789,
        "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
        "tipoCob": "cob"
    },
    "location": "pix.example.com/qr/9d36b84fc70b478fb95c12729b90ca25",
    "status": "ATIVA",
    "devedor": {
        "cnpj": "12345678000195",
        "nome": "Empresa de Serviços SA"
    },
    "valor": {
        "original": "37.00",
        "modalidadeAlteracao": 1
    },
    "chave": "7d9f0335-8dcc-4054-9bf9-0dbd61d36906",
    "solicitacaoPagador": "Serviço realizado.",
    "infoAdicionais": [
        {
            "nome": "Campo 1",
            "valor": "Informação Adicional1 do PSP-Recebedor"
        },
        {
            "nome": "Campo 2",
            "valor": "Informação Adicional2 do PSP-Recebedor"
        }
    ]
}

Requisição

Parâmetros Path

txid

string

requerido

Parâmetros Bodyapplication/json

Dados enviados para criação ou alteração da cobrança imediata via API Pix

calendario

object

Calendário

opcional

Os campos aninhados sob o identificador calendário organizam informações a respeito de controle de tempo da cobrança.

expiracao

integer <int32>

Tempo de vida da cobrança, especificado em segundos.

opcional

Tempo de vida da cobrança, especificado em segundos a partir da data de criação (Calendario.criacao)

Padrão:

86400

Exemplo:

3600

devedor

opcional

Os campos aninhados sob o objeto devedor são opcionais e identificam o devedor, ou seja, a pessoa ou a instituição a quem a cobrança está endereçada. Não identifica, necessariamente, quem irá efetivamente realizar o pagamento. Um CPF pode ser o devedor de uma cobrança, mas pode acontecer de outro CPF realizar, efetivamente, o pagamento do documento. Não é permitido que o campo devedor.cpf e campo devedor.cnpj estejam preenchidos ao mesmo tempo. Se o campo devedor.cnpj está preenchido, então o campo devedor.cpf não pode estar preenchido, e vice-versa. Se o campo devedor.nome está preenchido, então deve existir ou um devedor.cpf ou um campo devedor.cnpj preenchido.

One of

Pessoa Física

Pessoa Jurídica

cpf

string

CPF

requerido

CPF do usuário.

Padrão de combinação:

/^\d{11}$/

nome

string

Nome

requerido

Nome do usuário.

<= 200 Caracteres

contas

array [object {3}]

Contas

opcional

Lista de contas associadas ao devedor.

loc

object

opcional

Identificador da localização do payload.

valor

object

opcional

valores monetários referentes à cobrança.

original

string

Valor

requerido

Valor original da cobrança.

Padrão de combinação:

\d{1,10}\.\d{2}

modalidadeAlteracao

integer <int32>

Modalidade de alteração

opcional

Trata-se de um campo que determina se o valor final do documento pode ser alterado pelo pagador. Na ausência desse campo, assume-se que não se pode alterar o valor do documento de cobrança, ou seja, assume-se o valor 0. Se o campo estiver presente e com valor 1, então está determinado que o valor final da cobrança pode ter seu valor alterado pelo pagador.

>= 0<= 1

retirada

Informações de retirada

opcional

É uma estrutura opcional relacionada ao conceito de recebimento de numerário. Apenas um agrupamento por vez é permitido, quando há saque não há troco e vice-versa.

Quando uma cobrança imediata tem uma estrutura de retirada ela deixa de ser considerada Pix comum e passa à categoria de Pix Saque ou Pix Troco.

Para que o preenchimento do objeto retirada seja considerado válido as seguintes regras se aplicam:

os campos modalidadeAgente e prestadorDoServicoDeSaque são de preenchimento obrigatório;

quando o saque estiver presente a cobrança deve respeitar as seguintes condições:

O campo valor.original deve ser preenchido com valor igual a 0.00 (zero);

O campo valor.modalidadeAlteracao deve possuir o valor 0 (zero) explicitamente, ou implicitamente (pelo não preenchimento).

quando o troco estiver presente a cobrança deve respeitar as seguintes condições:

O campo valor.original deve ser preenchido com valor maior que 0.00 (zero);

O campo valor.modalidadeAlteracao deve possuir o valor 0 (zero) explicitamente, ou implicitamente (pelo não preenchimento).

IMPORTANTE: Quando usados o saque ou troco não será permitida a alteração do valor.original recebido. Na presença de saque ou troco o recebimento do campo valor.modalidadeAlteracao com valor 1 (um) é considerado erro.

Exemplos válidos:

Considerando os campos da estrutura valor e o predicado 'presente' cujo resultado é verdade quando a estrutura apontada é encontrada temos:

uma cobrança com valor fixo (condições: valor.original > 0 && valor.modalidadeAlteração = 0 && !presente(valor.retirada))

...
"valor": {
  "original": "10.00"
},
...

uma cobrança com valor alterável (condições: valor.original >= 0.00 && modalidadeAlteração = 1 && !presente(valor.retirada))

...
"valor": {
  "original": "10.00",
  "modalidadeAlteracao": 1
},

saque com valor fixo (condições: valor.original = 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.saque) && valor.retirada.saque.valor > 0 && valor.retirada.saque.modalidadeAlteracao = 0)

...
"valor": {
  "original": "0.00",
  "retirada": {
    "saque": {
      "valor": "5.00",
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

saque com valor alterável (condições: valor.original = 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.saque) && valor.retirada.saque.valor >= 0 && valor.retirada.saque.modalidadeAlteracao = 1)

...
"valor": {
  "original": "0.00",
  "retirada": {
    "saque": {
      "valor": "5.00",
      "modalidadeAlteracao": 1,
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

cobrança com troco fixo (condições: valor.original > 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.troco) && valor.retirada.troco.valor > 0 && valor.retirada.troco.modalidadeAlteracao = 0)

...
"valor": {
  "original": "10.00",
  "retirada": {
    "troco": {
      "valor": "5.00",
      "modalidadeAgente": "AGTEC",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

cobrança com troco alterável (condições: valor.original > 0.00 && valor.modalidadeAlteração = 0 && presente(valor.retirada.troco) && valor.retirada.troco.valor >= 0 && valor.retirada.troco.modalidadeAlteracao = 1)

...
  "valor": {
    "original": "10.00",
    "retirada": {
      "troco": {
        "valor": "0.00",
        "modalidadeAlteracao": 1,
        "modalidadeAgente": "AGTEC",
        "prestadorDoServicoDeSaque": "12345678"
      }
    }
  },
...

Exemplos inválidos:

Abaixo alguns exemplos que não são válidos. Convém observar que esta listagem não tem pretensão de ser completa, sendo tão somente uma referência para alguns erros possíveis.

saque sem modalidadeAgente e prestadorDoServicoDeSaque

...
"valor": {
  "original": "0.00",
  "retirada": {
    "saque": {
      "valor": "5.00"
    }
  }
},
...

cobrança com saque e troco juntos (não pode ter os dois ao mesmo tempo)

...
"valor": {
  "original": "100.00",
  "retirada": {
    "saque": {
      "valor": "50.00",
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    },
    "troco": {
      "valor": "30.00",
      "modalidadeAgente": "AGTEC",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

saque com valor.original maior que 0.00 (zero) (saque requer valor.original = 0.00)

...
"valor": {
  "original": "10.00",
  "retirada": {
    "saque": {
      "valor": "5.00",
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

troco com valor.original igual a 0.00 (zero) (para haver troco tem que haver valor.original > 0.00)

...
"valor": {
  "original": "0.00",
  "retirada": {
    "troco": {
      "valor": "5.00",
      "modalidadeAgente": "AGTEC",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

saque com valor.original alterável (não se pode alterar o valor.original na presença do saque)

...
"valor": {
  "original": "0.00",
  "modalidadeAlteracao": 1,
  "retirada": {
    "saque": {
      "valor": "5.00",
      "modalidadeAlteracao": 1,
      "modalidadeAgente": "AGPSS",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

troco com valor.original alterável (não se pode alterar o valor.original na presença do troco)

...
"valor": {
  "original": "0.01",
  "modalidadeAlteracao": 1,
  "retirada": {
    "troco": {
      "valor": "5.00",
      "modalidadeAlteracao": 1,
      "modalidadeAgente": "AGTOT",
      "prestadorDoServicoDeSaque": "12345678"
    }
  }
},
...

chave

string

Chave DICT do recebedor

opcional

Formato do campo chave

O campo chave determina a chave Pix registrada no DICT que será utilizada para a cobrança. Essa chave será lida pelo aplicativo do PSP do pagador para consulta ao DICT, que retornará a informação que identificará o recebedor da cobrança.

Os tipos de chave podem ser: telefone, e-mail, cpf/cnpj ou EVP.

O formato das chaves pode ser encontrado na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para iniciação do Pix.

<= 77 Caracteres

solicitacaoPagador

string

Solicitação ao pagador

opcional

O campo solicitacaoPagador, opcional, determina um texto a ser apresentado ao pagador para que ele possa digitar uma informação correlata, em formato livre, a ser enviada ao recebedor. Esse texto será preenchido, na pacs.008, pelo PSP do pagador, no campo RemittanceInformation . O tamanho do campo na pacs.008 está limitado a 140 caracteres.

<= 140 Caracteres

infoAdicionais

array [object {2}]

Informações adicionais

opcional

Cada respectiva informação adicional contida na lista (nome e valor) deve ser apresentada ao pagador.

nome

string

Nome

requerido

Nome do campo.

<= 50 Caracteres

valor

string

Valor

requerido

Dados do campo.

<= 200 Caracteres

Examples

Respostas

🟢201Created

application/json

Cobrança imediata criada

Body

Dados criados ou alterados da cobrança imediata via API Pix

calendario

object

Calendário

opcional

Os campos aninhados sob o identificador calendário organizam informações a respeito de controle de tempo da cobrança.

criacao

string <date-time>

Data de Criação

requerido

Timestamp que indica o momento em que foi criada a cobrança. Respeita o formato definido na RFC 3339.

expiracao

integer <int32>

Tempo de vida da cobrança, especificado em segundos.

requerido

Tempo de vida da cobrança, especificado em segundos a partir da data de criação (Calendario.criacao)

Padrão:

86400

Exemplo:

3600

txid

string

TxId

opcional

The "txId" field is a unique identifier generated by the Pix system to uniquely identify and monitor transactions.

revisao

integer <int32>

Revisão

read-onlyopcional

O campo `revisao`

Denota a revisão da cobrança. Sempre começa em zero. Sempre varia em acréscimos de 1.

O incremento em uma cobrança deve ocorrer sempre que um objeto da cobrança em questão for alterado.
O campo loc é uma exceção a esta regra.

Se em uma determinada alteração em uma cobrança, o único campo alterado for o campo loc,
então esta operação não incrementa a revisão da cobrança.

O campo loc não ocasiona uma alteração na cobrança em si.
Não é necessário armazenar histórico das alterações do campo loc para uma determinada cobrança.
Para os outros campos da cobrança, registra-se histórico.

devedor

opcional

One of

Pessoa Física

Pessoa Jurídica

cpf

string

CPF

requerido

CPF do usuário.

Padrão de combinação:

/^\d{11}$/

nome

string

Nome

requerido

Nome do usuário.

<= 200 Caracteres

loc

object

opcional

Identificador da localização do payload.

integer <int64>

Id da location

read-onlyrequerido

Identificador da location a ser informada na criação da cobrança .

location

string <uri>

Localização do payload

read-onlyrequerido

Localização do Payload a ser informada na criação da cobrança.

<= 77 Caracteres

Exemplo:

pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002

tipoCob

enum<string>

Tipo da cobrança

requerido

Valores permitidos:

cobcobv

criacao

string <date-time>

Data de Criação

read-onlyrequerido

Data e hora em que a location foi criada. Respeita RFC 3339.

location

string <uri>

Localização do payload

read-onlyopcional

Localização do Payload a ser informada na criação da cobrança.

<= 77 Caracteres

Exemplo:

pix.example.com/qr/v2/2353c790eefb11eaadc10242ac120002

status

enum<string>

Status do registro da cobrança.

opcional

Estado do registro da cobrança. Não se confunde com o estado da cobrança em si, ou seja, não guarda relação com o fato de a cobrança encontrar-se vencida ou expirada, por exemplo.

Os status são assim definidos:

ATIVA: indica que o registro se refere a uma cobrança que foi gerada mas ainda não foi paga nem removida;

CONCLUIDA: indica que o registro se refere a uma cobrança que já foi paga e, por conseguinte, não pode acolher outro pagamento;

REMOVIDA_PELO_USUARIO_RECEBEDOR: indica que o usuário recebedor solicitou a remoção do registro da cobrança; e

REMOVIDA_PELO_PSP: indica que o PSP Recebedor solicitou a remoção do registro da cobrança.

Valores permitidos:

ATIVACONCLUIDAREMOVIDA_PELO_USUARIO_RECEBEDORREMOVIDA_PELO_PSP