IMaliWay Gateway API

A API IMaliWay é organizada em torno de REST. Aceita corpos de pedido em JSON, devolve respostas em JSON e utiliza códigos de resposta HTTP padrão. Integre pagamentos M-Pesa, e-Mola, mKesh e iMali na sua aplicação em minutos.

Métodos de Pagamento Disponíveis

M-Pesa

e-Mola

mKesh

iMali

Fluxos de Pagamento

01

Push Payment

Cria uma transação e envia notificação push ao cliente para confirmar.

02

Pay-By-Link

Gera link e envia SMS. Cliente escolhe método ao clicar.

03

QR Code

Gera QR Code dinâmico para pagamento com conta iMali.

Autenticação

A IMaliWay utiliza encriptação RSA-ES-PKCS1 para gerar uma chave privada a partir do api_key e publicKey fornecidos pela Paytek. Este token deve ser enviado em cada pedido.

1

Receber credenciais da Paytek

Após registo como parceiro, a Paytek fornece api_key e publicKey para o ambiente Sandbox.

2

Gerar a privateKey

Encripte o api_key com RSA-ES-PKCS1 usando a publicKey para obter a privateKey.

3

Incluir em cada pedido

Envie Authorization: Bearer {privateKey} e X-Client-ID em todos os headers.

Nunca exponha a privateKey em código do lado do cliente. Gere-a sempre no servidor.

Headers obrigatórios em todos os pedidos

HeaderValor

AuthorizationBearer <privateKey>

X-Client-ID<your_client_id>

Content-Typeapplication/json

Acceptapplication/json

Códigos de Resposta

A API usa códigos no estilo HTTP para indicar sucesso ou falha.

Sucesso

200Success

201Success — Created

Erros

400partner_transaction_id com menos de 12 caracteres

401Pagamento não aceite / transação expirada

402Valor inválido (negativo ou zero)

404Cliente/loja/conta inválida

405Método não permitido

406partner_transaction_id já em uso

407Saldo insuficiente

408Conta/loja bloqueada

409Valor não disponível

422Pedido mal formatado

500Token inválido

501Limite KYC do cliente atingido

502Limite KYC da loja atingido

Push Payment

POST /payments

Cria uma transação de pagamento Push (C2B) para qualquer método disponível no gateway: M-Pesa, e-Mola, mKesh ou conta digital iMali. O cliente recebe uma notificação push no seu telemóvel para confirmar o pagamento.

Parâmetros

Parâmetro	Tipo	Estado	Descrição
`client_account_number`	string	obrigatório	Número de telefone da carteira (M-Pesa: 84xxxxxxx) ou conta iMali (9 dígitos)
`amount`	decimal	obrigatório	Valor a pagar. Mínimo 10 MT. Ex: 1000.00
`store_account_number`	string	obrigatório	Número da conta iMali da loja (conta STORE, 9 dígitos)
`partner_transaction_id`	string	obrigatório	ID único da transação gerado pelo parceiro. Exatamente 12 caracteres alfanuméricos. Ex: MPS25KLHLIKA
`payment_method`	enum mpesa \| emola \| mkesh \| imali	obrigatório	Método de pagamento em minúsculas
`payment_type`	enum push	fixo	Fixo: "push"
`transaction_type`	enum C2B	fixo	Fixo: "C2B"
`expiration_datetime`	string	opcional	Data/hora de expiração. Formato: Y-m-d H:i:s. Padrão: 2 minutos

curl -X POST 'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments' \
                        -H 'Authorization: Bearer {privateKey}' \
                        -H 'X-Client-ID: {client_id}' \
                        -H 'Content-Type: application/json' \
                        -H 'Accept: application/json' \
                        --data '{"client_account_number":"842592349","amount":"1000.00","store_account_number":"290000001","partner_transaction_id":"MPS25KLHLIKA","payment_method":"mpesa","payment_type":"push","transaction_type":"C2B"}'

const response = await fetch('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments', {
                            method: 'POST',
                            headers: {
                                'Authorization': 'Bearer {privateKey}',
                                'X-Client-ID': '{client_id}',
                                'Content-Type': 'application/json',
                                'Accept': 'application/json',
                            },
                            body: JSON.stringify({
                                client_account_number: '842592349',
                                amount: '1000.00',
                                store_account_number: '290000001',
                                partner_transaction_id: 'MPS25KLHLIKA',
                                payment_method: 'mpesa',
                                payment_type: 'push',
                                transaction_type: 'C2B'
                            }),
                        });
                        const data = await response.json();
                        console.log(data);

<?php
                        $ch = curl_init('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments');
                        curl_setopt_array($ch, [
                        CURLOPT_RETURNTRANSFER => true,
                        CURLOPT_CUSTOMREQUEST  => 'POST',
                        CURLOPT_HTTPHEADER     => [
                        'Authorization: Bearer {privateKey}',
                        'X-Client-ID: {client_id}',
                        'Content-Type: application/json',
                        'Accept: application/json',
                        ],
                        CURLOPT_POSTFIELDS     => json_encode([
                        'client_account_number' => '842592349',
                        'amount'                => '1000.00',
                        'store_account_number'  => '290000001',
                        'partner_transaction_id'=> 'MPS25KLHLIKA',
                        'payment_method'        => 'mpesa',
                        'payment_type'          => 'push',
                        'transaction_type'      => 'C2B'
                        ]),
                        ]);
                        $response = json_decode(curl_exec($ch), true);
                        curl_close($ch);

import requests

                        response = requests.post(
                        'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments',
                        headers={
                        'Authorization': 'Bearer {privateKey}',
                        'X-Client-ID': '{client_id}',
                        'Content-Type': 'application/json',
                        'Accept': 'application/json',
                        },
                        json={
                        'client_account_number': '842592349',
                        'amount': '1000.00',
                        'store_account_number': '290000001',
                        'partner_transaction_id': 'MPS25KLHLIKA',
                        'payment_method': 'mpesa',
                        'payment_type': 'push',
                        'transaction_type': 'C2B'
                        }
                        )
                        print(response.json())

Resposta (200 OK)

{
                                "data": {
                                "transaction_id": "MPS25KLHLIKA",
                                "partner_transaction_id": "MPS25KLHLIKA",
                                "amount": "1000.00",
                                "expiration_datetime": "2026-05-06 14:32:00",
                                "status": "PENDING"
                                }
                            }

Pay-By-Link

POST /payments

Gera um link de pagamento e envia via SMS para o cliente. O link redireciona para a página web do gateway, onde o cliente escolhe o método de pagamento. Suporta tipos DIRECT, RECURRING e DONATION.

Parâmetros

Parâmetro	Tipo	Estado	Descrição
`title`	string	obrigatório	Título do link de pagamento
`short_description`	string	obrigatório	Descrição breve do link
`amount`	decimal	obrigatório	Valor a pagar
`type`	enum DIRECT \| RECURRING \| DONATION	obrigatório	Tipo de link
`store_account_number`	string	obrigatório	Número da conta STORE iMali
`customer_link_id`	string	obrigatório	ID personalizado do link (deve ser único)
`send_to_phone`	string	obrigatório	Número de telefone para enviar o link via SMS
`partner_transaction_id`	string	obrigatório	ID único da transação. Exatamente 12 caracteres
`payment_method`	enum imali	fixo	Fixo: "imali"
`payment_type`	enum link	fixo	Fixo: "link"
`transaction_type`	enum C2B	fixo	Fixo: "C2B"
`expiration_datetime`	string	opcional	Data/hora de expiração. Formato: Y-m-d H:i:s
`thumbnail_image`	string	opcional	URL da imagem associada ao link
`payment_frequence`	enum DAILY \| WEEKLY \| MONTHLY \| YEARLY	opcional	Frequência de pagamento (apenas RECURRING)

curl -X POST 'https://paytek-africa.net:11901/api/parts/imaliway/v2/payments' \
                            -H 'Authorization: Bearer {privateKey}' \
                            -H 'X-Client-ID: {client_id}' \
                            -H 'Content-Type: application/json' \
                            -H 'Accept: application/json' \
                            --data '{"title":"Pagamento de Serviços","short_description":"PAY BY LINK","amount":"500.00","type":"DIRECT","store_account_number":"290000001","customer_link_id":"LINK_PARTNER_001","send_to_phone":"846002000","partner_transaction_id":"SJM5LYOVU5GJ","payment_method":"imali","payment_type":"link","transaction_type":"C2B"}'

const response = await fetch('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments', {
                                method: 'POST',
                                headers: {
                                    'Authorization': 'Bearer {privateKey}',
                                    'X-Client-ID': '{client_id}',
                                    'Content-Type': 'application/json',
                                    'Accept': 'application/json',
                                },
                                body: JSON.stringify({
                                    title: 'Pagamento de Serviços',
                                    short_description: 'PAY BY LINK',
                                    amount: '500.00',
                                    type: 'DIRECT',
                                    store_account_number: '290000001',
                                    customer_link_id: 'LINK_PARTNER_001',
                                    send_to_phone: '846002000',
                                    partner_transaction_id: 'SJM5LYOVU5GJ',
                                    payment_method: 'imali',
                                    payment_type: 'link',
                                    transaction_type: 'C2B'
                                }),
                            });
                            const data = await response.json();
                            console.log(data);

<?php
                            $ch = curl_init('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments');
                            curl_setopt_array($ch, [
                            CURLOPT_RETURNTRANSFER => true,
                            CURLOPT_CUSTOMREQUEST  => 'POST',
                            CURLOPT_HTTPHEADER     => [
                            'Authorization: Bearer {privateKey}',
                            'X-Client-ID: {client_id}',
                            'Content-Type: application/json',
                            'Accept: application/json',
                            ],
                            CURLOPT_POSTFIELDS     => json_encode([
                            'title'                 => 'Pagamento de Serviços',
                            'short_description'     => 'PAY BY LINK',
                            'amount'                => '500.00',
                            'type'                  => 'DIRECT',
                            'store_account_number'  => '290000001',
                            'customer_link_id'      => 'LINK_PARTNER_001',
                            'send_to_phone'         => '846002000',
                            'partner_transaction_id'=> 'SJM5LYOVU5GJ',
                            'payment_method'        => 'imali',
                            'payment_type'          => 'link',
                            'transaction_type'      => 'C2B'
                            ]),
                            ]);
                            $response = json_decode(curl_exec($ch), true);
                            curl_close($ch);

import requests

                            response = requests.post(
                            'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments',
                            headers={
                            'Authorization': 'Bearer {privateKey}',
                            'X-Client-ID': '{client_id}',
                            'Content-Type': 'application/json',
                            'Accept': 'application/json',
                            },
                            json={
                            'title': 'Pagamento de Serviços',
                            'short_description': 'PAY BY LINK',
                            'amount': '500.00',
                            'type': 'DIRECT',
                            'store_account_number': '290000001',
                            'customer_link_id': 'LINK_PARTNER_001',
                            'send_to_phone': '846002000',
                            'partner_transaction_id': 'SJM5LYOVU5GJ',
                            'payment_method': 'imali',
                            'payment_type': 'link',
                            'transaction_type': 'C2B'
                            }
                            )
                            print(response.json())

Resposta (200 OK)

{
                                    "data": {
                                    "link_id": "LNK123456789",
                                    "customer_link_id": "https://pay.imali.co.mz/l/LINK_PARTNER_001",
                                    "partner_transaction_id": "SJM5LYOVU5GJ",
                                    "send_to_phone": "846002000",
                                    "title": "Pagamento de Serviços",
                                    "amount": "500.00",
                                    "imali_fee": 5.00,
                                    "amount_to_credit": 495.00,
                                    "short_description": "PAY BY LINK",
                                    "type": "DIRECT",
                                    "status": "PENDING",
                                    "store_id": 290,
                                    "business_account_id": 122
                                    }
                                }

QR Code

POST /payments

Gera um QR Code dinâmico para pagamento com conta iMali. DYNAMIC_TERMINAL: valor variável, validade de 2 minutos (sem título/descrição). DYNAMIC_TICKET: valor fixo, expiração e título/descrição obrigatórios, sem refresh.

Parâmetros

Parâmetro	Tipo	Estado	Descrição
`store_account_number`	string	obrigatório	Número da conta STORE iMali
`amount`	decimal	obrigatório	Valor a pagar
`partner_transaction_id`	string	obrigatório	ID único da transação. Exatamente 12 caracteres
`payment_method`	enum imali	fixo	Fixo: "imali"
`payment_type`	enum qrcode	fixo	Fixo: "qrcode"
`qrcode_type`	enum DYNAMIC_TERMINAL \| DYNAMIC_TICKET	obrigatório	DYNAMIC_TERMINAL: valor variável, 2 min. DYNAMIC_TICKET: valor fixo, requer expiração/título/descrição
`transaction_type`	enum C2B	fixo	Fixo: "C2B"
`title`	string	opcional	Título (obrigatório para DYNAMIC_TICKET)
`description`	string	opcional	Descrição (obrigatório para DYNAMIC_TICKET)
`expiration_datetime`	string	opcional	Data/hora de expiração (obrigatório para DYNAMIC_TICKET)

curl -X POST 'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments' \
                                -H 'Authorization: Bearer {privateKey}' \
                                -H 'X-Client-ID: {client_id}' \
                                -H 'Content-Type: application/json' \
                                -H 'Accept: application/json' \
                                --data '{"store_account_number":"290000001","amount":"400.00","partner_transaction_id":"FJNGMQWLXCP3","payment_method":"imali","payment_type":"qrcode","qrcode_type":"DYNAMIC_TERMINAL","transaction_type":"C2B"}'

const response = await fetch('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments', {
                                    method: 'POST',
                                    headers: {
                                        'Authorization': 'Bearer {privateKey}',
                                        'X-Client-ID': '{client_id}',
                                        'Content-Type': 'application/json',
                                        'Accept': 'application/json',
                                    },
                                    body: JSON.stringify({
                                        store_account_number: '290000001',
                                        amount: '400.00',
                                        partner_transaction_id: 'FJNGMQWLXCP3',
                                        payment_method: 'imali',
                                        payment_type: 'qrcode',
                                        qrcode_type: 'DYNAMIC_TERMINAL',
                                        transaction_type: 'C2B'
                                    }),
                                });
                                const data = await response.json();
                                console.log(data);

<?php
                                $ch = curl_init('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments');
                                curl_setopt_array($ch, [
                                CURLOPT_RETURNTRANSFER => true,
                                CURLOPT_CUSTOMREQUEST  => 'POST',
                                CURLOPT_HTTPHEADER     => [
                                'Authorization: Bearer {privateKey}',
                                'X-Client-ID: {client_id}',
                                'Content-Type: application/json',
                                'Accept: application/json',
                                ],
                                CURLOPT_POSTFIELDS     => json_encode([
                                'store_account_number'  => '290000001',
                                'amount'                => '400.00',
                                'partner_transaction_id'=> 'FJNGMQWLXCP3',
                                'payment_method'        => 'imali',
                                'payment_type'          => 'qrcode',
                                'qrcode_type'           => 'DYNAMIC_TERMINAL',
                                'transaction_type'      => 'C2B'
                                ]),
                                ]);
                                $response = json_decode(curl_exec($ch), true);
                                curl_close($ch);

import requests

                                response = requests.post(
                                'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments',
                                headers={
                                'Authorization': 'Bearer {privateKey}',
                                'X-Client-ID': '{client_id}',
                                'Content-Type': 'application/json',
                                'Accept': 'application/json',
                                },
                                json={
                                'store_account_number': '290000001',
                                'amount': '400.00',
                                'partner_transaction_id': 'FJNGMQWLXCP3',
                                'payment_method': 'imali',
                                'payment_type': 'qrcode',
                                'qrcode_type': 'DYNAMIC_TERMINAL',
                                'transaction_type': 'C2B'
                                }
                                )
                                print(response.json())

Resposta (200 OK)

{
                                        "data": {
                                        "qrcode_id": "550e8400-e29b-41d4-a716-446655440000",
                                        "partner_transaction_id": "FJNGMQWLXCP3",
                                        "expiration_datetime": "2026-05-06 14:32:00",
                                        "amount": "400.00",
                                        "qrcode_type": "DYNAMIC_TERMINAL",
                                        "status": "PENDING"
                                        },
                                        "qrcode_token": "abc123:def456...789xyz",
                                        "qrcode_image": "data:image/png;base64,iVBORw0KGgo..."
                                    }

Verificar Estado

GET /payments/status

Verifica o estado de uma transação gerada via Push, Link ou QR Code. Para Push/Link usar partner_transaction_id. Para QR Code usar qrcode_token. Retorna PENDING, SUCCESS, FAILED ou EXPIRED.

Parâmetros

Parâmetro	Tipo	Estado	Descrição
`payment_type`	enum push \| link \| qrcode	obrigatório	Tipo de pagamento
`partner_transaction_id`	string	opcional	ID da transação (para push e link)
`qrcode_token`	string	opcional	Token do QR Code (apenas para qrcode)

curl -X GET 'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/status?partner_transaction_id=MPS25KLHLIKA&payment_type=push' \
                                    -H 'Authorization: Bearer {privateKey}' \
                                    -H 'X-Client-ID: {client_id}' \
                                    -H 'Accept: application/json'

const response = await fetch(
                                        'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/status?partner_transaction_id=MPS25KLHLIKA&payment_type=push',
                                        {
                                        method: 'GET',
                                        headers: {
                                        'Authorization': 'Bearer {privateKey}',
                                        'X-Client-ID': '{client_id}',
                                        'Accept': 'application/json',
                                        },
                                        }
                                        );
                                        const data = await response.json();
                                        console.log(data);

<?php
                                        $ch = curl_init('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/status?partner_transaction_id=MPS25KLHLIKA&payment_type=push');
                                        curl_setopt_array($ch, [
                                        CURLOPT_RETURNTRANSFER => true,
                                        CURLOPT_CUSTOMREQUEST  => 'GET',
                                        CURLOPT_HTTPHEADER     => [
                                        'Authorization: Bearer {privateKey}',
                                        'X-Client-ID: {client_id}',
                                        'Accept: application/json',
                                        ],
                                        ]);
                                        $response = json_decode(curl_exec($ch), true);
                                        curl_close($ch);

import requests

                                        response = requests.get(
                                        'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/status',
                                        headers={
                                        'Authorization': 'Bearer {privateKey}',
                                        'X-Client-ID': '{client_id}',
                                        'Accept': 'application/json',
                                        },
                                        params={
                                        'partner_transaction_id': 'MPS25KLHLIKA',
                                        'payment_type': 'push'
                                        }
                                        )
                                        print(response.json())

Resposta (200 OK)

{
                                                "data": {
                                                "status": "PENDING",
                                                "left_time": "1:45"
                                                }
                                            }

Atualizar QR

POST /payments/qrcode/refresh

Atualiza a validade de um QR Code DYNAMIC_TERMINAL expirado. Estende a validade por mais 2 minutos e altera o status para PENDING. Não disponível para DYNAMIC_TICKET.

Parâmetros

Parâmetro	Tipo	Estado	Descrição
`qrcode_token`	string	obrigatório	Token do QR Code obtido na criação

curl -X POST 'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/qrcode/refresh' \
                                            -H 'Authorization: Bearer {privateKey}' \
                                            -H 'X-Client-ID: {client_id}' \
                                            -H 'Content-Type: application/json' \
                                            -H 'Accept: application/json' \
                                            --data '{"qrcode_token":"a7c6a:fcc8ee9ceb82cb28...a37d0c8f9dfbf495ce05ff"}'

const response = await fetch('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/qrcode/refresh', {
                                                method: 'POST',
                                                headers: {
                                                    'Authorization': 'Bearer {privateKey}',
                                                    'X-Client-ID': '{client_id}',
                                                    'Content-Type': 'application/json',
                                                    'Accept': 'application/json',
                                                },
                                                body: JSON.stringify({
                                                    qrcode_token: 'a7c6a:fcc8ee9ceb82cb28...a37d0c8f9dfbf495ce05ff'
                                                }),
                                            });
                                            const data = await response.json();
                                            console.log(data);

<?php
                                            $ch = curl_init('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/qrcode/refresh');
                                            curl_setopt_array($ch, [
                                            CURLOPT_RETURNTRANSFER => true,
                                            CURLOPT_CUSTOMREQUEST  => 'POST',
                                            CURLOPT_HTTPHEADER     => [
                                            'Authorization: Bearer {privateKey}',
                                            'X-Client-ID: {client_id}',
                                            'Content-Type: application/json',
                                            'Accept: application/json',
                                            ],
                                            CURLOPT_POSTFIELDS     => json_encode([
                                            'qrcode_token' => 'a7c6a:fcc8ee9ceb82cb28...a37d0c8f9dfbf495ce05ff'
                                            ]),
                                            ]);
                                            $response = json_decode(curl_exec($ch), true);
                                            curl_close($ch);

import requests

                                            response = requests.post(
                                            'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/qrcode/refresh',
                                            headers={
                                            'Authorization': 'Bearer {privateKey}',
                                            'X-Client-ID': '{client_id}',
                                            'Content-Type': 'application/json',
                                            'Accept': 'application/json',
                                            },
                                            json={
                                            'qrcode_token': 'a7c6a:fcc8ee9ceb82cb28...a37d0c8f9dfbf495ce05ff'
                                            }
                                            )
                                            print(response.json())

Resposta (200 OK)

{
                                                    "data": {
                                                    "qrcode_id": "550e8400-e29b-41d4-a716-446655440000",
                                                    "partner_transaction_id": "FJNGMQWLXCP3",
                                                    "expiration_datetime": "2026-05-06 14:34:00",
                                                    "amount": "400.00",
                                                    "qrcode_type": "DYNAMIC_TERMINAL",
                                                    "status": "PENDING"
                                                    },
                                                    "qrcode_token": "new_token_abc123...",
                                                    "qrcode_image": "data:image/png;base64,iVBORw0KGgo..."
                                                }

Verificação B2C

POST /payments/check

Verifica as taxas que serão cobradas numa transferência B2C antes de a executar. Retorna fee, total e nome mascarado do destinatário. No ambiente Sandbox, masked_name retorna "Indisponível".

Parâmetros

Parâmetro	Tipo	Estado	Descrição
`client_account_number`	string	obrigatório	Número de telefone ou conta iMali do destinatário
`amount`	decimal	obrigatório	Valor a transferir (decimal, ex: 100.00)
`store_account_number`	string	obrigatório	Número da conta BUSINESS (não Store) de onde sai o dinheiro
`partner_transaction_id`	string	obrigatório	ID único da transação. Exatamente 12 caracteres
`payment_method`	enum mpesa \| emola \| mkesh \| imali	obrigatório	Método de pagamento em minúsculas
`transaction_type`	enum B2C	fixo	Fixo: "B2C"

curl -X POST 'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/check' \
                                                -H 'Authorization: Bearer {privateKey}' \
                                                -H 'X-Client-ID: {client_id}' \
                                                -H 'Content-Type: application/json' \
                                                -H 'Accept: application/json' \
                                                --data '{"client_account_number":"846002000","amount":"100.00","store_account_number":"290000002","partner_transaction_id":"B2C25CHECKID1","payment_method":"mpesa","transaction_type":"B2C"}'

const response = await fetch('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/check', {
                                                    method: 'POST',
                                                    headers: {
                                                        'Authorization': 'Bearer {privateKey}',
                                                        'X-Client-ID': '{client_id}',
                                                        'Content-Type': 'application/json',
                                                        'Accept': 'application/json',
                                                    },
                                                    body: JSON.stringify({
                                                        client_account_number: '846002000',
                                                        amount: '100.00',
                                                        store_account_number: '290000002',
                                                        partner_transaction_id: 'B2C25CHECKID1',
                                                        payment_method: 'mpesa',
                                                        transaction_type: 'B2C'
                                                    }),
                                                });
                                                const data = await response.json();
                                                console.log(data);

<?php
                                                $ch = curl_init('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/check');
                                                curl_setopt_array($ch, [
                                                CURLOPT_RETURNTRANSFER => true,
                                                CURLOPT_CUSTOMREQUEST  => 'POST',
                                                CURLOPT_HTTPHEADER     => [
                                                'Authorization: Bearer {privateKey}',
                                                'X-Client-ID: {client_id}',
                                                'Content-Type: application/json',
                                                'Accept: application/json',
                                                ],
                                                CURLOPT_POSTFIELDS     => json_encode([
                                                'client_account_number' => '846002000',
                                                'amount'                => '100.00',
                                                'store_account_number'  => '290000002',
                                                'partner_transaction_id'=> 'B2C25CHECKID1',
                                                'payment_method'        => 'mpesa',
                                                'transaction_type'      => 'B2C'
                                                ]),
                                                ]);
                                                $response = json_decode(curl_exec($ch), true);
                                                curl_close($ch);

import requests

                                                response = requests.post(
                                                'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments/check',
                                                headers={
                                                'Authorization': 'Bearer {privateKey}',
                                                'X-Client-ID': '{client_id}',
                                                'Content-Type': 'application/json',
                                                'Accept': 'application/json',
                                                },
                                                json={
                                                'client_account_number': '846002000',
                                                'amount': '100.00',
                                                'store_account_number': '290000002',
                                                'partner_transaction_id': 'B2C25CHECKID1',
                                                'payment_method': 'mpesa',
                                                'transaction_type': 'B2C'
                                                }
                                                )
                                                print(response.json())

Resposta (200 OK)

{
                                                        "data": {
                                                        "client_account_number": "846002000",
                                                        "amount": "100.00",
                                                        "total": 102.25,
                                                        "fee": "0.0225",
                                                        "masked_name": "Indisponível"
                                                        }
                                                    }

Transferência B2C

POST /payments

Executa uma transferência B2C (Business-to-Customer). Utiliza os mesmos parâmetros do método B2C Check. A conta store_account_number deve ser a conta BUSINESS (não Store).

Parâmetros

Parâmetro	Tipo	Estado	Descrição
`client_account_number`	string	obrigatório	Número de telefone ou conta iMali do destinatário
`amount`	decimal	obrigatório	Valor a transferir (decimal, ex: 100.00)
`store_account_number`	string	obrigatório	Número da conta BUSINESS (não Store)
`partner_transaction_id`	string	obrigatório	ID único da transação. Exatamente 12 caracteres
`payment_method`	enum mpesa \| emola \| mkesh \| imali	obrigatório	Método de pagamento em minúsculas
`transaction_type`	enum B2C	fixo	Fixo: "B2C"

curl -X POST 'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments' \
                                                    -H 'Authorization: Bearer {privateKey}' \
                                                    -H 'X-Client-ID: {client_id}' \
                                                    -H 'Content-Type: application/json' \
                                                    -H 'Accept: application/json' \
                                                    --data '{"client_account_number":"846002000","amount":"100.00","store_account_number":"290000002","partner_transaction_id":"B2C25TRANS001","payment_method":"mpesa","transaction_type":"B2C"}'

const response = await fetch('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments', {
                                                        method: 'POST',
                                                        headers: {
                                                            'Authorization': 'Bearer {privateKey}',
                                                            'X-Client-ID': '{client_id}',
                                                            'Content-Type': 'application/json',
                                                            'Accept': 'application/json',
                                                        },
                                                        body: JSON.stringify({
                                                            client_account_number: '846002000',
                                                            amount: '100.00',
                                                            store_account_number: '290000002',
                                                            partner_transaction_id: 'B2C25TRANS001',
                                                            payment_method: 'mpesa',
                                                            transaction_type: 'B2C'
                                                        }),
                                                    });
                                                    const data = await response.json();
                                                    console.log(data);

<?php
                                                    $ch = curl_init('https://paytek-africa.net:11901/api/partners/imaliway/v2/payments');
                                                    curl_setopt_array($ch, [
                                                    CURLOPT_RETURNTRANSFER => true,
                                                    CURLOPT_CUSTOMREQUEST  => 'POST',
                                                    CURLOPT_HTTPHEADER     => [
                                                    'Authorization: Bearer {privateKey}',
                                                    'X-Client-ID: {client_id}',
                                                    'Content-Type: application/json',
                                                    'Accept: application/json',
                                                    ],
                                                    CURLOPT_POSTFIELDS     => json_encode([
                                                    'client_account_number' => '846002000',
                                                    'amount'                => '100.00',
                                                    'store_account_number'  => '290000002',
                                                    'partner_transaction_id'=> 'B2C25TRANS001',
                                                    'payment_method'        => 'mpesa',
                                                    'transaction_type'      => 'B2C'
                                                    ]),
                                                    ]);
                                                    $response = json_decode(curl_exec($ch), true);
                                                    curl_close($ch);

import requests

                                                    response = requests.post(
                                                    'https://paytek-africa.net:11901/api/partners/imaliway/v2/payments',
                                                    headers={
                                                    'Authorization': 'Bearer {privateKey}',
                                                    'X-Client-ID': '{client_id}',
                                                    'Content-Type': 'application/json',
                                                    'Accept': 'application/json',
                                                    },
                                                    json={
                                                    'client_account_number': '846002000',
                                                    'amount': '100.00',
                                                    'store_account_number': '290000002',
                                                    'partner_transaction_id': 'B2C25TRANS001',
                                                    'payment_method': 'mpesa',
                                                    'transaction_type': 'B2C'
                                                    }
                                                    )
                                                    print(response.json())

Resposta (200 OK)

{
                                                            "code": "IMS002",
                                                            "success": "Created Successfully",
                                                            "type": "IMS",
                                                            "message": "Transferência feita com sucesso",
                                                            "messageLang": {
                                                            "pt": "Transferência feita com sucesso",
                                                            "en": "Success Transfer"
                                                            }
                                                        }

Webhooks — Visão Geral

Webhooks permitem que o sistema notifique automaticamente a sua aplicação sempre que ocorrer um evento importante, como a confirmação de um pagamento. Elimina a necessidade de polling constante.

A adesão ao webhook é feita automaticamente no acto da parceria. O parceiro deve fornecer uma callback_url e receberá uma webhook_secret para validação.

Eventos Disponíveis

PAYMENT.PENDINGPagamento criado, aguarda conclusão

PAYMENT.SUCCESSPagamento concluído com sucesso

PAYMENT.FAILEDPagamento falhou

Fluxo do Webhook

Cliente inicia transação no sistema do parceiro
iMali Gateway processa a transação e atualiza o estado
Gateway envia requisição HTTP POST para a callback_url configurada
Sistema do parceiro valida assinatura e processa a notificação

Estrutura do Payload

Headers

Content-Type: application/json
X-Webhook-Id: evt_123456
X-Webhook-Timestamp: 1712750000
X-Webhook-Signature: sha256=abc123...

Body

{
                                                        "id": "evt_123456",
                                                        "type": "payment.success",
                                                        "data": {
                                                        "payment_id": "pay_123",
                                                        "amount": 5000,
                                                        "status": "SUCCESS"
                                                        }
                                                    }

Retentativas: Se o endpoint não responder com HTTP 2xx, o webhook será reenviado automaticamente — até 10 tentativas em 72h com intervalo progressivo.

Segurança dos Webhooks

Valide cada webhook recebido usando a assinatura HMAC-SHA256 no cabeçalho X-Webhook-Signature para garantir autenticidade e proteção anti-replay.

Rejeite sempre webhooks com timestamp superior a 5 minutos para prevenir ataques de repetição.

Processo de Validação

1

Ler dados do header

Obter X-Webhook-Timestamp e X-Webhook-Signature do header.

2

Construir string assinada

Concatenar: timestamp + "." + payload_bruto

3

Gerar assinatura esperada

HMAC-SHA256(signed_string, webhook_secret)

4

Comparar e validar tempo

Usar hash_equals() para comparação. Validar que timestamp ≤ 5 minutos.

API Sandbox

Teste os endpoints directamente no browser. Nenhum dinheiro real é movimentado. As respostas são simuladas para desenvolvimento.

Para obter credenciais de Sandbox, contacte info@paytekafrica.com.

Endpoint

Parâmetros

Resposta

Envie um pedido para ver a resposta aqui.

Content-Type: application/json
X-Request-Id:  req_sandbox_abc123
X-Environment: sandbox