Obter payload JSON da cobrança imediata

get https://api.pix.voluti.com.br/{pixUrlAccessToken}

Use esse endpoint quando o usuário for realizar a leitura de um QR Code dinâmico gerado pelo recebedor. Este endpoint retorna uma estrutura JWS que contém as informações necessárias para a transação.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyIsImtpZCI6IjIwMTEtMDQtMjkiLCJqa3UiOiJodHRwczovL3Rvb2xzLmlldGYub3JnL2h0bWwvcmZjNzUxNyIsIng1dCI6IkFwcGVuZGl4QUV4YW1wbGVBMUpXS1NSc2FLZXkifQ.eyJjYWxlbmRhcmlvIjp7ImNyaWFjYW8iOiIyMDIwLTA5LTE1VDE5OjM5OjU0LjAxM1oiLCJhcHJlc2VudGFjYW8iOiIyMDIwLTA0LTAxVDE4OjAwOjAwWiIsImV4cGlyYWNhbyI6IjM2MDAifSwidHhpZCI6ImZjOWE0MzY2ZmYzZDQ5NjRiNWRiYzZjOTFhODcyMmQzIiwicmV2aXNhbyI6IjMiLCJzdGF0dXMiOiJBVElWQSIsInZhbG9yIjp7Im9yaWdpbmFsIjoiNTAwLjAwIn0sImNoYXZlIjoiNzQwN2M5YzgtZjc4Yi0xMWVhLWFkYzEtMDI0MmFjMTIwMDAyIiwic29saWNpdGFjYW9QYWdhZG9yIjoiSW5mb3JtYXIgY2FydGFvIGZpZGVsaWRhZGUiLCJpbmZvQWRpY2lvbmFpcyI6W3sibm9tZSI6InF1YW50aWRhZGUiLCJ2YWxvciI6IjIifV19.qI7NUrYkwcgXmyoyOjt2YLQyhxH-lPdr3xQ7RId9TDXZ-MlWmPJkUScjuo1Nz_EvlSotbWDGOxErBXHeTLHOQM-9T7lBmG5iw6uEX7L5U72XiganIm80EZCFD1vBPq9j89i4cP2U2Yv21TTt8JLhjA57KHLOSlj-KB5UAKCH-MX3AORFcrXFrYL2rrSQDe-lFNtdyPRwLQHIrhkQ6RR2FPhynzUG0401LScS9mWLLYbYzhzwtP5lk07Ryf4MZq86ihmOLFZXkIiW7pbSd8QfD5Dvj28XebLQi_bam9wInqKB--57_N741BskCN_TXf0EHbQ1qjNTgiT8Y1GIrA4pFA

Conforme pode-se verificar no exemplo acima, o objeto JWS apresenta três fragmentos separados pelo caractere . (ponto). São eles: header, payload e signature.

Nota:

Para garantir a segurança no acesso a essas URLs, é fundamental seguir as diretrizes estabelecidas no Manual de Segurança do Pix, disponível para consulta neste link.

time	status	user agent
Retrieving recent requests…

Loading…

Responses

Response body

object

calendario

object

required

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

criacao

date-time

required

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

apresentacao

date-time

required

Timestamp que indica o momento em que o payload JSON que representa a cobrança foi recuperado. Ou seja, idealmente, é o momento em que o usuário realizou a captura do QR Code para verificar os dados de pagamento. Respeita o formato definido na RFC 3339.

expiracao

int32

Defaults to 86400

Tempo de vida da cobrança, especificado em segundos a partir da data do campo criação.

txid

string

required

Identificador da transação (txid):

O campo txid determina o identificador da transação, sendo crucial para o processo de conciliação de pagamentos, pois determina a transação de forma única. Na pacs.008, é mencionado como TransactionIdentification <txId> ou idConciliacaoRecebedor.

Funcionalidade:

O txid é gerado pelo usuário recebedor e enviado ao PSP do pagador.
Após a confirmação do pagamento, é transmitido para o SPI via pacs.008 e também para o PSP do recebedor.
Ao detectar um pagamento com txid, o PSP do recebedor pode informar ao usuário recebedor sobre a liquidação específica desse pagamento.

Responsabilidades:

O txid é criado exclusivamente pelo usuário recebedor e está sob sua responsabilidade.
Cada txid é único por CPF/CNPJ do usuário recebedor, com a validação dessa regra realizada pelo PSP recebedor na API Pix.

revisao

int32

required

Indica a revisão da cobrança, começando sempre em zero e aumentando em incrementos de 1.

Incremento: A revisão é incrementada sempre que um objeto da cobrança é alterado, exceto pelo campo loc.
Exceção: Se a única alteração em uma cobrança for no campo loc, a revisão não é incrementada, pois o loc não altera a cobrança em si.
Armazenamento: Não é necessário manter histórico das alterações do campo loc, mas é necessário para outros campos da cobrança.

devedor

Os campos contidos 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.

cpf ou cnpj: A cobrança pode ter um CPF ou um CNPJ como devedor. Não é permitido preencher ambos ao mesmo tempo.
nome: Se o nome do devedor estiver preenchido, deve existir um CPF ou CNPJ preenchido.

status

string

required

Estado do registro da cobrança.

Os status:

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;
REMOVIDO_PELO_USUARIO_RECEBEDOR: Indica que o usuário recebedor solicitou a remoção do registro da cobrança;
REMOVIDO_PELO_PSP: Indica que o PSP recebedor solicitou a remoção do registro da cobrança.

ATIVA CONCLUIDA REMOVIDA_PELO_USUARIO_RECEBEDOR REMOVIDA_PELO_PSP

valor

object

required

Todos os campos que indicam valores monetários obedecem ao pattern \d{1,10}.\d{2}. O separador decimal é o caractere ponto. Não é aplicável utilizar separador de milhar. Exemplos de valores aderentes ao padrão: “1.00”, “123.99”, “123456789.23

original

string

required

Valor original da cobrança.

modalidadeAlteracao

int32

0 to 1

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.

retirada

object

É 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 deve ser preenchido com valor igual a 0.00 (zero);
- O campo 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 deve ser preenchido com valor maior que 0.00 (zero);
- O campo 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 recebido. Na presença de saque ou troco o recebimento do campo 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

length ≤ 77

Formato da Chave Pix na qual a conta receberá o valor.

Conforme especificado na PACS.008. Os tipos de chave permitidos são:

Telefone
E-mail
CPF/CNPJ
O Endereço Virtual de Pagamento (EVP)

O formato detalhado das chaves está na seção "Formatação das chaves do DICT no BR Code" do Manual de Padrões para Iniciação do Pix.
.

solicitacaoPagador

string

length ≤ 140

Permite que o pagador inclua um texto livre relacionado ao recebedor.

Preenchimento: O PSP do pagador insere esse texto no campo RemittanceInformation da pacs.008.

Limite de caracteres: Restrito a 140 caracteres.

infoAdicionais

array of objects

Apresentação das informações adicionais ao pagador:

Cada informação adicional contida nos campos nome e valor deve ser exibida ao pagador.

Informações adicionais

object

nome

string

required

length ≤ 50

Nome do pagador.

valor

string

required

length ≤ 200

Valor de cobrança.

Language


xxxxxxxxxx
1
curl --request GET \
2
     --url https://api.pix.voluti.com.br/pixUrlAccessToken \
3
     --header 'accept: application/jose'


xxxxxxxxxx
22
 
1
{
2
  "calendario": {
3
    "criacao": "2020-09-15T19:39:54.013Z",
4
    "apresentacao": "2020-04-01T18:00:00Z",
5
    "expiracao": 3600
6
  },
7
  "txid": "fc9a4366ff3d4964b5dbc6c91a8722d3",
8
  "revisao": 3,
9
  "status": "ATIVA",
10
  "valor": {
11
    "original": "500.00",
12
    "modalidadeAlteracao": 0
13
  },
14
  "chave": "7407c9c8-f78b-11ea-adc1-0242ac120002",
15
  "solicitacaoPagador": "Informar cartao fidelidade",
16
  "infoAdicionais": [
17
    {
18
      "nome": "quantidade",
19
      "valor": "2"
20
    }
21
  ]
22
}

200

Exemplos válidos:

Exemplos inválidos:

400Requisição com formato inválido.

404Recurso solicitado não foi encontrado.

503Serviço não está disponível no momento. Serviço solicitado pode estar em manutenção ou fora da janela de funcionamento.