View Source Gringotts (gringotts v1.1.1)

Gringotts is a payment gateway integration library for merchants

Gringotts provides a unified interface for multiple Payment Gateways to make it easy for merchants to use multiple gateways. All gateways must conform to the API as described in this module, but can also support more gateway features than those required by Gringotts.

standard-api-arguments

Standard API arguments

gateway-module-name

gateway (Module) Name

The gateway to which this request is made. This is required in all API calls because Gringotts supports multiple Gateways.

Example

If you've configured Gringotts to work with Stripe, you'll do this to make an authorization request:

Gringotts.authorize(Gingotts.Gateways.Stripe, other args ...)

amount-and-currency

amount and currency

This argument represents the "amount", annotated with the currency unit for the transaction. amount is polymorphic thanks to the Gringotts.Money protocol which can even be implemented by your very own custom Money type!

Currently, we support only ex_money's Money type. Please don't forget to add the ex_money lib to your deps!

Note

Gringotts supports ex_money out of the box, just drop ex_money types in this argument and everything will work as expected.

Support for monetized and money would be nice, but is currently not planned.

When this highly precise amount is serialized into the network request, we use a potentially lossy Gringotts.Money.to_string/1 or Gringotts.Money.to_integer/1 to perform rounding (if required) using the half-even strategy.

Hence, to protect your interests, and save real money, we STRONGLY RECOMMEND that (you) merchants perform any required rounding and handle remainders in their application logic -- before passing the amount to Gringotts's API.

Example

If you use ex_money in your project, and want to make an authorization for $2.99 to the XYZ Gateway, you'll do the following:

# the money lib is aliased as "MoneyLib"

amount = MoneyLib.new("2.99", :USD)
Gringotts.authorize(Gringotts.Gateways.XYZ, amount, some_card, extra_options)

card-a-payment-source

card, a payment source

Gringotts provides a Gringotts.CreditCard type to hold card parameters which merchants fetch from their clients. You (the merchant) needs to be PCI-DSS compliant to be able to use this.

The same type can also hold Debit card details.

Some gateways do not provide direct API integrations even for PCI compliant merchants, and force every merchant to use their client-side integration to generate a card token.

Thus for such gateways, Gringotts accepts a string card-token instead of (or in addition to) a CreditCard.t struct. Please refer the "Notes" section of your chosen gateway to find what the card argument accepts.

Note

Gringotts only supports payment by debit or credit card, even though the gateways might support payment via other instruments such as e-wallets, vouchers, bitcoins or banks. Support for these instruments is planned in future releases.

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

opts-for-optional-params

opts for optional params

opts is a keyword list of other options/information accepted by the gateway. The format, use and structure is gateway specific and documented in the Gateway's docs.

configuration

Configuration

Merchants must provide Gateway specific configuration in their application config in the usual elixir style. The required and optional fields are documented in every Gateway.

The required config keys are validated at runtime, as they include authentication information. See Gringotts.Adapter.validate_config/2.

global-config

Global config

This is set using the :global_config key once in your application.

:mode

Gateways usually provide sandboxed environments to test applications and the merchant can use the :mode switch to choose between the sandbox or live environment.

Available Options:

  • :test -- for sandbox environment, all requests will be routed to the gateway's sandbox/test API endpoints. Use this in your :dev and :test environments.
  • :prod -- for live environment, all requests will reach the financial and banking networks. Switch to this in your application's :prod environment.

Example

config :gringotts, :global_config,
    # for live environment
    mode: :prod

gateway-specific-config

Gateway specific config

The gateway level config is documented in their docs. They must be of the following format:

config :gringotts, Gringotts.Gateways.XYZ,
  # some_documented_key: associated_value
  # some_other_key: another_value

Link to this section Summary

Functions

Performs a (pre) Authorize operation.

Captures a pre-authorized amount.

Transfers amount from the customer to the merchant.

Refunds the amount to the customer's account with reference to a prior transfer.

Stores the payment-source data for later use, returns a token.

Removes a previously token from the gateway

Voids the referenced payment.

Link to this section Functions

Link to this function

authorize(gateway, amount, card, opts \\ [])

View Source

Performs a (pre) Authorize operation.

The authorization validates the card details with the banking network, places a hold on the transaction amount in the customer’s issuing bank and may also trigger risk management. Funds are not transferred, until the authorization is capture/3d.

capture/3 must also be implemented alongwith this.

example

Example

To (pre) authorize a payment of $4.20 on a sample card with the XYZ gateway,

amount = Money.new("4.2", :USD)
card = %Gringotts.CreditCard{
  first_name: "Harry",
  last_name: "Potter",
  number: "4200000000000000",
  year: 2099, month: 12,
  verification_code: "123",
  brand: "VISA"
}
{:ok, auth_result} = Gringotts.authorize(Gringotts.Gateways.XYZ, amount, card, opts)
Link to this function

capture(gateway, id, amount, opts \\ [])

View Source

Captures a pre-authorized amount.

amount is transferred to the merchant account. The gateway might support,

  • partial captures,
  • multiple captures, per authorization

example

Example

To capture $4.20 on a previously authorized payment worth $4.20 by referencing the obtained authorization id with the XYZ gateway,

auth_result # The result of an `authorize/3` request.
amount = Money.new("4.2", :USD)
Gringotts.capture(Gringotts.Gateways.XYZ, amount, auth_result.id, opts)
Link to this function

purchase(gateway, amount, card, opts \\ [])

View Source

Transfers amount from the customer to the merchant.

Gateway attempts to process a purchase on behalf of the customer, by debiting amount from the customer's account by charging the customer's card.

This method can be implemented as a chained call to authorize/3 and capture/3. But it must be implemented as a single call to the Gateway if it provides a specific endpoint or action for this.

*Note! All gateways must implement (atleast) this method.

example

Example

To process a purchase worth $4.2, with the XYZ gateway,

amount = Money.new("4.2", :USD)
card = %Gringotts.CreditCard{
  first_name: "Harry",
  last_name: "Potter",
  number: "4200000000000000",
  year: 2099, month: 12,
  verification_code: "123",
  brand: "VISA"
}
Gringotts.purchase(Gringotts.Gateways.XYZ, amount, card, opts)
Link to this function

refund(gateway, amount, id, opts \\ [])

View Source

Refunds the amount to the customer's account with reference to a prior transfer.

The end customer will usually see two bookings/records on his statement.

example

Example

To refund a previous purchase worth $4.20 referenced by id, with the XYZ gateway,

amount = Money.new("4.2", :USD)
Gringotts.purchase(Gringotts.Gateways.XYZ, amount, id, opts)
Link to this function

store(gateway, card, opts \\ [])

View Source

Stores the payment-source data for later use, returns a token.

The token must be returned in the Response.token field.

note

Note

This usually enables One-Click and Recurring payments.

example

Example

To store a card (a payment-source) for future use, with the XYZ gateway,

card = %Gringotts.CreditCard{
  first_name: "Harry",
  last_name: "Potter",
  number: "4200000000000000",
  year: 2099, month: 12,
  verification_code: "123",
  brand: "VISA"
}
Gringotts.store(Gringotts.Gateways.XYZ, card, opts)
Link to this function

unstore(gateway, token, opts \\ [])

View Source

Removes a previously token from the gateway

Once unstore/3d, the token must becom invalid, though some gateways might not support this feature.

example

Example

To unstore with the XYZ gateway,

token = "some_privileged_customer"
Gringotts.unstore(Gringotts.Gateways.XYZ, token)
Link to this function

void(gateway, id, opts \\ [])

View Source

Voids the referenced payment.

This method attempts a reversal/immediate cancellation of the a previous transaction referenced by id.

As a consequence, the customer usually won't see any booking on his statement.

example

Example

To void a previous (pre) authorization with the XYZ gateway,

id = "some_previously_obtained_token"
Gringotts.void(Gringotts.Gateways.XYZ, id, opts)