AtEx v0.20.21 AtEx.Payment View Source

This module holds the implementation for the HTTP Gateway that runs calls against the Africas Talking API Payment endpoints

Link to this section Summary

Functions

Mobile Business To Business (B2B) APIs allow you to send payments to businesses e.g banks from your Payment Wallet.

This function initiates a mobile B2C request by making a HTTP POST request to the Africa's talking Mobile B2C endpoint.

Find a particular payment transaction by sending a HTTP GET request to the following endpoint

Bank checkout APIs allow your application to collect money into your payment wallet by initiating transactions that deduct money from a customers bank account.

Bank checkout validation APIs allow your application to validate bank checkout charge requests.

Bank checkout validation APIs allow your application to validate bank checkout charge requests.

Card Checkout APIs allow your application to collect money into your Payment Wallet by initiating transactions that deduct money from a customers Debit or Credit Card.

Card checkout validation APIs allow your application to validate card checkout charge requests.

Fetch transactions of a particular payment product by sending a HTTP GET request to the following endpoint

Fetch your wallet transactions by sending a HTTP GET request to the following endpoint

Find a particular payment transaction by sending a HTTP GET request to the following endpoint

This function initiates a mobile checkout request by sending a HTTP POST request to the Africa's talking Mobile Checkout endpoint.

Topup stash APIs allow you to move money from a Payment Product to an Africa’s Talking application stash. An application stash is the wallet that funds your service usage expences.

Wallet transfer APIs allow you to transfer money from one Payment Product to another Payment Product hosted on Africa’s Talking.

Link to this section Functions

Mobile Business To Business (B2B) APIs allow you to send payments to businesses e.g banks from your Payment Wallet.

Config

Add b2c_product_name key to your AtEx configs

Parameters

attrs: - a map containing a provider(Mpesa,TigoTanzania,Athena), transferType(BusinessBuyGoods,BusinessPayBill, DisburseFundsToBusiness, BusinessToBusinessTransfer), currencyCode amount, destinationChannel, destinationAccount and a map of metadata see the docs at https://build.at-labs.io/docs/payments%2Fmobile%2Fb2b for how to use these keys

Example

  iex>AtEx.Payment.b2b_checkout(%{provider: "Athena", transferType: "DisburseFundsToBusiness", amount: 10, currencyCode: "KES", destinationChannel: "Mine", destinationAccount: "Mine", metadata: %{ message: "I am here"}})
  {:ok,
  %{
  "providerChannel" => "525900",
  "status" => "Queued",
  "transactionFee" => "KES 0.1000",
  "transactionId" => "ATPid_2504d5f5d28256fa264e815518e3ab0d"
  }}

This function initiates a mobile B2C request by making a HTTP POST request to the Africa's talking Mobile B2C endpoint.

Config

Add stk_product_name key to your AtEx configs

Parameters

attrs: - a list of Recipient each a map containing a phoneNumber, currencyCode, amount and a map of metadata key optionally it may also contain name, reason and providerChannel see the docs at https://build.at-labs.io/docs/payments%2Fmobile%2Fb2c%2Foverview for how to use these keys

Example

  iex>AtEx.Payment.b2c_checkout([%{phoneNumber: "254724540000", amount: 10, currencyCode: "KES", metadata: %{ message: "I am here"}}])
  {:ok,
  %{
  "entries" => [
      %{
      "phoneNumber" => "+254724540000",
      "provider" => "Athena",
      "providerChannel" => "525900",
      "status" => "Queued",
      "transactionFee" => "KES 0.1000",
      "transactionId" => "ATPid_2b76da39eebd5c6bcc49e5d30c3d0390",
      "value" => "KES 10.0000"
      }
  ],
  "numQueued" => 1,
  "totalTransactionFee" => "KES 0.1000",
  "totalValue" => "KES 10.0000"
  }}

Find a particular payment transaction by sending a HTTP GET request to the following endpoint

Example

  iex>AtEx.Gateway.Payments.Query.WalletBalance.balance()
  {:ok, %{"balance" => "KES 90.0000", "status" => "Success"}}

Bank checkout APIs allow your application to collect money into your payment wallet by initiating transactions that deduct money from a customers bank account.

Config

Add bank_checkout_product_name key to your AtEx configs

Parameters

attrs: - a map containing bankAccount(a map), currencyCode, amount, narration and a map of metadata see the docs at https://build.at-labs.io/docs/payments%2Fbank%2Fcheckout for how to use these keys

Example

  iex>AtEx.Payment.bank_checkout(%{bankAccount: %{accountName: "KCB", accountNumber: "93892892", bankCode: 234001}, amount: 1000.00, currencyCode: "KES", narration: "Payment", metadata: %{detail: "A Bill"}})
  {:ok,
  %{
  "description" => "Payment is pending validation by the user",
  "status" => "PendingValidation",
  "transactionId" => "ATPid_722a5dbaf1e8be4832614b523810dc29"
  }}

Bank checkout validation APIs allow your application to validate bank checkout charge requests.

Config

Add bank_transfer_product_name key to your AtEx configs

Parameters

attrs: - a list of recipients each containing a map with currencyCode, amount, narration and a map of metadata (optional) see the docs at https://build.at-labs.io/docs/payments%2Fbank%2Ftransfer for how to use these keys

Example

  iex>AtEx.Payment.bank_transfer([%{bankAccount: %{accountName: "KCB", accountNumber: "93892892", bankCode: 234001}, amount: 1000.00, currencyCode: "KES", narration: "Payment", metadata: %{detail: "A Bill"}}])

  {:ok,
  %{
      "entries": [%{
          "accountNumber": "93892892",
          "status": "Queued",
          "transactionId": "ATPid_SampleTxnId",
          "transactionFee": "NGN 50.00"
      }]
  }}

Bank checkout validation APIs allow your application to validate bank checkout charge requests.

Parameters

attrs: - a map containing transactionId and otp see the docs at https://build.at-labs.io/docs/payments%2Fbank%2Fvalidate for how to use these keys

Example

  iex>AtEx.Payment.bank_validate(%{transactionId: "ATPid_a58b61dc2bf556ff9c4b16e9f6e40795", otp: "password"})
  {:ok,
  %{
      "status": "Success",
      "description": "Payment completed successfully"
  }}
Link to this function

card_checkout(map)

View Source
card_checkout(map()) :: {:error, any()} | {:ok, any()}

Card Checkout APIs allow your application to collect money into your Payment Wallet by initiating transactions that deduct money from a customers Debit or Credit Card.

Config

Add card_checkout_product_name key to your AtEx configs

Parameters

attrs: - a map containing either paymentCard(a map) or checkoutToken, currencyCode, amount, narration and a map of metadata(optional) see the docs at https://build.at-labs.io/docs/payments%2Fcard%2Fcheckout for how to use these keys

Example

  iex>AtEx.Payment.card_checkout(%{amount: 1000.00, currencyCode: "KES", narration: "Payment", paymentCard: %{number: "10928873477387", cvvNumber: 253, expiryMonth: 12, expiryYear: 2020, countryCode: "NG", authToken: "jhdguyt6372gsu6q"}})
  {:ok, %{
        status: "PendingValidation",
        description: "Waiting for user input",
        transactionId: "ATPid_SampleTxnId123"
      }}

Card checkout validation APIs allow your application to validate card checkout charge requests.

Parameters

attrs: - a map containing transactionId and otp see the docs at https://build.at-labs.io/docs/payments%2Fcard%2Fvalidate for how to use these keys

Example

  iex>AtEx.Payment.card_validate(%{transactionId: "ATPid_SampleTxnId123", otp: "password"})

  {:ok,
    %{
      "status": "Success",
      "description": "Payment completed successfully",
      "checkoutToken": "ATCdTkn_SampleCdTknId123"
  }}
Link to this function

fetch_product_transactions(map)

View Source

Fetch transactions of a particular payment product by sending a HTTP GET request to the following endpoint

Parameters

attrs: - a map containing:

  • productName - The name of the payment product whose transactions you’d like to fetch.
  • pageNumber - The number of the page you’d like to read results from. Please Note: This STARTS from 1 and NOT 0
  • count - The number of transaction results you would like for this query. Must be > 1 and < 1,000
  • and optional parameters startDate, endDate, category, provider, status, source, destination and providerChannel For more on how to use these keys https://build.at-labs.io/docs/payments%2Fquery%2Ffetch_product_transactions

Example

  iex>AtEx.Payment.fetch_product_transactions(%{productName: "AtEx", pageNumber: 1, count: 10})
  {:ok,
  %{
  "status" => "Success",
  "responses" => %{
      "requestMetadata" => %{
          "reason" => "Testing things..."
      },
      "sourceType" => "Wallet",
      "source" => "PaymentWallet",
      "provider" => "Mpesa",
      "destinationType" => "PhoneNumber",
      "description" => "The service request is processed successfully.",
      "providerChannel" => "824879",
      "transactionFee" => "KES 1.0000",
      "providerRefId" => "SAMPLE_MPESA_CODE",
      "providerMetadata" => %{
          "recipientIsRegistered" => "true",
          "recipientName" => "254724XXXYYY - John Doe"
      },
      "status" => "Success",
      "productName" => "testing",
      "category" => "MobileB2C",
      "transactionDate" => "12.05.2018 21:46:13",
      "destination" => "+254708663158",
      "value" => "KES 2900.0000",
      "transactionId" => "ATPid_b9379b671fee8ccf24b2c74f94da0ceb",
      "creationTime" => "2018-05-12 18:46:12"
  }
  }}
Link to this function

fetch_wallet_transactions(map)

View Source

Fetch your wallet transactions by sending a HTTP GET request to the following endpoint

Parameters

attrs: - a map containing:

  • pageNumber - The number of the page you’d like to read results from. Please Note: This STARTS from 1 and NOT 0
  • count - The number of transaction results you would like for this query. Must be > 1 and < 1,000
  • and optional parameters startDate, endDate, categories, provider, status, source, destination and providerChannel For more on how to use these keys https://build.at-labs.io/docs/payments%2Fquery%2Ffetch_wallet_transactions

Example

  iex>AtEx.Payment.fetch_wallet_transactions(%{ pageNumber: 1, count: 10})
  {:ok,
  %{
  "description" => "Success",
  "responses" => [
      %{
      "balance" => "KES 90.0000",
      "category" => "Debit",
      "date" => "2020-07-13 13:46:08",
      "description" => "MobileB2B Payment Request to Mine",
      "transactionId" => "ATPid_2504d5f5d28256fa264e815518e3ab0d",
      "value" => "KES 10.0000"
      },
      %{
      "balance" => "KES 90.0000",
      "category" => "Debit",
      "date" => "2020-07-10 18:50:22",
      "description" => "MobileB2C Payment Request to +254724540000",
      "transactionId" => "ATPid_5e635fa1099b4c7f69e63a0cbc3120c4",
      "value" => "KES 10.0000"
      },
      %{
      "balance" => "KES 90.0000",
      "category" => "Debit",
      "date" => "2020-07-01 15:18:33",
      "description" => "MobileB2C Payment Request to +254724540000",
      "transactionId" => "ATPid_beeb0be6b1bff57ec8f32675fe3f6e72",
      "value" => "KES 10.0000"
      }
  ],
  "status" => "Success"
  }}

Find a particular payment transaction by sending a HTTP GET request to the following endpoint

Parameters

attrs: - a map containing:

Example

  iex>AtEx.Payment.find_transaction(%{transactionId: "ATPid_a58b61dc2bf556ff9c4b16e9f6e40795"})
  {:ok,
  %{
  "status" => "Success",
  "data" => %{
      "requestMetadata" => %{
          "reason" => "Testing things..."
      },
      "sourceType" => "Wallet",
      "source" => "PaymentWallet",
      "provider" => "Mpesa",
      "destinationType" => "PhoneNumber",
      "description" => "The service request is processed successfully.",
      "providerChannel" => "824879",
      "transactionFee" => "KES 1.0000",
      "providerRefId" => "SAMPLE_MPESA_CODE",
      "providerMetadata" => %{
          "recipientIsRegistered" => "true",
          "recipientName" => "254724XXXYYY - John Doe"
      },
      "status" => "Success",
      "productName" => "testing",
      "category" => "MobileB2C",
      "transactionDate" => "12.05.2018 21:46:13",
      "destination" => "+254708663158",
      "value" => "KES 2900.0000",
      "transactionId" => "ATPid_b9379b671fee8ccf24b2c74f94da0ceb",
      "creationTime" => "2018-05-12 18:46:12"
  }
  }}

This function initiates a mobile checkout request by sending a HTTP POST request to the Africa's talking Mobile Checkout endpoint.

Parameters

attrs: - a map containing a phoneNumber, currencyCode and amount key optionally it may also contain providerChannel and a map of metadata see the docs at https://build.at-labs.io/docs/payments%2Fmobile%2Fcheckout for how to use these keys

Example

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

Topup stash APIs allow you to move money from a Payment Product to an Africa’s Talking application stash. An application stash is the wallet that funds your service usage expences.

Parameters

map: - a map containing:

  • productName Africa’s Talking Payment product to initiate this transaction.
  • currencyCode 3-digit ISO format currency code for the value of this transaction (e.g KES, UGX, USD)
  • amount Amount - in the provided currency - that the application will be topped up with.
  • metadata A map of any metadata that you would like us to associate with the request. Use this field to send data that will map notifications to topup stash requests. It will be included in the notification we send once the topup stash request is completed.

Example

iex> AtEx.Payment.topup(%{ currencyCode: "KES", amount: 1500, productName: "AtEx", metadata: %{ message: "I am here"}})
  {:ok,
    %{
      "status" => "Success",
      "description" => "Topped up user stash. New Stash Balance: KES 1500.00",
      "transactionId" => "ATPid_SampleTxnId123"
    }
  }

Wallet transfer APIs allow you to transfer money from one Payment Product to another Payment Product hosted on Africa’s Talking.

Parameters

map: - a map containing:

  • productName Africa’s Talking Payment product to initiate this transaction.
  • targetProductCode Unique product code of the Africa’s Talking Payment Product to transfer the funds to.
  • currencyCode 3-digit ISO format currency code for the value of this transaction (e.g KES, UGX, USD)
  • amount Amount - in the provided currency - that the application will be topped up with.
  • metadata A map of any metadata that you would like us to associate with the request. Use this field to send data that will map notifications to topup stash requests. It will be included in the notification we send once the topup stash request is completed.

Example

iex> AtEx.Payment.transfer(%{ currencyCode: "KES", amount: 1500.00, productName: "AtEx", targetProductCode: 564,  metadata: %{ message: "Electricity Bills"}})
      {:ok,
        %{
          "status" => "Success",
          "description" => "Transfered funds to sandbox [TestProduct]",
          "transactionId" => "ATPid_SampleTxnId123"
        }
      }