Billing (3DS Support)

O helper Billing normaliza os dados opcionais de faturação para uma compra. Para não enviar billing, passe [] explicitamente em preparePurchase($amount, []).

Ele cobre:

• campos obrigatórios de faturação;
• endereço de entrega;
• telefones;
• identificação e histórico da conta;
• indicação de atividade suspeita;
• correspondência entre endereço de faturação e entrega.

---

Exemplo rápido com Billing::from()

Use from() quando os dados já estão num array:

use Erilshk\Sisp\Billing;

$billing = Billing::from([
    'email' => 'user@mail.com',
    'country' => '132',
    'city' => 'Praia',
    'address' => 'Achada Santo António',
    'postalCode' => '7600',
    'mobilePhone' => '9911122',
]);

O objeto pode ser enviado diretamente:

$vinti4->preparePurchase(1500, $billing);

Para obter o array normalizado:

$data = $billing->toArray();

Exemplo completo com chaining

$billing = Billing::make()
    ->email('user@mail.com')
    ->country('132')
    ->city('Praia')
    ->address('Achada Santo António')
    ->address2('Bloco B, Apt 10')
    ->address3('Próximo ao mercado')
    ->postalCode('7600')
    ->state('01')
    ->shipCountry('132')
    ->shipAddress('Rua de Entrega, 45')
    ->shipCity('Praia')
    ->shipPostalCode('7601')
    ->shipState('01')
    ->mobilePhone('238', '9911122')
    ->workPhone('238', '2612345')
    ->accountId('123456')
    ->accountInfo([
        'chAccAgeInd' => '05',
        'chAccChange' => '20230101',
        'chAccDate' => '20220101',
        'chAccPwChange' => '20230201',
        'chAccPwChangeInd' => '05',
        'suspiciousAccActivity' => '01',
    ])
    ->addressMatchesShipping(false)
    ->suspicious(false);

make() é indicado quando os dados são adicionados de forma gradual. toArray() remove campos vazios.

---

Campos obrigatórios

Campo SISP	Nome amigável	Tipo	Descrição
email	email	string	E-mail do titular
billAddrCountry	country	string	País em código numérico, como 132
billAddrCity	city	string	Cidade de faturação
billAddrLine1	address	string	Endereço principal
billAddrPostCode	postalCode	string	Código postal

billAddrCountry usa 132 por padrão. Se informar billing, forneça email, cidade, morada e código postal. Para não enviar dados 3DS adicionais, passe [] em preparePurchase().

Campos opcionais de faturação

Campo SISP	Nome amigável	Método
billAddrLine2	address2	address2()
billAddrLine3	address3	address3()
billAddrState	state	state()

Endereço de entrega

Campo SISP	Nome amigável	Método
shipAddrCountry	shipCountry	shipCountry()
shipAddrCity	shipCity	shipCity()
shipAddrLine1	shipAddress	shipAddress()
shipAddrPostCode	shipPostalCode	shipPostalCode()
shipAddrState	shipState	shipState()

Use addressMatchesShipping(true) quando o endereço de entrega corresponde ao endereço de faturação. O valor enviado será Y; para false, será N.

---

Telefones

$billing
    ->mobilePhone('238', '9911122')
    ->workPhone('238', '2612345');

A estrutura final é:

[
    'cc' => '238',
    'subscriber' => '9911122',
]

Ao usar Billing::from(), também pode passar apenas o número. Nesse caso, a biblioteca usa 238 como código padrão.

Billing::from([
    'phone' => '9911122',
    // Ou: 'mobilePhone' => ['cc' => '238', 'subscriber' => '9911122'],
]);

Para +2389911122 ou números de outros países, informe cc e subscriber separadamente. A classe retira caracteres não numéricos, mas não interpreta automaticamente um prefixo internacional; +2389911122 passado como uma string inteira duplicaria o indicativo.

---

Dados da conta

acctID

Identifica a conta do cliente no sistema do comerciante:

$billing->accountId('CLIENTE-123');

O limite validado pela requisição é 64 caracteres.

acctInfo

$billing->accountInfo([
    'chAccAgeInd' => '05',
    'chAccDate' => '20220101',
    'chAccChange' => '20230101',
    'chAccPwChange' => '20230201',
    'chAccPwChangeInd' => '05',
]);

Quando não informados, chAccAgeInd, chAccPwChangeInd e suspiciousAccActivity recebem valores padrão.

As datas de acctInfo são enviadas como fornecidas; use o formato YYYYMMDD. created_at e updated_at não são aliases de Billing::from() e serão ignorados. Mapeie campos do seu $user explicitamente para as chaves SISP. fromUser() permanece apenas para compatibilidade.

Atividade suspeita

$billing->suspicious(true);

true define suspiciousAccActivity como 02; false define como 01.

---

Nomes amigáveis e nomes SISP

Billing::from() aceita os dois formatos:

Billing::from([
    'country' => '132',
    'billAddrCity' => 'Praia',
    'address' => 'Plateau',
    'billAddrPostCode' => '7600',
    'email' => 'user@mail.com',
]);

Campos desconhecidos são ignorados.

Um payload 3DS já no formato SISP também pode ser passado diretamente:

$billing = Billing::from([
    'email' => 'cliente@example.cv',
    'billAddrCountry' => '132',
    'billAddrCity' => 'Praia',
    'billAddrLine1' => 'Rua Principal, 1',
    'billAddrPostCode' => '7600',
    'addrMatch' => 'N',
    'mobilePhone' => ['cc' => '238', 'subscriber' => '9912345'],
    'acctInfo' => ['chAccDate' => '20220328'],
]);

Para dados da sua aplicação, faça o mapeamento com nomes explícitos:

$billing = Billing::from([
    'email' => $user['email'],
    'city' => $user['city'],
    'address' => $user['address'],
    'postalCode' => $user['postal_code'],
    'accountId' => (string) $user['id'],
    'mobilePhone' => ['cc' => '238', 'subscriber' => $user['phone']],
]);

Nesse exemplo, $user['phone'] deve conter o número local, sem +238. O Billing não garante que os valores recebidos correspondem a um telefone, país ou endereço válidos: essa verificação pertence à aplicação.

---