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

Link to this function authorize(worker, gateway, amount, card, opts \\ [])

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)
Link to this function capture(worker, gateway, id, amount, opts \\ [])

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)
Link to this function purchase(worker, gateway, amount, card, opts \\ [])

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.

Link to this function refund(worker, gateway, amount, id, opts \\ [])

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)
Link to this function store(worker, gateway, card, opts \\ [])

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)
Link to this function unstore(worker, gateway, customer_id, opts \\ [])

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)
Link to this function void(worker, gateway, id, opts \\ [])

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)