Skip to content

Commit

Permalink
Updated public API docs
Browse files Browse the repository at this point in the history 
There's much t0d0 in here.

* Documented the amount section
  • Loading branch information
@oyeb
oyeb committed Jan 2, 2018
1 parent 47073d4 commit 03b8866
Showing 1 changed file with 37 additions and 42 deletions.
79 changes: 37 additions & 42 deletions lib/gringotts.ex
View file
Expand Up @@ -41,12 +41,20 @@ defmodule Gringotts do
This option specifies which payment gateway this request should be called for.
Since `Gringotts` supports multiple payment gateway integrations at the same time
so this information get's critical.
so this information gets critical.
### Amount
eg: 5000
### Amount _and currency_
eg:
%{amount: Decimal.new(42), currency: "USD"}
Amount is the money an application wants to deduct in cents on the card.
This argument represents the "amount", annotated with the currency unit for
which the transaction is being requested. `amount` is polymorphic thanks to
the `Gringotts.Money` protocol which can be implemented by your custom Money
type.
We support [`ex_money`][ex_money] and [`monetized`][monetized] out of the
box, and you can drop their types in this argument and everything will work
as expected.
### Card Info
eg:
Expand All @@ -66,21 +74,22 @@ defmodule Gringotts do
This stores all the credit card info of the customer along with some address info etc.
### Other options
eg: [currency: "usd"]
This is a keyword list of all the other options/information which the payment gateway
needs apart from the above mentioned options.
`opts` is a `keyword` list of other options/information which the
payment gateway needs apart from the above mandatory method arguments. These
are gateway specific options and you can see what's supported in the
gateway's docs.
> This is passed as is to the gateway and not modified, usually it comes back in the
response object intact.
[ex_money]: https://hexdocs.pm/ex_money/readme.html
[monetized]: https://hexdocs.pm/monetized/
"""

import GenServer, only: [call: 2]

@doc """
This is the bare minimum API for a gateway to support, and consists of a single call:
@payment %{
payment = %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
Expand All @@ -92,10 +101,8 @@ defmodule Gringotts do
country: "US",
postal_code: "11111"
}
@options [currency: "usd"]
Gringotts.purchase(Gringotts.Gateways.Stripe, 5, @payment, @options)
amount = %{amount: Decimal.new(4.99), currency: "USD"}
Gringotts.purchase(Gringotts.Gateways.Stripe, amount, payment)
This method is expected to authorize payment and transparently trigger eventual
settlement. Preferably it is implemented as a single call to the gateway,
Expand All @@ -112,7 +119,7 @@ defmodule Gringotts do
period of time. When implementing this API, authorize and capture are
both required.
@payment %{
payment = %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
Expand All @@ -124,10 +131,8 @@ defmodule Gringotts do
country: "US",
postal_code: "11111"
}
@options [currency: "usd"]
Gringotts.authorize(Gringotts.Gateways.Stripe, 5, @payment, @options)
amount = %{amount: Decimal.new(4.99), currency: "USD"}
Gringotts.authorize(Gringotts.Gateways.Stripe, amount, payment)
"""
def authorize(gateway, amount, card, opts \\ []) do
validate_config(gateway)
Expand All @@ -141,10 +146,11 @@ defmodule Gringotts do
Not passing an amount to capture should always cause the full amount of the initial
authorization to be captured.
If the gateway does not support partial captures, calling `capture` with an amount
other than nil should raise an error indicating partial capture is not supported.
If the gateway does not support partial captures, calling `capture` with a
`nil` amount should raise an error indicating partial capture is not
supported.
@payment %{
payment = %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
Expand All @@ -157,11 +163,9 @@ defmodule Gringotts do
postal_code: "11111"
}
@options [currency: "usd"]
amount = %{amount: Decimal.new(4.99), currency: "USD"}
id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
Gringotts.capture(Gringotts.Gateways.Stripe, id, 5)
Gringotts.capture(Gringotts.Gateways.Stripe, id, amount)
"""
def capture(gateway, id, amount, opts \\ []) do
validate_config(gateway)
Expand All @@ -173,7 +177,7 @@ defmodule Gringotts do
API that should immediately cancel an authorized charge, clearing it off of the
underlying payment instrument without waiting for expiration.
@payment %{
payment = %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
Expand All @@ -185,11 +189,7 @@ defmodule Gringotts do
country: "US",
postal_code: "11111"
}
@options [currency: "usd"]
id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
Gringotts.void(Gringotts.Gateways.Stripe, id)
"""
Expand All @@ -202,7 +202,7 @@ defmodule Gringotts do
Cancels settlement or returns funds as appropriate for a referenced prior
`purchase` or `capture`.
@payment %{
payment = %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
Expand All @@ -214,10 +214,9 @@ defmodule Gringotts do
country: "US",
postal_code: "11111"
}
amount = %{amount: Decimal.new(4.99), currency: "USD"}
id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
Gringotts.refund(Gringotts.Gateways.Stripe, 5, id)
Gringotts.refund(Gringotts.Gateways.Stripe, amount, id)
"""
def refund(gateway, amount, id, opts \\ []) do
validate_config(gateway)
Expand All @@ -235,7 +234,7 @@ defmodule Gringotts do
and `authorize`. Currently the standard is to return the token in the
`%Response{...}` `authorization` field.
@payment %{
payment = %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
Expand All @@ -247,10 +246,7 @@ defmodule Gringotts do
country: "US",
postal_code: "11111"
}
id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
Gringotts.store(Gringotts.Gateways.Stripe, @payment)
Gringotts.store(Gringotts.Gateways.Stripe, payment)
"""
def store(gateway, card, opts \\ []) do
validate_config(gateway)
Expand All @@ -264,8 +260,7 @@ defmodule Gringotts do
This should be done once the payment capture is done and you don't wish to make any
further deductions for the same card.
customer_id = "random_customer"
customer_id = "some_privileged_customer"
Gringotts.unstore(Gringotts.Gateways.Stripe, customer_id)
"""
def unstore(gateway, customer_id, opts \\ []) do
Expand Down

0 comments on commit 03b8866

Please sign in to comment.