Skip to main content

Python SDK

With the Transfa API, you can request payments from anywhere in West Africa. And by using the SDKs, you can quickly integrate Transfa in your workflow and benefits of the following features:

  • Request a payment
  • Get a payment status
  • Refund a payment
  • Retrieve and list all payments
  • And also process webhooks sent from our end to get real-time update.

Let's see how you can use the Transfa Python SDK to collect and manage payments without further due.

Note

You will need an API key for this tutorial. For better understanding and avoiding unwanted effects, you should use tests api keys before, and once you are comfortable with the SDK and sure that the integration is working, you can move to a live environement.

Using the Transfa Python SDK​

First of all, you need to install the SDK python package.

pip install --upgrade transfa

After the installation, let's describe the minimum required information to request a payment.

import uuid

from transfa.api_client import client

client.api_key = "ak_test_..."

response = client.Payment.request_payment({
        "account_alias": "60201010",
        "amount": 5000,
        "mode": "mtn-benin",
        "webhook_url": "https://your_app_url.domain/your_webhook_endpoint/" # Optional
    },
    idempotency_key=uuid.uuid4().hex)

# Process the response's body
print(response.text)

In the code above, we are using the request_payment method to request a payment. The required payload for this method is:

  • the account_alias which represents the mobile money account of your customer.
  • the amount which means the amount of the payment requested.
  • the mode which means the gateway of the account_alias
  • and another parameter, the idempotency_key which is actually essential as it helps us and you avoid duplicated payments.

You can also send a webhook_url and the Transfa API will handle everything that concerns webhook notifications.

The returned object by the request_payment method is a Response object and you can access the data of the responses as you will do with this type of object.

Retrieve and List Payments​

The Transfa SDK also provides methods such as list and retrieve to list and retrieve payments from the API.

from transfa.api_client import client

client.api_key = "ak_test_..."

response = client.Payment.list()
print(response.text)

response = client.Payment.retrieve(payment_id="28dc22751e854b86a6a1d8ded87a83")
print(response.text)

And for a better developer experience, if you want to check the status of a payment you can use the status method and pass the payment id as a parameter.


from transfa.api_client import client

client.api_key = "ak_test_..."

response = client.Payment.status(payment_id="28dc22751e854b86a6a1d8ded87a83")

print(response.text)

And you can also request a refund for a certain payment using the refund method. You just need to use the refund method and pass the payment id as a parameter.


from transfa.api_client import client

client.api_key = "ak_test_..."

response = client.Payment.refund(payment_id="28dc22751e854b86a6a1d8ded87a83")
print(response.text)

Now that we better understand how to use the Payment API, let's see how you can verify a webhook using the Transfa Python SDK.

Webhooks​

At Transfa, we use webhooks to notify you of changes in the status of a payment. Here is an example of a webhook payload sent by the Transfa API.

{
  "webhook_id": "a6a307855d4e4e0dbab9e4e98cee80f7",
  "event": "payment:processing",
  "payment": "WGYDKVCCCK",
  "created": "2023-01-29T11:29:18.439332+00:00",
  "updated": "2023-01-29T11:29:18.439346+00:00"
}

The webhooks handle three types of events. These events come with the following structure payment:financial_status and you can have the following events:

  • payment:pending: meaning that the payment is pending. It also means that the status of the payment is processing.
  • payment:success: meaning that the payment is completed.
  • payment:failed meaning that the payment has been canceled or has just failed.
  • payment:refunded meaning that the payment has been refunded. The status of the payment will remain completed.

Using the Transfa SDK, you will need to have a private secret key. This key is used to sign the payload of the request and ensure that there is no data tempering.

from transfa.webhook import Webhook

...

webhook = Webhook(webhook_token=secret_key, body=body, headers=request.headers)

verified = webhook.verify()

In the code above, verified can either be a boolean or a dict. If the verify the method runs successfully, it will return the data in the payload. Otherwise, you will receive False the meaning that the data is not authentic.

tip

It is a good habit to use an environment to store transfa API and secret keys in your Python application. We can recommend the usage python-dotenv or you can use the getenv API of the os package.