View Source KoraPay (korapay v0.1.0)

KoraPay client wrapper (https://docs.korapay.com/).

installation

Installation

Set the the required environment variables for production. For development/sandbox data set config/dev.exs.

see: https://developers.korapay.com/docs/api-keys

  config :kora_pay,
    public: "test_yourkey",
    private: "test_yourkey",
    webhook_url: "https://www.myserver.com/webhook",

usage

Usage

  defmodule MyApp do
    def all_banks do
      case KoraPay.list_banks() do
        {:ok, banks} -> IO.inspect(banks)
        {:error, error} -> IO.inspect(error)
      end
    end
  end

Link to this section Summary

Link to this section Types

@type auth_model() :: :otp | :three_ds | :avs | :pin
@type auth_options() ::
  String.t()
  | %{
      state: String.t(),
      city: String.t(),
      country: String.t(),
      address: String.t(),
      zip_codes: String.t()
    }
@type balance() :: %{NGN: %{pending_balance: float(), available_balance: float()}}
@type bank_account() :: %{
  bank_name: String.t(),
  bank_code: String.t(),
  account_number: String.t(),
  account_name: String.t()
}
@type card() :: %{
  card_type: :mastercard | :visa | :verve,
  first_six: String.t(),
  last_four: String.t(),
  expiry: String.t()
}
@type channel() :: :card | :bank_transfer
@type charge_options() :: %{
  optional(:redirect_url) => String.t(),
  optional(:channels) => [channel()],
  optional(:default_channel) => channel()
}
@type charge_reference() :: %{reference: String.t(), checkout_url: String.t()}
@type charge_response() :: %{
  amount: non_neg_integer(),
  amount_charged: non_neg_integer(),
  auth_model: auth_model(),
  currency: String.t(),
  fee: float(),
  vat: float(),
  response_message: String.t(),
  payment_reference: String.t(),
  status: status(),
  transaction_reference: String.t(),
  authorization: %{},
  card: card()
}
@type charge_status() :: %{
  reference: String.t(),
  amount: non_neg_integer(),
  fee: float(),
  currency: String.t(),
  status: status(),
  description: String.t(),
  created_at: DateTime.t(),
  payer_bank_account: payer_bank_account(),
  card: card()
}
@type customer() :: %{
  :email => String.t(),
  optional(:name) => String.t(),
  optional(:phone) => String.t()
}
@type destination() :: %{
  type: String.t(),
  amount: float(),
  currency: String.t(),
  narration: String.t(),
  bank_account: short_bank_account(),
  customer: customer()
}
@type disbursement() :: %{
  amount: non_neg_integer(),
  fee: float(),
  currency: String.t(),
  status: status(),
  reference: String.t(),
  narration: String.t(),
  customer: customer()
}
@type disbursement_status() :: %{
  type: transaction_type(),
  transaction_status: String.t(),
  transaction_date: DateTime.t(),
  channel: channel(),
  disbursement: disbursement()
}
@type error() :: {:error, %{reason: String.t(), details: %{}}}
@type misc_bank_account() :: %{
  code: String.t(),
  country: String.t(),
  name: String.t(),
  nibss_bank_code: String.t(),
  slug: String.t()
}
@type payer_bank_account() :: %{
  account_number: String.t(),
  account_name: String.t(),
  bank_name: String.t()
}
@type short_bank_account() :: %{bank: String.t(), account: String.t()}
@type status() :: :success | :pending | :processing | :expired | :failed
@type transaction() :: %{
  reference: String.t(),
  status: status(),
  type: transaction_type(),
  amount: float(),
  fee: float(),
  narration: String.t(),
  currency: String.t(),
  created_at: DateTime.t(),
  transaction_status: String.t(),
  callback_url: String.t(),
  meta: %{},
  customer: customer()
}
@type transaction_type() :: :collection | :disubursement
@type virtual_account() :: %{
  account_reference: String.t(),
  unique_id: String.t(),
  account_status: String.t(),
  created_at: DateTime.t(),
  currency: String.t(),
  bank_account: bank_account(),
  customer: customer()
}
Link to this type

virtual_bank_account_txn()

View Source
@type virtual_bank_account_txn() :: %{
  reference: String.t(),
  status: status(),
  amount: String.t(),
  fee: String.t(),
  currency: String.t(),
  description: String.t(),
  payer_bank_account: payer_bank_account()
}
Link to this type

virtual_bank_account_txn_response()

View Source
@type virtual_bank_account_txn_response() :: %{
  total_amount_received: 1000,
  account_number: String.t(),
  currency: String.t(),
  transactions: [virtual_bank_account_txn()],
  pagination: %{
    page: integer(),
    total: integer(),
    pageCount: integer(),
    totalPages: integer()
  }
}

Link to this section Functions

Link to this function

authorize_charge(txn_reference, auth_model, options)

View Source
@spec authorize_charge(String.t(), auth_model(), auth_options()) ::
  charge_response() | error()

Authorize a charge that is :processing.

examples

Examples

iex(1)> KoraPay.authorize_charge("test-txn", :otp, "12345")
iex(2)> KoraPay.authorize_charge("test-txn", :pin, "1234")
iex(3)> KoraPay.authorize_charge("test-txn", :avs, %{state: "Lagos", city: "Lekki", ...})

options

Options

  1. Required only if auth type is :pin
  2. Required only if auth type is :otp
  3. Required only if auth type is :avs
    • state
    • city
    • country
    • address
    • zip_codes
@spec balances() :: balance() | error()

Return account balances. (currently naira only)

examples

Examples

iex(1)> KoraPay.balances()
{:ok, %{"NGN" => %{"available_balance" => 946, "pending_balance" => 0}}}
Link to this function

charge_card(charge_data)

View Source
@spec charge_card(String.t()) :: charge_response() | error()

Create a charge on a card.

examples

Examples

enc_data = "test_encrypted_base64_data"

iex(1)> KoraPay.charge_card(enc_data)
{:ok, %{
    "amount" => 200,
    "amount_charged" => 200,
    "auth_model" => "OTP",
    "currency" => "NGN",
    "fee": 2.6,
    "vat": 0.2,
    "response_message" => "Please enter the OTP sent to your mobile number 080****** and email te**@rave**.com",
    "payment_reference"=> "1To64uTVkRcRA",
    "status" => "processing",
    "transaction_reference"=> "KPY-CA-b5Mit73shYeQ",
    "card" => {
      "card_type": "mastercard",
      "first_six": "539983",
      "last_four": "8381",
      "expiry": "10/31"
    }
  }
}
Link to this function

charge_status(reference)

View Source
@spec charge_status(String.t()) :: charge_status() | error()

Find the details of a charge by providing a reference.

examples

Examples

iex(1)> KoraPay.charge_status("test-txn")
{:ok, %{
        "amount" => "1000.00",
        "currency" => "NGN",
        "description" => "Fix Test Webhook",
        "fee" => nil,
        "reference" => "test-txn",
        "status" => "processing"
        }
  }
Link to this function

create_charge(amount, currency, narration, customer, reference \\ generate_reference(), charge_options \\ %{})

View Source
@spec create_charge(
  non_neg_integer(),
  String.t(),
  String.t(),
  customer(),
  String.t(),
  charge_options()
) :: charge_response() | error()

Create a generic payment.

see: https://docs.korapay.com/#f192d2e8-aab2-4f5a-98ef-fa0ed7e2d853

examples

Examples

iex(1)> KoraPay.create_charge(1000, "NGN", "test-xyz", %{email: "jycdmbhw@sharklasers.com"})
{:ok, %{
    "checkout_url" => "https://test-checkout.korapay.com/test-txn/pay",
    "reference" => "test-txn" # reference is automatically generated by library.
  }
}

charge-options

Charge options

  1. reference : transaction reference, if not provided, will be auto generated.
  2. charge_options: map of zero or more attributes.
  • :redirect_url: URL to redirect your customer when the transaction is complete.
  • :default_channel: channel that shows up when client modal is instantiated. E.g "bank_transfer"
  • :channels: Allowed payment channels for this transaction e.g ["card", "bank_transfer"]
Link to this function

create_virtual_bank_account(name, permanent, bvn, bank_code, customer, reference \\ generate_reference())

View Source
@spec create_virtual_bank_account(
  String.t(),
  boolean(),
  [String.t()],
  String.t(),
  customer(),
  String.t()
) :: virtual_account() | error()

Create a virutal bank account.

examples

Examples

iex(1)> KoraPay.create_virtual_bank_account("Steph James", true, ["12345678901"], "035", %{ "name" => "Don Alpha"})

options

Options

  1. reference : transaction reference, if not provided, will be auto generated. ##
Link to this function

disburse(amount, currency, bank_account, customer, reference \\ generate_reference(), type \\ "bank_account")

View Source

Payout to a bank account.

examples

Examples

iex(1)> bank_account = %{"bank" => "033", "account" => "0000000000"}
iex(2)> customer = %{"name" => "John Doe", "email" => "johndoe@korapay.com"}
iex(3)> KoraPay.disburse(1000, "NGN", bank_account, customer)
{:ok, %{
  "amount" => "100.00",
  "fee" => "2.50",
  "currency" => "NGN",
  "status" => "processing",
  "reference" => "KPY-D-t74azVrw9oPLtv9",
  "narration" => "Test Transfer Payment",
  "customer" => %{
    "name" => "John Doe",
    "email" => "johndoe@korapay.com"
    }
  }
}

options

Options

  • reference : transaction reference, if not provided, will be auto generated.
  • type : destination type. defaults to "bank_account"
@spec list_banks() :: [misc_bank_account()] | error()

All supported bank accounts.

example

Example

iex(1)> KoraPay.list_banks()
{:ok, [%{
  name: "First Bank of Nigeria",
  slug: "firstbank",
  code: "011",
  nibss_bank_code: "000016",
  country: "NG"
  }, ...]}
Link to this function

resolve_bank_account(bank_code, account_number)

View Source
@spec resolve_bank_account(String.t(), String.t()) :: bank_account() | error()

Verify a bank account.

examples

Examples

iex(1)> KoraPay.resolve_bank_account("058", "0234247896")
{:ok, %{
 "account_name" => "OLAEGBE GBENGA EMMANUEL",
 "account_number" => "0234247896",
 "bank_code" => "058",
 "bank_name" => "GTBank Plc"
}}
@spec transactions() :: [transaction()] | error()

All transactions for a client.

examples

Examples

iex(1)> KoraPay.transactions()
{:ok,  [
    %{
      "type" => "collection",
      "amount" => 1000,
      "fee" => 10,
      "narration" => "payment for a book",
      "currency" => "NGN",
      "created_at" => "2019-08-05T20:29:49.000Z",
      "status" => "success",
      "transaction_status" => "success",
      "reference" => "KPY-D-jLo7Zbk",
      "callback_url" => "https://example.com",
      "meta" => "{'product_name':'Becoming by Michelle Obama','product_description':''}",
      "customer" => %{
        "name" => "Timi Adesoji",
        "email" => "johndoe@korapay.com",
      }
    }, ...]}
Link to this function

verify_disbursement(reference)

View Source
@spec verify_disbursement(String.t()) :: disbursement_status() | error()

Check on a payout's status.

examples

Examples

iex(1)> KoraPay.verify_disbursement("KPY_jLo7Zbk")
{:ok, %{
      "amount" => 1000,
      "fee" => 10,
      "narration" => "payout to customer",
      "currency" => "NGN",
      "created_at" => "2019-08-05T20:29:49.000Z",
      "status" => "success",
      "reference" => "KPY_jLo7Zbk",
      "callback_url" => "https://example.com",
      "trace_id" => "000000000000000111111111111111",
      "message" => "Payout successful",
      "customer" => %{
      "name" => "John Doe",
      "email" => "johndoe@korapay.com",
    }
  }
}
Link to this function

virtual_bank_account_details(ref)

View Source
@spec virtual_bank_account_details(String.t()) :: virtual_account() | error()
Link to this function

virtual_bank_account_transactions(account_number)

View Source
@spec virtual_bank_account_transactions(account_number :: String.t()) ::
  [virtual_bank_account_txn_response()] | error()