Pagamento - Documentação

Introdução

Introdução da doc

A PAGAMENTO.AO Surgiu para facilitar as empresas/entidades a receberem pagamentos online de forma simples e segura.

Moedas Suportadas

As moedas suportadas pelo Pagamento são fornecidas abaixo.

Moeda Simbolo/Reg
KZ AOA

API KEY

Obtenha a sua chave de API

Para obter a sua api key, deverá logar na sua conta de comerciante Aqui, caso não tenha uma conta de comecerciante por-favor entre em contacto com [email protected]

Gerar Pagamento

Nesta secção iremos explicar como gerar um pagamento

Para iniciar o processo de pagamento, use o código de amostra fornecido e preste muita atenção aos parâmetros. Os endpoints da API mencionados abaixo precisarão ser usados para fazer a solicitação.

EndPoint de Produção: https://pagamento.ao/payment/initiate

EndPoint de Qualidade: https://pagamento.ao/test/payment/initiate

Solicitação para o EndPoint com os seguintes parâmetros abaixo.

Parametro Tipo Desc
public_key string (50) Obrigatorio Your Public API key
identifier string (20) Obrigatorio Identifier is basically for identify payment at your end
currency string (4) Obrigatorio Currency Code, Must be in Upper Case. e.g. USD,EUR
amount decimal Obrigatorio Payment amount
details string (100) Obrigatorio Details of your payment or transaction
ipn_url string Obrigatorio The url of instant payment notification
success_url string Obrigatorio Payment success redirect url
cancel_url string Obrigatorio Payment cancel redirect url
site_name string Obrigatorio Your business site name
site_logo string/url Opcional Your business site logo
checkout_theme string Opcional Checkout form theme dark/light. Default theme is light
Customer
customer[] array Obrigatorio customer must be an array
customer.first_name string Obrigatorio Customer's first name
customer.last_name string Obrigatorio Customer's last name
customer.email string Obrigatorio Customer's valid email
customer.mobile string Obrigatorio Customer's valid mobile
Shipping info
shipping_info[] array Opcional shipping_info must be an array
shipping_info.address_one string Opcional Customer's address one
shipping_info.address_two string Opcional Customer's address two
shipping_info.area string Opcional Shipping area of customer
shipping_info.city string Opcional Shipping city of customer
shipping_info.sub_city string Opcional Shipping sub city of customer
shipping_info.state string Opcional Shipping state
shipping_info.postcode string Opcional Shipping postcode
shipping_info.country string Opcional Shipping country
shipping_info.others string Opcional Others info
Billing info
billing_info[] array Opcional billing_info must be an array
billing_info.address_one string Opcional Customer's address one
billing_info.address_two string Opcional Customer's address two
billing_info.area string Opcional Billing area of customer
billing_info.city string Opcional Billing city of customer
billing_info.sub_city string Opcional Billing sub city of customer
billing_info.state string Opcional Billing state
billing_info.postcode string Opcional Billing postcode
billing_info.country string Opcional Billing country
billing_info.others string Opcional Others info
Example PHP code
<?php
     $parameters = [
        'identifier' => 'AO001',
        'currency' => 'kz',
        'amount' => 5000,
        'gateway_methods' => [
            "MulticaixaExpress"
        ],
        'details' => 'Capa de telefone',
        'ipn_url' => 'https://seusite.com/callback.php',
        'cancel_url' => 'https://seusite.com/pedido-cancelado.php',
        'success_url' => 'https://seusite.com/pagamento-bem-sucedido.php',
        'public_key' => 'sua-chave-publica',
        'site_name' => 'Minha loja',
        'site_logo' => 'https://seusite.com/logo.png',
        'checkout_theme' => 'light',
        'customer'=>[
            'first_name'=>'Edgar',
            'last_name'=>'Singui',
            'email'=>'[email protected]',
            'mobile'=>'923000000',
        ],
        'shipping_info'=>[
            'address_one'=>'',
            'address_two'=>'',
            'area'=>'',
            'city'=>'',
            'sub_city'=>'',
            'state'=>'',
            'postcode'=>'',
            'country'=>'',
            'others'=>'',
        ],
        'billing_info'=>[
            'address_one'=>'',
            'address_two'=>'',
            'area'=>'',
            'city'=>'',
            'sub_city'=>'',
            'state'=>'',
            'postcode'=>'',
            'country'=>'',
            'others'=>'',
        ]
    ];

    $parameters = http_build_query($parameters);

    // producao
    $url = 'https://pagamento.ao/payment/initiate';

    // qualidade
    $url = 'https://pagamento.ao/test/payment/initiate';

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

?>
Example Responses
// Em caso de erro
{
    "status": "error",
    "message": [
        "Invalid api key"
    ]
}

// Em caso de sucesso
{
    "status": "success",
    "message": [
        "Payment initiated"
    ],
    "redirect_url": "https://example.com/payment/checkout?payment_trx=eyJpdiI6IkFyNllSNU1lOFdkYTlPTW52cytPNGc9PSIsInZhbHVlIjoiWWowRTRjdzZ1S1BBRm4ydS81OWR1WjdXeFIxcjE1WkZRVE9BcmZYeXpzND0iLCJtYWMiOiJjNDdhODUzYzY2NmZlZGJjZTI5ODQyMmRkYzdjYjRmM2NiNjg4M2RiMWZjN2EyMzFkODI4OWMwYjk3ZWYwNGQwIiwidGFnIjoiIn0%3D"
}

Validar um pagamento

Como validar um pagamento ?

Antes de tudo para validar um pagamento deve certificar-se que definiu a ipn url, nada mais nada menos do que o callback ou a url que a PAGAMENTO.AO deve notificar se um pagmaento for recebido.

Sempre que um pagamento for processado pela PAGAMENTO.AO, o seu sistema receberá um json contendo informaçõs do pagamento com o valor pago e a currency, seu sistema além disso irá receber tambêm o status, a signature e o identifier passado por si ao gerar o pagamento

Para confirmar que a notificação de pagamneto recebida em seu sistema foi origiada pela PAGAMENTO.AO deverá comprar a assinatura recebida com a assinatura gerada pelo seu sistema. Atenção que deverá definir correctamente a url de callback pois a PAGAMENTO.AO não irá identificar quando foi definida uma url quebrada ou algo parecido isso está na responsablidade de quem for fazer a integração.

Verbo: POST

Veja mais detalhes.

Parametro Desc
status Payment success status.
identifier Identifier is basically for identify payment at your end.
signature A hash signature to verify your payment at your end.
data Data contains some basic information with charges, amount, currency, payment transaction id etc.
Example PHP code
<?php
    //Receive the response parameter
    $status = $_POST['status'];
    $signature = $_POST['signature'];
    $identifier = $_POST['identifier'];
    $data = $_POST['data'];

    // Generate your signature
    $customKey = $data['amount'].$identifier;
    $secret = 'YOUR_SECRET_KEY';
    $mySignature = strtoupper(hash_hmac('sha256', $customKey , $secret));

    $myIdentifier = 'YOUR_GIVEN_IDENTIFIER';

    if($status == "success" && $signature == $mySignature &&  $identifier ==  $myIdentifier){
        //your operation logic
    }
?>