AtEx

An API Wrapper for the Africas Talking API https://africastalking.com/

Features
Installation
Configuration
Documentation
Contribution
Licence

Features

We hope to cover all the endpoints of Africas Talking to help elixir developers integrate its services in their applications. Here are the main modules we hope to develop in the process.

Installation

Available in Hex, the package can be installed by adding at_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:at_ex, "~> 0.20.22"}
  ]
end

Configuration

Create a dev.exs file under the config folder in the root of the project if you do not have it. like touch config/dev.exs to setup configs for development environment i.e, sandbox credentials check sample configuration below.
Create a prod.exs file under the config folder in the root of the project if you dont have it. like touch config/prod.exs to setup at_ex configs for production environment i.e, live credentials check sample configuration below.
Copy the contents of dev.sample.exs into the dev.exs created above.
Go to Africas Talking to register for an account.
On signing up go to the https://account.africastalking.com/apps/sandbox to get an api key
Add the api key in the api_key:value in the config/dev.exs created above.
For sandbox, set the sandbox key to true

Example Configuration setup

Below is an example configuration for dev.exs this is suitable for testing with the sandbox:

config :at_ex,
  api_key: "===INSERT AFRICAS_TALKING_API_KEY HERE ===",
  # When changed to "false" one will use the live endpoint url
  sandbox: true,
  username: "sandbox",
  stk_product_name: "AtEx",
  b2c_product_name: "AtEx",
  b2b_product_name: "AtEx",
  bank_checkout_product_name: "AtEx",
  bank_transfer_product_name: "AtEx",
  card_checkout_product_name: "AtEx"

Below is an example configuration for prod.exs this is when you go live:

config :at_ex,
  api_key: "===INSERT AFRICAS_TALKING_LIVE_API_KEY HERE ===",
  username: "LIVE_USERNAME",
  # When changed to "false" one will use the live endpoint url
  sandbox: false,
  stk_product_name: "AtEx", #Add your specific product name.
  b2c_product_name: "AtEx",
  b2b_product_name: "AtEx",
  bank_checkout_product_name: "AtEx",
  bank_transfer_product_name: "AtEx",
  card_checkout_product_name: "AtEx"

Documentation

The docs can be found at https://hexdocs.pm/at_ex.

Quick examples

Sending SMS

    iex> AtEx.Sms.send_sms(%{to: "+254722000000", message: "Howdy"})
    {:ok,
    %{
        "SMSMessageData" => %{
        "Message" => "Sent to 1/1 Total Cost: ZAR 0.1124",
        "Recipients" => [
        %{
            "cost" => "KES 0.8000",
            "messageId" => "ATXid_96e52a761a82c1bad58e885109224aad",
            "number" => "+254722000000",
            "status" => "Success",
            "statusCode" => 101
        }
        ]
    }
    }}

Payment Mobile checkout

    iex>AtEx.Payment.mobile_checkout(%{phoneNumber: "254724540000", amount: 10, currencyCode: "KES"})
    %{
        "description" => "Waiting for user input",
        "providerChannel" => "525900",
        "status" => "PendingConfirmation",
        "transactionId" => "ATPid_bbd0bcd713e27d9201807076c6db0ed5"
    }

Contribution

If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question. If you don't see your idea listed, Open an issue.

Check the Contribution guide on how to contribute.