gringotts v0.0.2 Gringotts.Gateways.Stripe

Stripe gateway implementation. For reference see Stripe’s API documentation. The following features of Stripe are implemented:

ActionMethod
Pre-authorizeauthorize/3
Capturecapture/3
Refundrefund/3
Reversalvoid/2
Debitpurchase/3
Storestore/2
Unstoreunstore/2

The opts argument

Most Gringotts API calls accept an optional Keyword list opts to supply optional arguments for transactions with the Stripe gateway. The following keys are supported:

KeyRemarkStatus
currencyImplemented
captureImplemented
descriptionImplemented
metadataImplemented
receipt_emailImplemented
shippingImplemented
customerImplemented
sourceImplemented
statement_descriptorImplemented
chargeImplemented
reasonImplemented
account_balanceNot implemented
business_vat_idNot implemented
couponNot implemented
default_sourceNot implemented
emailNot implemented
shippingNot implemented

Registering your Stripe account at Gringotts

After making an account on Stripe, head to the dashboard and find your account secrets in the API section.

Here’s how the secrets map to the required configuration parameters for Stripe:

Config parameterStripe secret
:secret_keySecret key

Your Application config must look something like this:

config :gringotts, Gringotts.Gateways.Stripe,
    adapter: Gringotts.Gateways.Stripe,
    secret_key: "your_secret_key",
    default_currency: "usd"

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 card with reference to a prior transfer

Stores the payment-source data for later use

Deletes previously stored payment-source data

Validates the config dynamically depending on what is the value of required_config

Voids the referenced payment

Link to this section Functions

Link to this function authorize(amount, payment, opts)
authorize(Float, Map, List) :: Map

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 also triggers risk management. Funds are not transferred.

Stripe returns an charge_id which should be stored at your side and can be used later to:

Note

Uncaptured charges expire in 7 days. For more information, see authorizing charges and settling later.

Example

The following session shows how one would (pre) authorize a payment of $10 on a sample card.

iex> payment = %{
      expiration: {2018, 12}, number: "4242424242424242", cvc:  "123", name: "John Doe",
      street1: "123 Main", street2: "Suite 100", city: "New York", region: "NY", country: "US",
      postal_code: "11111"
    }

iex> opts = [currency: "usd"]
iex> amount = 10

iex> Gringotts.authorize(:payment_worker, Gringotts.Gateways.Stripe, amount, payment, opts)
Link to this function capture(id, amount, opts)
capture(String.t(), Float, List) :: Map

Captures a pre-authorized amount.

Amount is transferred to the merchant account by Stripe when it is smaller or equal to the amount used in the pre-authorization referenced by charge_id.

Note

Stripe allows partial captures and release the remaining amount back to the payment source. Thus, the same pre-authorisation charge_id cannot be used to perform multiple captures.

Example

The following session shows how one would (partially) capture a previously authorized a payment worth $10 by referencing the obtained charge_id.

iex> id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
iex> amount = 5
iex> opts = []

iex> Gringotts.capture(:payment_worker, Gringotts.Gateways.Stripe, id, amount, opts)
Link to this function purchase(amount, payment, opts)
purchase(Float, Map, List) :: Map

Transfers amount from the customer to the merchant.

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

Example

The following session shows how one would process a payment in one-shot, without (pre) authorization.

iex> payemnt = %{
      expiration: {2018, 12}, number: "4242424242424242", cvc:  "123", name: "John Doe",
      street1: "123 Main", street2: "Suite 100", city: "New York", region: "NY", country: "US",
      postal_code: "11111"
    }

iex> opts = [currency: "usd"]
iex> amount = 5

iex> Gringotts.purchase(:payment_worker, Gringotts.Gateways.Stripe, amount, payment, opts)
Link to this function refund(amount, id, opts)
refund(Float, String.t(), List) :: Map

Refunds the amount to the customer’s card with reference to a prior transfer.

Stripe processes a full or partial refund worth amount, referencing a previous purchase/3 or capture/3.

Example

The following session shows how one would refund a previous purchase (and similarily for captures).

iex> amount = 5
iex> id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
iex> opts = []

iex> Gringotts.refund(:payment_worker, Gringotts.Gateways.Stripe, amount, id, opts)
Link to this function store(payment, opts)
store(Map, List) :: Map

Stores the payment-source data for later use.

Stripe can store the payment-source details, for example card which can be used to effectively to process One-Click and Recurring_ payments, and return a customer_id for reference.

Example

The following session shows how one would store a card (a payment-source) for future use.

iex> payment = %{
      expiration: {2018, 12}, number: "4242424242424242", cvc:  "123", name: "John Doe",
      street1: "123 Main", street2: "Suite 100", city: "New York", region: "NY", country: "US",
      postal_code: "11111"
    }

iex> opts = []

iex> Gringotts.store(:payment_worker, Gringotts.Gateways.Stripe, payment, opts)
Link to this function unstore(id, opts)

Deletes previously stored payment-source data.

Deletes the already stored payment source, so that it cannot be used again for capturing payments.

Examples

The following session shows how one would unstore a already stored payment source.

iex> id = "cus_BwpLX2x4ecEUgD"

iex> Gringotts.unstore(:payment_worker, Gringotts.Gateways.Stripe, id, opts)
Link to this function validate_config(config)

Validates the config dynamically depending on what is the value of required_config

Link to this function void(id, opts)
void(String.t(), List) :: Map

Voids the referenced payment.

This method attempts a reversal of the either a previous purchase/3 or authorize/3 referenced by charge_id. As a consequence, the customer will never see any booking on his statement.

Voiding a previous authorization

Stripe will reverse the authorization by sending a “reversal request” to the payment source (card issuer) to clear the funds held against the authorization.

Voiding a previous purchase

Stripe will reverse the payment, by sending all the amount back to the customer. Note that this is not the same as refund/3.

Example

The following session shows how one would void a previous (pre) authorization. Remember that our capture/3 example only did a partial capture.

iex> id = "ch_1BYvGkBImdnrXiZwet3aKkQE"
iex> opts = []

iex> Gringotts.void(:payment_worker, Gringotts.Gateways.Stripe, id, opts)