defmodule KoraPay do
@moduledoc """
KoraPay client wrapper (https://docs.korapay.com/).
## 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
```
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
```
"""
### Entities ###
@type card :: %{
card_type: :mastercard | :visa | :verve,
first_six: String.t(),
last_four: String.t(),
expiry: String.t()
}
@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 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()
}
@type customer :: %{
required(: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 charge_reference :: %{reference: String.t(), checkout_url: String.t()}
# Auth
@type auth_model :: :otp | :three_ds | :avs | :pin
# Transaction types
@type balance :: %{
NGN: %{
pending_balance: float(),
available_balance: float()
}
}
@type status :: :success | :pending | :processing | :expired | :failed
@type transaction_type :: :collection | :disubursement
@type channel :: :card | :bank_transfer
### Bank Account Types ###
@type bank_account :: %{
bank_name: String.t(),
bank_code: String.t(),
account_number: String.t(),
account_name: String.t()
}
@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()
}
@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 misc_bank_account :: %{
code: String.t(),
country: String.t(),
name: String.t(),
nibss_bank_code: String.t(),
slug: String.t()
}
### API Types ###
@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 disbursement_status :: %{
type: transaction_type(),
transaction_status: String.t(),
transaction_date: DateTime.t(),
channel: channel(),
disbursement: disbursement()
}
@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 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()
}
}
### Helper Types
@type charge_options :: %{
optional(:redirect_url) => String.t(),
optional(:channels) => [channel()],
optional(:default_channel) => channel()
}
@type auth_options ::
String.t()
| %{
state: String.t(),
city: String.t(),
country: String.t(),
address: String.t(),
zip_codes: String.t()
}
@type error :: {:error, %{reason: String.t(), details: %{}}}
@doc """
Create a generic payment.
see: https://docs.korapay.com/#f192d2e8-aab2-4f5a-98ef-fa0ed7e2d853
## 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
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"]`
"""
@spec create_charge(
non_neg_integer(),
String.t(),
String.t(),
customer(),
String.t(),
charge_options()
) :: charge_response() | error()
def create_charge(
amount,
currency,
narration,
customer,
reference \\ generate_reference(),
charge_options \\ %{}
) do
params =
Map.merge(
%{
amount: to_string(amount),
currency: currency,
reference: reference,
notification_url: Application.get_env(:kora_pay, :webhook_url),
narration: narration,
customer: customer
},
charge_options
)
impl().create_charge(params)
end
@doc """
Find the details of a charge by providing a reference.
## 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"
}
}
```
"""
@spec charge_status(String.t()) :: charge_status() | error()
def charge_status(reference), do: impl().charge_status(reference)
@doc """
Authorize a [charge](./KoraPay.html#charge_card/1) that is `:processing`.
## 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
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 authorize_charge(String.t(), auth_model(), auth_options()) ::
charge_response() | error()
def authorize_charge(txn_reference, auth_model, options) do
auth =
case auth_model do
:avs -> %{avs: options}
:otp -> %{otp: options}
:pin -> %{pin: options}
end
params = %{
transaction_reference: txn_reference,
authorization: auth
}
impl().authorize_charge(params)
end
@doc """
Create a charge on a card.
## 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"
}
}
}
```
"""
@spec charge_card(String.t()) :: charge_response() | error()
def charge_card(charge_data), do: impl().charge_card(charge_data)
@doc """
Payout to a bank account.
## 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
- `reference` : transaction reference, if not provided, will be auto generated.
- `type` : destination type. defaults to `"bank_account"`
"""
@spec disburse(non_neg_integer(), String.t(), bank_account(), customer(), String.t()) ::
disbursement() | error()
def disburse(
amount,
currency,
bank_account,
customer,
reference \\ generate_reference(),
type \\ "bank_account"
) do
params = %{
reference: reference,
destination: %{
type: type,
amount: to_string(amount),
currency: currency,
bank_account: bank_account,
customer: customer
}
}
impl().disburse(params)
end
@doc """
Check on a payout's status.
## 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",
}
}
}
```
"""
@spec verify_disbursement(String.t()) :: disbursement_status() | error()
def verify_disbursement(reference), do: impl().verify_disbursement(reference)
@doc """
All transactions for a client.
## 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",
}
}, ...]}
```
"""
@spec transactions() :: [transaction()] | error()
def transactions, do: impl().transactions()
@doc """
Verify a bank account.
## 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 resolve_bank_account(String.t(), String.t()) :: bank_account() | error()
def resolve_bank_account(bank_code, account_number) do
params = %{
bank: bank_code,
account: account_number
}
impl().resolve_bank_account(params)
end
@doc """
All supported bank accounts.
## Example
```
iex(1)> KoraPay.list_banks()
{:ok, [%{
name: "First Bank of Nigeria",
slug: "firstbank",
code: "011",
nibss_bank_code: "000016",
country: "NG"
}, ...]}
```
"""
@spec list_banks() :: [misc_bank_account()] | error()
def list_banks, do: impl().list_banks()
@doc """
Return account balances. (currently naira only)
## Examples
```
iex(1)> KoraPay.balances()
{:ok, %{"NGN" => %{"available_balance" => 946, "pending_balance" => 0}}}
```
"""
@spec balances :: balance() | error()
def balances, do: impl().balances()
@doc """
Create a virutal bank account.
## Examples
```
iex(1)> KoraPay.create_virtual_bank_account("Steph James", true, ["12345678901"], "035", %{ "name" => "Don Alpha"})
```
## Options
1. `reference` : transaction reference, if not provided, will be auto generated.
##
"""
@spec create_virtual_bank_account(
String.t(),
boolean(),
[String.t()],
String.t(),
customer(),
String.t()
) ::
virtual_account() | error()
def create_virtual_bank_account(
name,
permanent,
bvn,
bank_code,
customer,
reference \\ generate_reference()
) do
params = %{
account_name: name,
account_reference: reference,
permanent: permanent,
bvn: bvn,
bank_code: bank_code,
customer: customer
}
impl().create_virtual_bank_account(params)
end
@spec virtual_bank_account_details(String.t()) :: virtual_account() | error()
def virtual_bank_account_details(ref), do: impl().virtual_bank_account_details(ref)
@spec virtual_bank_account_transactions(account_number :: String.t()) ::
[virtual_bank_account_txn_response()] | error()
def virtual_bank_account_transactions(account_number) do
impl().virtual_bank_account_transactions(%{account_number: account_number})
end
defp generate_reference, do: UUID.uuid4(:slug)
defp impl, do: Application.get_env(:kora_pay, :api, KoraPay.Client)
end
