Documentação

Introdução

A API da Txenka é organizada em torno de payment_intents — cada pagamento que crias e confirmas. Todos os pedidos e respostas usam JSON, e o URL base é https://api.txenka.com/v1.

Autenticação

Todas as chamadas autenticadas usam a tua API key no cabeçalho Authorization. Encontras a tua chave em Definições → API Keys no dashboard — usa txk_test_… para testar sem processar dinheiro real, e txk_live_… em produção.

HTTP Header

Authorization: Bearer txk_test_8f2a3c9d1e...

Criar um pagamento

Um payment_intent representa uma cobrança. O valor é sempre em centavos (2450 = 24,50 MZN).

curl -X POST https://api.txenka.com/v1/payment-intents \
  -H "Authorization: Bearer txk_test_8f2a3c9d1e..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2450,
    "currency": "MZN",
    "payment_method": "mpesa",
    "customer_phone": "258840000000",
    "description": "Pedido #1042"
  }'

const res = await fetch('https://api.txenka.com/v1/payment-intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer txk_test_8f2a3c9d1e...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 2450,
    currency: 'MZN',
    payment_method: 'mpesa',
    customer_phone: '258840000000',
    description: 'Pedido #1042',
  }),
});
const intent = await res.json();

$ch = curl_init('https://api.txenka.com/v1/payment-intents');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer txk_test_8f2a3c9d1e...',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 2450,
        'currency' => 'MZN',
        'payment_method' => 'mpesa',
        'customer_phone' => '258840000000',
        'description' => 'Pedido #1042',
    ]),
]);
$intent = json_decode(curl_exec($ch), true);

import requests

response = requests.post(
    "https://api.txenka.com/v1/payment-intents",
    headers={"Authorization": "Bearer txk_test_8f2a3c9d1e..."},
    json={
        "amount": 2450,
        "currency": "MZN",
        "payment_method": "mpesa",
        "customer_phone": "258840000000",
        "description": "Pedido #1042",
    },
)
intent = response.json()

require 'net/http'
require 'json'

uri = URI('https://api.txenka.com/v1/payment-intents')
req = Net::HTTP::Post.new(uri)
req['Authorization'] = 'Bearer txk_test_8f2a3c9d1e...'
req['Content-Type'] = 'application/json'
req.body = {
  amount: 2450,
  currency: 'MZN',
  payment_method: 'mpesa',
  customer_phone: '258840000000',
  description: 'Pedido #1042',
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
intent = JSON.parse(res.body)

body, _ := json.Marshal(map[string]any{
    "amount":         2450,
    "currency":       "MZN",
    "payment_method": "mpesa",
    "customer_phone": "258840000000",
    "description":    "Pedido #1042",
})

req, _ := http.NewRequest("POST", "https://api.txenka.com/v1/payment-intents", bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer txk_test_8f2a3c9d1e...")
req.Header.Set("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

var body = """
    {"amount":2450,"currency":"MZN","payment_method":"mpesa",
     "customer_phone":"258840000000","description":"Pedido #1042"}""";

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.txenka.com/v1/payment-intents"))
    .header("Authorization", "Bearer txk_test_8f2a3c9d1e...")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

Response

{
  "object": "payment_intent",
  "id": "pi_01hx4k9…",
  "status": "requires_confirmation",
  "amount": 2450,
  "currency": "MZN",
  "payment_method": "mpesa"
}

Confirmar o pagamento

Confirmar dispara o pedido junto do método escolhido — por exemplo, um pedido STK push no telemóvel do cliente para M-Pesa/e-Mola.

curl -X POST https://api.txenka.com/v1/payment-intents/pi_01hx4k9…/confirm \
  -H "Authorization: Bearer txk_test_8f2a3c9d1e..."

const res = await fetch(
  'https://api.txenka.com/v1/payment-intents/pi_01hx4k9…/confirm',
  { method: 'POST', headers: { 'Authorization': 'Bearer txk_test_8f2a3c9d1e...' } }
);
const result = await res.json();

$ch = curl_init('https://api.txenka.com/v1/payment-intents/pi_01hx4k9…/confirm');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer txk_test_8f2a3c9d1e...'],
]);
$result = json_decode(curl_exec($ch), true);

import requests

response = requests.post(
    "https://api.txenka.com/v1/payment-intents/pi_01hx4k9…/confirm",
    headers={"Authorization": "Bearer txk_test_8f2a3c9d1e..."},
)
result = response.json()

require 'net/http'
require 'json'

uri = URI('https://api.txenka.com/v1/payment-intents/pi_01hx4k9…/confirm')
req = Net::HTTP::Post.new(uri)
req['Authorization'] = 'Bearer txk_test_8f2a3c9d1e...'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
result = JSON.parse(res.body)

req, _ := http.NewRequest(
    "POST",
    "https://api.txenka.com/v1/payment-intents/pi_01hx4k9…/confirm",
    nil,
)
req.Header.Set("Authorization", "Bearer txk_test_8f2a3c9d1e...")

res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.txenka.com/v1/payment-intents/pi_01hx4k9…/confirm"))
    .header("Authorization", "Bearer txk_test_8f2a3c9d1e...")
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();

var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

O status devolvido pode ser processing (aguarda confirmação do cliente), succeeded ou failed. Para métodos assíncronos, subscreve um webhook para saberes quando o estado muda sem teres de sondar a API.

Métodos de pagamento

mpesa M-Pesa — carteira móvel Vodacom

emola e-Mola — carteira móvel Movitel

card Cartão — Visa e Mastercard

bank_transfer Transferência bancária

Webhooks

Configura um endpoint em Definições → Webhooks no dashboard para receberes uma notificação HTTP POST sempre que o estado de um pagamento mudar — sem teres de sondar a API.

Eventos principais

payment_intent.succeeded

O pagamento foi confirmado com sucesso.

payment_intent.failed

O pagamento falhou ou foi recusado.

payment_intent.processing

Aguarda confirmação do cliente (ex: STK push enviado).

Erros

Erros seguem sempre o mesmo formato, com um code estável para tratares programaticamente e uma message legível.

Response

{
  "error": {
    "code": "payment_method_disabled",
    "message": "O método de pagamento 'mpesa' não está activo para esta conta."
  }
}

Precisas de ajuda a integrar?

A nossa equipa responde a dúvidas técnicas sobre a API.

Falar com a equipa