Gringotts is a payment processing library in Elixir integrating various payment gateways, drawing motivation from Shopify'sactivemerchantgem andcommerce_billing.Checkout thedemo here.

Gringotts offers asimple and unified APIto access dozens of different payment gateways with very different APIs, response schemas, documentation and jargon.

The project started outas a fork ofcommerce_billingand the notable differences are:

1. NoGenServerprocess to act as a "payment worker".
2. Consistent docs and good amount of tests.
3. Support many more payment gateways.

Installation

Fromhex.pm

Addgringottsto the list of dependencies of your application.

# your mix.exs

defdepsdo
[
{:gringotts,"~> 1.1"},
# ex_money provides an excellent Money library, and integrates
# out-of-the-box with Gringotts
{:ex_money,">= 2.6.0"}
]
end

Usage

This simple example demonstrates how apurchasecan be made using a sample credit card using theMONEIgateway.

One must "register" their account withgringottsie, put all the authentication details in the Application config. Usually via config/config.exs

# config/config.exs

config:gringotts,Gringotts.Gateways.Monei,
userId:"your_secret_user_id",
password:"your_secret_password",
entityId:"your_secret_channel_id"

Copy and paste this code in a module or anIExsession, or use this handy .iex.exsfor all the bindings.

aliasGringotts.Gateways.Monei
aliasGringotts.CreditCard

# a fake sample card that will work now because the Gateway is by default
# in "test" mode.

card=%CreditCard{
first_name:"Harry",
last_name:"Potter",
number:"4200000000000000",
year:2099,month:12,
verification_code:"123",
brand:"VISA"
}

# a sum of $42
amount=Money.new(42,:USD)

caseGringotts.purchase(Monei,amount,card)do
{:ok,%{id:id}}->
IO.puts("Payment authorized, reference token: '#{id}' ")

{:error,%{status_code:error,raw:raw_response}}->
IO.puts("Error:#{error}\nRaw:\n#{raw_response}")
end

On theGringotts.Moneyprotocol and money representation

All financial applications must take proper care when representing money in their system. Using simplefloating values might lead to losses in the real world due tovarious reasons.

Most payment gateways are strict about the formatting of theamountin the request, hence we cannot render arbitrary floating amounts like $4.99999.Moreover, such amounts might mean something to your application but they don't have any value in the real world (since you can't charge someone for a fraction of a US cent).

Your applicationmust roundsuch amounts before invoking Gringottsand manage any remainders sensiblyyourself.

Gringotts may perform rounding using thehalf-even strategy, but it will discard remainders if any.

Supported "Money" libraries

Gringotts does not ship with any library to work with monies. You are free to choose any monie library you wish, as long as they implement the Gringotts.Moneyfor their type!

That said, we recommend [ex_money][ex_money] (abovev2.6.0) to represent monies. You just have to add it in yourdeps().

Supported Gateways

Gateway	PCI compliance	purchase	authorize	capture	void	refund	(card)store	(card)unstore
Authorize.Net	mandatory	✅	✅	✅	✅	✅	✅	✅
CAMS	mandatory	✅	✅	✅	✅	✅	❌	❌
MONEI	mandatory	✅	✅	✅	✅	✅	✅	❌
PAYMILL	optional	✅	✅	✅	✅	✅	❌	❌
Stripe	optional	✅	✅	✅	✅	✅	✅	✅
TREXLE	mandatory	✅	✅	✅	❌	✅	✅	❌

Road Map

Apart from supporting more and more gateways, we also keep a somewhat detailed plan for the future on ourwiki.

FAQ

1. What's with the name? "Gringotts"?

Gringotts has a nice ring to it. Alsothis.

License

MIT