07. Classe Payload

A classe Payload é a classe principal dos códigos Pix desta biblioteca. A partir dela, é possível criar um código Pix e gerar um QR Code compatível. A partir da versão 1.2.0 desta biblioteca, a classe foi dividida em duas classes, são elas:

• StaticPayload para criação de um código Pix estático;
• DynamicPayload para criação de um código Pix dinâmico;

Para compatibilidade com versões anteriores a 1.2.0, a classe Payload ainda pode ser instanciada e adotará o comportamento padrão da StaticPayload, sendo assim um código Pix estático.

Definições

Os atributos obrigatórios do Pix são:

• Pix Key alterado pelo método setPixKey() com o tipo Parser::KEY_TYPE_* e o valor da chave Pix;
• Merchant Name alterado pelo método setMerchantName() com o nome do titular da conta como consta na instituição bancária.
• Merchant City alterado pelo método setMerchantCity() com a cidade da agência da conta como consta na instituição bancária.

Os atributos opcionais do Pix são:

• Point of Initiation Method alterado pelo método setAsReusable() sendo true como código Pix reutilizável e false como código Pix utilizável apenas uma vez. Para utilizar true deve-se haver um PSP autorizado para controlar os QR Code Dinâmicos. Ainda não implementamos conexões com APIs de PSPs.
• Merchant Account Information . Label alterado pelo método setDescription() com a descrição do pagamento. Tamanho máximo de 36 caracteres.
• Transaction Amount alterado pelo método setAmount() com o valor da transação em float. Tamanho máximo de 13 caracteres.
• Additional Data Field . Reference Label alterado pelo método setTid() com o ID da transação. Tamanho máximo de 25 caracteres.

Constantes

Utilize as constantes Payload::OUTPUT_* para definir o tipo de saída do QR Code Pix. As constantes disponíveis são:

Constante	Valor	Descrição
Payload::OUTPUT_SVG	svg	A saída do QR Code será em base64 svg.
Payload::OUTPUT_PNG	png	A saída do QR Code será em base64 png.

Utilize as constantes Payload::ECC_* para a correção de erro QR Code Pix. Isso permite qual a porcentagem de dano que um QR Code pode ter para continuar sendo lido. As constantes disponíveis são:

Constante	Valor	Descrição
Payload::ECC_L	0b01	7% de perda no QR Code.
Payload::ECC_M	0b00	15% de perda no QR Code.
Payload::ECC_Q	0b11	25% de perda no QR Code.
Payload::ECC_H	0b10	35% de perda no QR Code.

Modificadores

A classe Payload apresenta alguns modificadores de dados que podem ser aplicados a qualquer momento antes de gerar o código Pix ou QR Code. São eles:

• applyEmailWhitespace() (indicado para Bancos/PSPs com versões Pix inferiores a 2.2) irá substituir o caractere @ na chave de e-mail pelo caractere (espaço). Esse modificador é aplicado apenas as chaves de e-mail;
• applyValidCharacters() (alguns Bancos/PSPs não leem acentuações no Pix) determina a substituição dos acentos e demais caracteres inválidos como [\!\.\,\@\#\$\%\&\*\(\)\/\*\?]. Esse modificador é aplicado nos campos description, merchantName e merchantCity;
• applyUppercase() transforma todos os caracteres em maiúsculo. Esse modificador é aplicado nos campos description, merchantName e merchantCity.

Métodos

Set

• setPixKey() informa a chave Pix. Esse método é desabilitado na classe DynamicPayload;
• setDescription() informa a descrição do Pix. Esse método é desabilitado na classe DynamicPayload;
• setMerchantName() informa o titular da conta Pix;
• setMerchantCity() informa a cidade do titular da conta Pix;
• setAmount() informa o valor do pagamento Pix;
• setAsReusable() não é recomendado utilizar esse método, ele define se o QR Code é estático ou dinâmico. Ao invés disso, utilize as classes StaticPayload (sempre será true) ou DynamicPayload (sempre será false);
• setPayloadUrl() informa a URL do SPI. Esse método é disponível somente na classe DynamicPayload;

Ao criar e gerar códigos Pix é possível que as seguintes exceções possam ocorrer:

• InvalidPixKeyTypeException caso o tipo da chave Pix seja inválido;
• InvalidPixKeyException caso a chave Pix seja inválida;
• InvalidEmvFieldException caso um campo preenchido seja inválido;
• EmvIdIsRequiredException caso um campo obrigatório não seja preenchido;

Get

• getTid() obtém o ID da transação do Pix atual;
• getPixCode() retorna o código Pix em string;
• getQRCode() retorna uma string formatada em base64. A saída pode ser controlada com os valores Payload::OUTPUT_* para o formato de saída do QR Code e, também, os valores Payload::ECC_* para controlar as porcentagens de perca de dados do QR Code.

Classe DynamicPayload

Para o Pix estático (StaticPayload) não existe segredo. Já para o DynamicPayload é obrigatório uma URL gerada pelo Banco/PSP que conterá as informações detalhadas da cobrança Pix. Para isso é necessário que, antes de criar o código Pix, você tenha obtido a URL do Pix dinâmico, do contrário, o DynamicPayload não será um pix válido.

Exemplo

use Piggly\Pix\DynamicPayload;
use Piggly\Pix\Exceptions\EmvIdIsRequiredException;
use Piggly\Pix\Exceptions\InvalidEmvFieldException;
use Piggly\Pix\Exceptions\InvalidPixKeyException;
use Piggly\Pix\Exceptions\InvalidPixKeyTypeException;
use Piggly\Pix\StaticPayload;

try
{
	// Pix estático
	// Obtém os dados pix do usuário
	// -> Dados obrigatórios
	$keyType  = filter_input( INPUT_POST, 'keyType', FILTER_SANITIZE_STRING);
	$keyValue = filter_input( INPUT_POST, 'keyValue', FILTER_SANITIZE_STRING);
	$merchantName = filter_input( INPUT_POST, 'merchantName', FILTER_SANITIZE_STRING);
	$merchantCity = filter_input( INPUT_POST, 'merchantCity', FILTER_SANITIZE_STRING);

	// -> Dados opcionais
	$amount = filter_input( INPUT_POST, 'amount', FILTER_SANITIZE_STRING);
	$tid = filter_input( INPUT_POST, 'tid', FILTER_SANITIZE_STRING);
	$description = filter_input( INPUT_POST, 'description', FILTER_SANITIZE_STRING);

	$payload = 
		(new StaticPayload())
			// ->applyValidCharacters()
			// ->applyUppercase()
			// ->applyEmailWhitespace()
			->setPixKey($keyType, $keyValue)
			->setMerchantName($merchantName)
			->setMerchantCity($merchantCity)
			->setAmount($amount)
			->setTid($tid)
			->setDescription($description);

			
	// Pix dinâmico
	// Obtém os dados pix do usuário
	// -> Dados obrigatórios
	$merchantName = filter_input( INPUT_POST, 'merchantName', FILTER_SANITIZE_STRING);
	$merchantCity = filter_input( INPUT_POST, 'merchantCity', FILTER_SANITIZE_STRING);

	// Obtém os dados do SPI para o Pix
	$payload = 
	(new DynamicPayload())
		->setPayloadUrl($spiUrl) // URL do Pix no SPI
		->setMerchantName($merchantName)
		->setMerchantCity($merchantCity);
		
	// Continue o código

	// Código pix
	echo $pix->getPixCode();
	// QR Code
	echo '<img style="margin:12px auto" src="'.$pix->getQRCode().'" alt="QR Code de Pagamento" />';
}
catch ( InvalidPixKeyException $e )
{ /** Retorna que a chave pix está inválida. */ }
catch ( InvalidPixKeyTypeException $e )
{ /** Retorna que a chave pix está inválida. */ }
catch ( InvalidEmvFieldException $e )
{ /** Retorna que algum campo está inválido. */ }
catch ( EmvIdIsRequiredException $e )
{ /** Retorna que um campo obrigatório não foi preenchido. */ }