Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aviabird/gringotts

A complete payment library for Elixir and Phoenix Framework
https://github.com/aviabird/gringotts

billing elixir elixir-phoenix gateway gringotts payment payment-gateway payments stripe

Last synced: about 2 months ago
JSON representation

A complete payment library for Elixir and Phoenix Framework

Host: GitHub
URL: https://github.com/aviabird/gringotts
Owner: aviabird
License: mit
Created: 2017-12-19T06:52:13.000Z (almost 7 years ago)
Default Branch: dev
Last Pushed: 2024-01-30T23:08:10.000Z (8 months ago)
Last Synced: 2024-07-23T19:23:56.943Z (about 2 months ago)
Topics: billing, elixir, elixir-phoenix, gateway, gringotts, payment, payment-gateway, payments, stripe
Language: Elixir
Homepage: https://hexdocs.pm/gringotts/Gringotts.html
Size: 948 KB
Stars: 478
Watchers: 36
Forks: 53
Open Issues: 38
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE

Awesome Lists containing this project

freaking_awesome_elixir - Elixir - A complete payment library for Elixir and Phoenix Framework similar to [ActiveMerchant](https://github.com/activemerchant/active_merchant) from the Ruby world. (Third Party APIs)
awesome-fintech - Gringotts - a simple and unified API to access dozens of different payment gateways with very different APIs, response schemas, documentation, and jargon (Other)
fucking-awesome-elixir - gringotts - A complete payment library for Elixir and Phoenix Framework similar to [ActiveMerchant](https://github.com/activemerchant/active_merchant) from the Ruby world. (Third Party APIs)
awesome-elixir - gringotts - A complete payment library for Elixir and Phoenix Framework similar to [ActiveMerchant](https://github.com/activemerchant/active_merchant) from the Ruby world. (Third Party APIs)

README

        


  

    

  





  Gringotts is a payment processing library in Elixir integrating various payment gateways, drawing motivation from Shopify's activemerchant gem and commerce_billing. Checkout the demo here.





      

 



Gringotts offers a **simple and unified API** to access dozens of different payment

gateways with very different APIs, response schemas, documentation and jargon.

The project started out **as a fork of [`commerce_billing`][commerce-billing]** and

the notable differences are:

1. No `GenServer` process to act as a "payment worker".

2. Consistent docs and good amount of tests.

3. Support many more payment gateways.

[commerce-billing]: https://github.com/joshnuss/commerce_billing

## Installation

### From [`hex.pm`][hexpm]

Add `gringotts` to the list of dependencies of your application.

```elixir

# your mix.exs

def deps do

  [

    {: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 a `purchase` can be made using a sample

credit card using the [MONEI][monei] gateway.

One must "register" their account with `gringotts` ie, put all the

authentication details in the Application config. Usually via

`config/config.exs`

```elixir

# 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 an `IEx` session, or use this handy

[`.iex.exs`][monei-bindings] for all the bindings.

```elixir

alias Gringotts.Gateways.Monei

alias Gringotts.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)

case Gringotts.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

```

[hexpm]: https://hex.pm/packages/gringotts

[monei]: http://www.monei.net

[monei-bindings]: https://gist.github.com/oyeb/a2e2ac5986cc90a12a6136f6bf1357e5

## On the `Gringotts.Money` protocol and money representation

All financial applications must take proper care when representing money in

their system. Using simple `float`ing values might lead to losses in the real

world due to [various reasons][floating-issues].

Most payment gateways are strict about the formatting of the `amount` in 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 application **must round** such amounts before invoking Gringotts **and manage

any remainders sensibly** yourself.

> Gringotts may perform rounding using the [`half-even`][wiki-half-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.Money`][protocol] for their type!

That said, we recommend [`ex_money`][ex_money] (above [`v2.6.0`][2_6_0]) to

represent monies. You just have to add it in your `deps()`.

[protocol]: https://github.com/aviabird/gringotts/blob/dev/lib/gringotts/money.ex

[floating-issues]: https://elixirforum.com/t/comparison-of-decimals-not-logical/770/21

[wiki-half-even]: https://en.wikipedia.org/wiki/Rounding#Round_half_to_even

[ex-money]: https://github.com/kipcole9/money

[2_6_0]: https://github.com/kipcole9/money/releases/tag/v2.6.0

## Supported Gateways

| Gateway               | PCI compliance | `purchase` | `authorize` | `capture` | `void`   | `refund` | (card) `store` | (card) `unstore` |

|-----------------------|----------------|------------|-------------|-----------|----------|----------|----------------|------------------|

| [Authorize.Net][anet] | mandatory      | ✅    | ✅     | ✅   | ✅  | ✅  | ✅        | ✅          |

| [CAMS][cams]          | mandatory      | ✅    | ✅     | ✅   | ✅  | ✅  | ❌       | ❌         |

| [MONEI][monei]        | mandatory      | ✅    | ✅     | ✅   | ✅  | ✅  | ✅        | ❌         |

| [PAYMILL][paymill]    | optional       | ✅    | ✅     | ✅   | ✅  | ✅  | ❌       | ❌         |

| [Stripe][stripe]      | optional       | ✅    | ✅     | ✅   | ✅  | ✅  | ✅        | ✅          |

| [TREXLE][trexle]      | mandatory      | ✅    | ✅     | ✅   | ❌ | ✅  | ✅        | ❌         |

[anet]: http://www.authorize.net/

[cams]: https://www.centralams.com/

[monei]: http://www.monei.net/

[paymill]: https://www.paymill.com

[stripe]: https://www.stripe.com/

[trexle]: https://www.trexle.com/

[wirecard]: http://www.wirecard.com

[demo]: https://gringottspay.herokuapp.com/

## [Road Map][roadmap]

Apart from supporting more and more gateways, we also keep a somewhat detailed

plan for the future on our [wiki][roadmap].

## FAQ

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

Gringotts has a nice ring to it. Also [this][reason].

[reason]: http://harrypotter.wikia.com/wiki/Gringotts

## License

MIT

[roadmap]: https://github.com/aviabird/gringotts/wiki/Roadmap