gringotts v0.0.2 Gringotts
Gringotts is a payment gateway integration library supporting many gateway integrations.
Configuration
The configuration for Gringotts
must be in your application environment,
usually defined in your config/config.exs
and are mandatory:
Global Configuration
The global configuration sets the library level configurations to interact with the gateway. If the mode is not set then by ‘default’ the sandbox account is selected.
To integrate with the sandbox account set.
config :gringotts, :global_config,
mode: :test
To integrate with the live account set.
config :gringotts, :global_config,
mode: :prod
Gateway Configuration
The gateway level configurations are for fields related to a specific gateway.
config :Gringotts, Gringotts.Gateways.Stripe,
adapter: Gringotts.Gateways.Stripe,
api_key: "sk_test_vIX41hC0sdfBKrPWQerLuOMld",
default_currency: "USD"
Key
for the configuration and the adapter value should be the same, we could have
chosen to pick adapter and used it as the key but we have chosen to be explicit rather
than implicit.
Standard Arguments
The public API is designed in such a way that library users end up passing mostly a standard params for almost all requests.
Worker Name
eg: :payment_worker
The standard central supervised worker responsible for delegating/calling all
the payment specific methods such as authorise
& purchase
.
> This option is going to be removed in our next version.
Gateway Name
eg: Gringotts.Gateways.Stripe
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.
Amount
eg: 5000
Amount is the money an application wants to deduct in cents on the card.
Card Info
eg:
%CreditCard {
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
cvc: "123",
street1: "123 Main",
street2: "Suite 100",
city: "New York",
region: "NY",
country: "US",
postal_code: "11111"
}
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.
> This is passed as is to the gateway and not modified, usually it comes back in the response object intact.
Link to this section Summary
Functions
Authorize should authorize funds on a payment instrument that will
not be settled without a following call to capture
within some finite
period of time. When implementing this API, authorize and capture are
both required
Captures deducts an amount from the card, this happens once the card is authorised
This is the bare minimum API for a gateway to support, and consists of a single call
Cancels settlement or returns funds as appropriate for a referenced prior
purchase
or capture
Tokenizes a supported payment method in the gateway’s vault. If the gateway
conflates tokenization with customer management, Gringotts
should hide all
customer management and any customer identifier(s) within the token returned.
It’s certainly legitimate to have a library that interacts with all the features
in a gateway’s vault, but Gringotts
is not the right place for it
Removes the token from the payment gateway, once unstore
request is fired the
token which could enable authorise
& capture
would not work with this token
Void is an optional (but highly recommended) supplement to authorise
& capture
API that should immediately cancel an authorized charge, clearing it off of the
underlying payment instrument without waiting for expiration
Link to this section Functions
Authorize should authorize funds on a payment instrument that will
not be settled without a following call to capture
within some finite
period of time. When implementing this API, authorize and capture are
both required.
@payment %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
cvc: "123",
street1: "123 Main",
street2: "Suite 100",
city: "New York",
region: "NY",
country: "US",
postal_code: "11111"
}
@options [currency: "usd"]
Gringotts.authorize(:payment_worker, Gringotts.Gateways.Stripe, 5, @payment, @options)
Captures deducts an amount from the card, this happens once the card is authorised.
Partial captures, if supported by the gateway, are achieved by passing an amount. 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.
@payment %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
cvc: "123",
street1: "123 Main",
street2: "Suite 100",
city: "New York",
region: "NY",
country: "US",
postal_code: "11111"
}
@options [currency: "usd"]
id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
Gringotts.capture(:payment_worker, Gringotts.Gateways.Stripe, id, 5)
This is the bare minimum API for a gateway to support, and consists of a single call:
@payment %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
cvc: "123",
street1: "123 Main",
street2: "Suite 100",
city: "New York",
region: "NY",
country: "US",
postal_code: "11111"
}
@options [currency: "usd"]
Gringotts.purchase(:payment_worker, Gringotts.Gateways.Stripe, 5, @payment, @options)
This method is expected to authorize payment and transparently trigger eventual
settlement. Preferably it is implemented as a single call to the gateway,
but it can also be implemented as chained authorize
and capture
calls.
Cancels settlement or returns funds as appropriate for a referenced prior
purchase
or capture
.
@payment %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
cvc: "123",
street1: "123 Main",
street2: "Suite 100",
city: "New York",
region: "NY",
country: "US",
postal_code: "11111"
}
id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
Gringotts.refund(:payment_worker, Gringotts.Gateways.Stripe, 5, id)
Tokenizes a supported payment method in the gateway’s vault. If the gateway
conflates tokenization with customer management, Gringotts
should hide all
customer management and any customer identifier(s) within the token returned.
It’s certainly legitimate to have a library that interacts with all the features
in a gateway’s vault, but Gringotts
is not the right place for it.
It’s critical that store
returns a token that can be used against purchase
and authorize
. Currently the standard is to return the token in the
%Response{...}
authorization
field.
@payment %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
cvc: "123",
street1: "123 Main",
street2: "Suite 100",
city: "New York",
region: "NY",
country: "US",
postal_code: "11111"
}
id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
Gringotts.store(:payment_worker, Gringotts.Gateways.Stripe, @payment)
Removes the token from the payment gateway, once unstore
request is fired the
token which could enable authorise
& capture
would not work with this token.
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"
Gringotts.unstore(:payment_worker, Gringotts.Gateways.Stripe, customer_id)
Void is an optional (but highly recommended) supplement to authorise
& capture
API that should immediately cancel an authorized charge, clearing it off of the
underlying payment instrument without waiting for expiration.
@payment %{
name: "John Doe",
number: "4242424242424242",
expiration: {2018, 12},
cvc: "123",
street1: "123 Main",
street2: "Suite 100",
city: "New York",
region: "NY",
country: "US",
postal_code: "11111"
}
@options [currency: "usd"]
id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
Gringotts.void(:payment_worker, Gringotts.Gateways.Stripe, id)