Vamos analisar de que forma é possível criar referências Multibanco e como ter acesso às notificações de pagamentos por Multibanco, usando o serviço da Easypay.

Para este efeito vamos ter em conta as configurações apresentadas no artigo anterior, esta package, que serve de wrapper para efetuar as chamadas à API da Easypay.

Além disto, podes acompanhar a “documentação” oficial e este repositório que criei e que contém os exemplos de código completos.

Sem mais demoras, o artigo está dividido em quatro pontos:

  1. Fluxo de pagamento e estrutura de dados
  2. Criação da referência Multibanco
  3. Notificação de pagamento em tempo real
  4. Notificação de pagamento assíncrona

1. Fluxo de pagamento e estrutura de dados

Uma das dificuldades que tive quando fiz a integração, foi “visualizar” o esquema de dados e que informação guardar. Por isso, além de apresentar a forma como é feita a integração, apresentarei também a estrutura e a lógica do sistema que desenvolvi (e que poderá ser diferente mediante os requisitos que tiveres).

No meu caso, a estrutura de dados da própria aplicação segue uma lógica semelhante a:

  • Tabela references: regista todos as “compras”. Terá sempre associada uma linha para cada referência criada (seja ela por multibanco ou débito direto)
  • Tabela payments: regista todas as tentativas de cobrança e e informação completa, quando o pagamento é feito com sucesso
  • Tabela payment_notifications: Regista todas as interações referentes a um determinado pagamento

O único motivo pelo qual tenho uma tabela “references” e uma “payments” tem a ver com o requisito do sistema que implementei. No meu caso, uma compra pode dar origem a diversos pagamentos (imagina o pagamento de uma subscrição, onde é paga uma fee mensalmente). Neste caso, a subscrição é apenas uma (portanto, a “compra”), mas existe um pagamento por mês associado a essa compra.

Acredito que o caso mais comum, em implementações que tenham apenas pagamentos por MB, é ter uma única tabela que guarda a referência MB e a informação da cobrança. Neste caso bastaria a tabela “payments” e outra para as notificações do pagamento.

Nos exemplos podes encontrar um exemplo do schema da base de dados.

O fluxo para pagamentos com referências Multibanco será sempre semelhante a:

  1. Registares internamente a “compra” *
  2. Criar a referência multibanco e apresentar essa informação ao cliente
  3. Aguardar pelo pagamento da referência e marcar o pagamento como concluído
  4. Marcares a compra como concluída *

O ponto 1 e 4 são específicos da tua aplicação. Nomeadamente o ponto 1 é obrigatório para conseguires fazer o relacionamento entre a compra no teu sistema e o pagamento.

2. Criação da referência Multibanco

Para criares a referência multibanco é necessário fazer uma chamada à API 01BG com os parâmetros corretos. Os parâmetros obrigatórios nesta API são:

  • ep_user: Identifica a conta de utilizador na Easypay.
    É o mesmo username que usas para aceder ao backoffice
  • ep_entity: Entidade associada à conta da Easypay, que pretendes usar para a referência.
    É sempre um número com cinco dígitos
  • ep_cin: CIN (Client Identification Number) para a referência.
    É sempre um número com seis dígitos e reflete sempre os primeiros 6 dígitos que a referencia terá (ex: 123 456 000)
  • t_value: Valor a cobrar ao cliente. Deves usar o “.” (ponto) como separador de casas decimais
  • t_key: O identificador da compra no teu sistema.
    Permite relacionar a compra do teu sistema com o pagamento da Easypay. Normalmente é um autoincrement da BD
  • ep_language: Preenchido por omissão pela package, terá o valor PT
  • ep_country: Preenchido por omissão pela package, terá o valor PT
  • ep_ref_type: Por alguma razão o campo é obrigatório mas o valor é sempre “auto”. É preenchido de forma automatica pela package

O parâmetro s_code é também obrigatório caso a autenticação seja feita por código e não por IP. Se a autenticação for feita por IP não deves enviar este parâmetro.

Opcionalmente podes enviar os seguintes parâmetros

  • o_name: Nome do cliente
  • o_description: Descrição para o pagamento (por ex, que produto foi comprado)
  • o_obs: Observações para o pagamento
  • o_mobile: N.º de telefone / telemóvel do cliente
  • o_email: Email do cliente

Tendo estes dados, basta criares uma instância da package que serve como wrapper, passares um array com os dados ou usares o método setValue(key, value) para definir os parâmetros.

Abaixo apresento o código essencial para a criação da referência, mas podes encontrar aqui o exemplo completo e funcional.

use Easypay\EasyPay;

// Os parâmetros `ep_language`, `ep_country` e `ep_ref_type` são definidos automaticamente pela package
$easypay = new EasyPay([
    'ep_user'   => 'YOUR_USER',
    'ep_entity' => '12345',
    'ep_cin'    => '123456',
    's_code'    => 'CODE_VALIDATION',
]);
// Defines o valor a pagar
$easypay->setValue('t_value', '50.00');

// Defines a chave que vai relacionar o pagamento com a compra do teu sistema
// Por norma este valor é um autoincrement da tabela onde registas a compra
$easypay->setValue('t_key', 12);

// Vamos enviar também os parâmetros opcionais
$easypay->setValue('o_name', 'John Doe');
$easypay->setValue('o_description', 'Purchase of amazing product');
$easypay->setValue('o_obs', 'Bought XPTO product on Nov 2017');
$easypay->setValue('o_mobile', '+351 123 456 789');
$easypay->setValue('o_email', 'email@example.com');

// Neste momento, basta chamar o método da package `createReference` com o parâmetro 'normal'
// A variável $result será um array com o conteúdo do XML de resposta da API.
$result = $easypay->createReference('normal');

A resposta ao request devolve sempre um XML com um ep_status que indica se o request foi efetuado com sucesso ou não e um ep_message correspondente. Se a chamada à API der algum erro, o XML será semelhante a:

<?xml version="1.0" encoding="ISO-8859-1"?>
<getautoMB>
    <ep_status>err1</ep_status>
    <ep_message>ep_country or ep_entity or ep_user or ep_cin not ok;</ep_message>
    <ep_cin>123456</ep_cin>
    <ep_user>YOUR_USER</ep_user>
    <ep_entity>00</ep_entity>
    <ep_reference>00</ep_reference>
    <ep_value>00</ep_value>
    <ep_key>00</ep_key>
    <ep_link></ep_link>
</getautoMB>

Nota que o “err1” no ep_status não é nenhum “typo”. Este é efetivamente o valor que vem na resposta.

Caso a referência seja criada com sucesso, então o XML de resposta será semelhante a:

<?xml version="1.0" encoding="ISO-8859-1"?>
<getautoMB>
    <ep_status>ok0</ep_status>
    <ep_message>ep_country and ep_entity and ep_user and ep_cin ok and validation by code;code ok - new reference generated - 123456789 - </ep_message>
    <ep_cin>123456</ep_cin>
    <ep_user>YOUR_USER</ep_user>
    <ep_entity>12345</ep_entity>
    <ep_reference>123456789</ep_reference>
    <ep_value>50.00</ep_value>
    <t_key>12</t_key>
    <ep_link>http://test.easypay.pt/_s/c11.php?e=12345&r=123456789&v=50.00&c=PT&l=PT&t_key=12</ep_link>
</getautoMB>

Neste momento tens acesso a todos os dados necessários para efetuar o pagamento, nomeadamente ep_entity, ep_reference e ep_value. Eventualmente deverás guardar esta informação na base de dados, apresentar os dados de pagamento ao utilizador e, se fizer sentido, enviar um email ao cliente com os dados para pagamento.

Notas importantes sobre o backoffice da Easypay:

  1. Podes ver todas as chamadas a APIs no backoffice através do menu Webservices » API Status

    Integração de pagamentos por MB com Easypay images/22-integracao-servico-pagamentos-easypay-multibanco-mb-atm/297-easypay-backoffice-webservices-api-status.jpg
  2. Sempre que uma referência é criada com sucesso, podes ter acesso a esse registo no backoffice em New Payment Identifier » Manual Generation

    Integração de pagamentos por MB com Easypay images/22-integracao-servico-pagamentos-easypay-multibanco-mb-atm/300-easypay-backoffice-new-payment-identifier-manual-generation.jpg

Em desenvolvimento, para poderes testar as notificações de pagamentos multibanco com sucesso, deves usar a coluna Test Multibanco Pay que existe na imagem acima. Ao clicares nesse botão, a Easypay “faz de conta” que a referência correspondente foi paga.

Após pagamento da referência existem duas formas de teres informação de que o pagamento foi efetuado com sucesso. Podes usar apenas uma ou ambas, mediante os requisitos da tua aplicação. Vamos ver estas formas de pagamento nos pontos seguintes.

3. Notificação de pagamento em tempo real

Este método permite que a tua aplicação seja notificada imediatamente após o pagamento. A “documentação” oficial indica que este método funciona para pagamentos por Multibanco, Transferência bancária e pagamentos por Cartão de Crédito. Apenas posso assegurar o funcionamento de pagamentos por MB, não tendo testado os restantes tipos de pagamentos.

Para que a tua aplicação possa ser notificada em tempo real, tens de configurar, no backoffice da Easypay, em Webservices » URL Configuration, o campo url notificação do(s) CIN(s) que estás a usar.

Integração de pagamentos por MB com Easypay images/22-integracao-servico-pagamentos-easypay-multibanco-mb-atm/298-easypay-backoffice-webservices-url-configuration-notifications.jpg

Neste campo deves colocar um endereço para o teu site / aplicação, que esteja preparado para receber e processar a notificação em tempo real. Quando a Easypay receber a indicação de pagamento por parte da entidade bancária, irá chamar o endereço que aí configuraste com um conjunto de parâmetros enviados por GET, nomeadamente ep_cin, ep_user e ep_doc. A chamada ao teu URL é semelhante a:

http://www.yoursite.com/your/notification_url.php?ep_cin=123456&ep_user=YOUR_USER&ep_doc=MBTEST0001234567890123456789

Como podes constatar, é enviado um ep_doc como identificador do pagamento, mas nunca no processo de criação da referência tens acesso a este valor. A única forma de identificar imediatamente o pagamento seria através do ep_reference ou t_key.

Para colmatar esta questão, vamos ter de consumir a API 03AG, que serve para devolver os dados completos referentes a um pagamento, que incluem os campos que já temos.

Além disto, como indica a documentação oficial, tens de devolver um XML como resposta à chamada da Easypay, que contém um parâmetro chamado ep_key. Este parâmetro serve para identificar o pagamento concreto (não confundir com o t_key, que identifica a “compra”), pelo que se não tens este valor criado, terás também de o criar neste processo.

No fundo, este processo de notificação terá de incluir várias partes, nomeadamente:

  1. Chamada à API 03AG para obteres a informação completa do pagamento
  2. Criação do ep_key
  3. Criação de XML de resposta para a Easypay

Poderão existir ainda outros processos específicos à tua aplicação, como o registo do pagamento na BD ou algum envio de email para o cliente final.

Mais abaixo colocamos o código de exemplo, mas podes encontrar aqui o código completo e funcional. Para já, importa perceber qual o conteúdo do XML da resposta da API 03AG.

<?xml version="1.0" encoding="ISO-8859-1"?>
<getautoMB_detail>
    <ep_status>ok0</ep_status>
    <ep_message>ep_country and ep_entity and ep_user and ep_cin ok and validation by code;code ok - doc MBTEST0001234567890123456789 and key  ok;</ep_message>
    <ep_cin>123456</ep_cin>
    <ep_user>YOUR_USER</ep_user>
    <ep_key></ep_key>
    <t_key>12</t_key>
    <ep_doc>MBTEST0001234567890123456789</ep_doc>
    <ep_payment_type>MB</ep_payment_type>
    <ep_entity>12345</ep_entity>
    <ep_reference>123456789</ep_reference>
    <ep_value>50</ep_value>
    <ep_value_fixed>0.35</ep_value_fixed>
    <ep_value_var>0.9</ep_value_var>
    <ep_value_tax>0.2625</ep_value_tax>
    <ep_value_transf>48.4875</ep_value_transf>
    <ep_date_transf>2017-11-03</ep_date_transf>
    <ep_date_read>2017-10-31 19:49:30</ep_date_read>
    <ep_status_read>verified</ep_status_read>
    <o_key>12</o_key>
    <o_obs><![CDATA[Purchase of amazing product]]></o_obs>
    <o_email>email@example.com</o_email>
    <o_mobile>+351 123 456 78</o_mobile>
    <ep_date>2017-10-31 19:10:24</ep_date>
</getautoMB_detail>

Uma nota para o parâmetro ep_payment_type que podes usar para identificar o tipo de pagamento. Quando o pagamento é Multibanco, este parâmetro tem de vir preenchido com o valor “MB”.

Depois da chamada com sucesso e de teres acesso aos dados do pagamento, vais ter de criar o ep_key (número, auto increment) que identifica o pagamento e que tem de ser enviado no XML para a Easypay. Por norma este número resulta da inserção dos dados do pagamento numa tabela e consequente obtenção do identificador. No fundo, o ep_key servirá como chave primária de uma tabela.

Depois de criado o ep_key, podes criar o XML de resposta ao request da Easypay para o URL de notificação, que deve conter os seguintes dados:

<!--?xml version="1.0" encoding="ISO-8859-1"?-->
<getautomb_key>
    <ep_status>ok0</ep_status>
    <ep_message>generated document</ep_message>
    <ep_cin>123456</ep_cin>
    <ep_user>YOUR_USER</ep_user>
    <ep_doc>MBTEST0001234567890123456789</ep_doc>
    <ep_key>3</ep_key>
</getautomb_key>

O código para este processo, em termos reduzidos, é semelhante ao que é apresentado abaixo. Novamente reforço que o exemplo completo e funcional se encontra neste ficheiro.

// Vamos criar já o XML parcial, que terá de ser devolvido no final, com a informação que temos
$epCin = $_GET['ep_cin'];
$epUser = $_GET['ep_user'];
$epDoc = $_GET['ep_doc'];

$xml = new SimpleXMLElement('<getautoMB_key></getautoMB_key>');
$xml->addChild('ep_cin', $epCin);
$xml->addChild('ep_user', $epUser);
$xml->addChild('ep_doc', $epDoc);

// Agora temos de obter os dados completos do pagamento (marcado como step 4 na documentação)
$easypay = new Easypay\EasyPay([
    'ep_user'   => 'YOUR_USER',
    'ep_entity' => '12345',
    'ep_cin'    => '123456',
    's_code'    => 'CODE_VALIDATION',
]);
// Call API 03AG
$paymentInfo = $easypay->getPaymentInfo([
    'ep_cin'  => $epCin,
    'ep_user' => $epUser,
    'ep_doc'  => $epDoc,
]);

// Aqui terá de existir tratamento de erros, caso o request não seja bem sucedido

// Vamos abrir uma ligação ao MySQL, para podermos registar o pagamento e obter o ep_key
$conn = new PDO(
    'mysql:host=localhost;dbname=easypay_examples',
    'db_user',
    'db_pass'
);
$conn->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

// Estamos a assumir que a referência foi registada na tabela easypay_references,
// no momento da criação (passo 1 deste artigo)
$stmt = $conn->prepare('SELECT * FROM easypay_references WHERE ep_reference = :ep_reference');
$stmt->execute([':ep_reference' => $paymentInfo['ep_reference']]);
$easypayReference = $stmt->fetch();

// Tendo acesso ao registo da easypay_reference, podemos criar um novo registo na easypay_payments.
// Após o registo ser guardado será criado o ep_key, que iremos usar no XML
$stmt = $conn->prepare("
    INSERT INTO easypay_payments (easypay_reference_id, ep_doc, ep_cin, ep_user, ep_status, ep_message,
        ep_entity, ep_reference, ep_value, ep_date, ep_payment_type, ep_value_fixed, ep_value_var,
        ep_value_tax, ep_value_transf, ep_date_transf, t_key)
    VALUES (:easypay_reference_id, :ep_doc, :ep_cin, :ep_user, :ep_status, :ep_message, :ep_entity,
        :ep_reference, :ep_value, :ep_date, :ep_payment_type, :ep_value_fixed, :ep_value_var,
        :ep_value_tax, :ep_value_transf, :ep_date_transf, :t_key)
");
$stmt->execute([
    ':easypay_reference_id' => $easypayReference['id'],
    ':ep_doc' => $epDoc,
    ':ep_cin' => $epCin,
    ':ep_user' => $epUser,
    ':ep_status' => $paymentInfo['ep_status'],
    ':ep_message' => $paymentInfo['ep_message'],
    ':ep_entity' => $paymentInfo['ep_entity'],
    ':ep_reference' => $paymentInfo['ep_reference'],
    ':ep_value' => $paymentInfo['ep_value'],
    ':ep_date' => $paymentInfo['ep_date'],
    ':ep_payment_type' => $paymentInfo['ep_payment_type'],
    ':ep_value_fixed' => $paymentInfo['ep_value_fixed'],
    ':ep_value_var' => $paymentInfo['ep_value_var'],
    ':ep_value_tax' => $paymentInfo['ep_value_tax'],
    ':ep_value_transf' => $paymentInfo['ep_value_transf'],
    ':ep_date_transf' => $paymentInfo['ep_date_transf'],
    ':t_key' => $paymentInfo['t_key'],
]);
// Vamos buscar o ep_key
$epKey = $conn->lastInsertId();

// Adicionamos o ep_key ao XML
$xml->addChild('ep_key', $epKey);

// Adicionamos o estado e a mensagem ao XML
$xml->addChild('ep_status', 'ok0');
$xml->addChild('ep_message', 'generated document');

// Devolvemos o XML à Easypay com a informação completa
header("content-type: text/xml; charset=utf-8");
echo $xml->saveXML();

4. Notificação de pagamento assíncrona

Se não for importante teres as notificações em tempo real, podes implementar a API 040BG1 que devolve informação sobre todos os pagamentos efetuados num determinado período.

Esta API recebe os parâmetros ep_cin, ep_user e ep_entity. Opcionalmente tens de enviar o parâmetro s_code, caso a autenticação seja feita por código. Ao chamares esta API com os parâmetros “mínimos”, são devolvidos os 10 pagamentos mais recentes.

Para testares a API, podes fazer a chamada diretamente através do browser ou do Postman e o URL será semelhante a:

http://test.easypay.pt/_s/api_easypay_040BG1.php?ep_user=YOUR_USER&s_code=VALIDATION_CODE&ep_cin=123456&ep_entity=12345

Para obteres a lista de pagamentos de um determinado período deves enviar os parâmetros o_list_type, o_ini e o_last, sendo estes dois últimos parâmetros preenchidos com valores distintos, mediante o valor que colocas no o_list_type.

Como exemplo, se quiseres obter os últimos 100 pagamentos, deves passar o o_list_type com o valor “last” e colocares o _oini com o valor do n.º de pagamentos que pretendes.

http://test.easypay.pt/_s/api_easypay_040BG1.php?ep_user=YOUR_USER&s_code=VALIDATION_CODE&ep_cin=123456&ep_entity=12345&o_list_type=last&o_ini=100

Se pretenderes, por exemplo, obter todos os pagamentos efetuados no dia 01-11-2017, deverás passar no o_list_type o valor “date” e nos parâmetros o_ini e o_last o valor “2017-11-01”. O URL ficará assim:

http://test.easypay.pt/_s/api_easypay_040BG1.php?ep_user=YOUR_USER&s_code=VALIDATION_CODE&ep_cin=123456&ep_entity=12345&o_list_type=date&o_ini=2017-11-01&o_last=2017-11-01

Ao contrário do método de notificações em tempo real, esta API devolve todos os dados de cada pagamento, não sendo necessário chamares a API 03AG.

Esta API (040BG1) devolve um XML semelhante a

<?xml version="1.0"?>
<get_ref>
    <ep_status>ok0</ep_status>
    <ep_message>ep_country and ep_entity and ep_user and ep_cin ok and validation by code;code ok - query with 2 records</ep_message>
    <ep_num_records>2</ep_num_records>
    <ref_detail>
        <ref>
            <ep_cin>123456</ep_cin>
            <ep_user>YOUR_USER</ep_user>
            <ep_entity>12345</ep_entity>
            <ep_reference>123456789</ep_reference>
            <ep_value>50</ep_value>
            <ep_key>51</ep_key>
            <t_key>7</t_key>
            <ep_doc>MBTEST1234567891234567891234</ep_doc>
            <ep_payment_type>MB</ep_payment_type>
            <ep_value_fixed>0.35</ep_value_fixed>
            <ep_value_var>0.9</ep_value_var>
            <ep_value_tax>0.2625</ep_value_tax>
            <ep_value_transf>48.4875</ep_value_transf>
            <ep_date_transf>2017-11-04</ep_date_transf>
            <ep_key_read>51</ep_key_read>
            <ep_date_read>2017-11-01 12:00:00</ep_date_read>
            <ep_status_read>verified</ep_status_read>
            <ep_status>pago</ep_status>
            <ep_batch_transf></ep_batch_transf>
            <ep_invoice_number></ep_invoice_number>
            <ep_payment_date>2017-11-01 12:00:00</ep_payment_date>
        </ref>
        <ref>
            <ep_cin>123456</ep_cin>
            <ep_user>YOUR_USER</ep_user>
            <ep_entity>12345</ep_entity>
            <ep_reference>123456788</ep_reference>
            <ep_value>50</ep_value>
            <ep_key>50</ep_key>
            <t_key>12</t_key>
            <ep_doc>MBTEST9632587410012354698714</ep_doc>
            <ep_payment_type>MB</ep_payment_type>
            <ep_value_fixed>0.35</ep_value_fixed>
            <ep_value_var>0.9</ep_value_var>
            <ep_value_tax>0.2625</ep_value_tax>
            <ep_value_transf>48.4875</ep_value_transf>
            <ep_date_transf>2017-11-03</ep_date_transf>
            <ep_key_read>50</ep_key_read>
            <ep_date_read>2017-11-01 15:30:00</ep_date_read>
            <ep_status_read>verified</ep_status_read>
            <ep_status>pago</ep_status>
            <ep_batch_transf></ep_batch_transf>
            <ep_invoice_number></ep_invoice_number>
            <ep_payment_date>2017-10-31 18:15:30</ep_payment_date>
        </ref>
    </ref_detail>
</get_ref>

Neste tipo de notificação, deves ter algum tipo de cronjob ou tarefa agendada que seja executada num intervalo de tempo e que chame esta API. Sempre que te sejam devolvidos resultados, deves procurar pelo identificador do pagamento (o ep_reference, por exemplo) e atualizar a tua base de dados.

Mediante os valores dos parâmetros que envias para a API, podes estar a receber o mesmo pagamento várias vezes, pelo que deve precaver este tipo de situações (não vale a pena processar mais que uma vez o mesmo pagamento). Além disto, neste tipo de notificações, também ao contrário do método de tempo real, não é necessário devolveres dados à Easypay.

Uma nota importante sobre esta API: quando não existem resultados, a API devolve o ep_status com “err1” (???!!), como demonstro abaixo. Eventualmente será boa ideia preveres esta situação no tratamento de erros da tua aplicação.

<?xml version="1.0" encoding="ISO-8859-1"?>
<get_ref>
    <ep_status>err1</ep_status>
    <ep_message>ep_country and ep_entity and ep_user and ep_cin ok and validation by code;code ok - query with no records</ep_message>
</get_ref>

O código completo e funcional que demonstra este método está neste ficheiro e abaixo apresento o código mais relevante.

$easypay = new Easypay\EasyPay([
    'ep_user'   => 'YOUR_USER',
    'ep_entity' => '12345',
    'ep_cin'    => '123456',
    's_code'    => 'CODE_VALIDATION',
]);

// Chama a API com os parâmetros que entendemos
$payments = $easypay->fetchAllPayments([
    'o_list_type' => 'date',
    'o_ini'       => '2017-11-04',
    'o_last'      => '2017-11-04',
], true);

// Trata o "erro" que é não existirem resultados ... ...
if ($payments['ep_status'] === 'err1'
    && strpos($payments['ep_message'], ' - query with no records') !== false
    ) {
    var_dump($easypay->getLogs());
    // There are no payments for the request
    echo 'no results';
    die();
}

// Temos algum erro real?
if ($payments['ep_status'] === 'err1') {
    var_dump($paymentInfo);
    throw new Exception('Something went wrong fetching payments');
}

foreach ($payments['ref_detail'] as $payment) {
    // Para este caso apenas interessam pagamentos por MB
    if ($payment['ep_payment_type'] !== 'MB') {
        continue;
    }

    // Vamos procurar a referência que deu origem a este pagamento
    $stmt = $conn->prepare('SELECT * FROM easypay_references WHERE ep_reference = :ep_reference');
    $stmt->execute([':ep_reference' => $payment['ep_reference']]);
    $easypayReference = $stmt->fetch();

    // Se não existe registo no nosso sistema, avança. NOTA IMPORTANTE:
    // Por vezes as pessoas enganam-se a pagar e trocam um número da referência, por ex, e
    // o teu sistema está a processar um pagamento que não é devido. Daí a proteção
    if (!is_array($easypayReference) || empty($easypayReference)) {
        continue;
    }

    // Agora que garantimos que esta notificação é referente ao nosso sistema, vamos criar o registo na
    // easypay_payments. Depois disto, faz o que a tua aplicação precisa (enviar emails, enviar encomenda,
    // ativar algum plano, etc).
    $stmt = $conn->prepare("
        INSERT INTO easypay_payments (easypay_reference_id, ep_doc, ep_cin, ep_user, ep_status, ep_message,
            ep_entity, ep_reference, ep_value, ep_date, ep_payment_type, ep_value_fixed,
            ep_value_var, ep_value_tax, ep_value_transf, ep_date_transf, t_key)
        VALUES (:easypay_reference_id, :ep_doc, :ep_cin, :ep_user, :ep_status, :ep_message,
            :ep_entity, :ep_reference, :ep_value, :ep_date, :ep_payment_type, :ep_value_fixed,
            :ep_value_var, :ep_value_tax, :ep_value_transf, :ep_date_transf, :t_key)
    ");
    $stmt->execute([
        ':easypay_reference_id' => $easypayReference['id'],
        ':ep_doc' => $payment['ep_doc'],
        ':ep_cin' => $payment['ep_cin'],
        ':ep_user' => $payment['ep_user'],
        ':ep_status' => $payment['ep_status'],
        ':ep_message' => $payment['ep_message'],
        ':ep_entity' => $payment['ep_entity'],
        ':ep_reference' => $payment['ep_reference'],
        ':ep_value' => $payment['ep_value'],
        ':ep_date' => $payment['ep_date'],
        ':ep_payment_type' => $payment['ep_payment_type'],
        ':ep_value_fixed' => $payment['ep_value_fixed'],
        ':ep_value_var' => $payment['ep_value_var'],
        ':ep_value_tax' => $payment['ep_value_tax'],
        ':ep_value_transf' => $payment['ep_value_transf'],
        ':ep_date_transf' => $payment['ep_date_transf'],
        ':t_key' => $payment['t_key'],
    ]);
}

E é isto. No próximo artigo falaremos de Débitos Diretos, onde o processo é bastante mais complexo.

Este artigo faz parte da série Como integrar pagamentos com a Easypay

  1. Introdução à integração de pagamentos MB e DD com Easypay
  2. Integração de pagamentos por Débito Direto com Easypay (em breve)

Imagem do artigo retirada de Freepik: Background vector created by Photoroyalty - Freepik.com