gringotts v0.0.2 Gringotts.Gateways.Monei

MONEI gateway implementation.

For reference see MONEI’s API (v1) documentation.

The following features of MONEI are implemented:

ActionMethodtype
Pre-authorizeauthorize/3PA
Capturecapture/3CP
Refundrefund/3RF
Reversalvoid/2RV
Debitpurchase/3DB
Tokenization / Registrationsstore/2

What’s this last column type?
That’s the paymentType of the request, which you can ignore unless you’d like to contribute to this module. Please read the MONEI Guides.

The opts argument

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

KeyRemarkStatus
billing_addressNot implemented
cartNot implemented
currencyImplemented
customParametersNot implemented
customerNot implemented
invoiceNot implemented
merchantNot implemented
shipping_addressNot implemented
shipping_customerNot implemented

All these keys are being implemented, track progress in issue #36!

Registering your MONEI account at Gringotts

After making an account on MONEI, head to the dashboard and find your account “secrets” in the Sub-Accounts > Overview section.

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

Config parameterMONEI secret
:userIdUser ID
:entityIdChannel ID
:passwordPassword

Your Application config must include the :userId, :entityId, :password fields and would look something like this:

config :gringotts, Gringotts.Gateways.Monei,
  adapter: Gringotts.Gateways.Monei,
  userId: "your_secret_user_id",
  password: "your_secret_password",
  entityId: "your_secret_channel_id"

Scope of this module, and quirks

  • MONEI does not process money in cents, and the amount is rounded to 2 decimal places.
  • Although MONEI supports payments from various cards, banks and virtual accounts (like some wallets), this library only accepts payments by (supported) cards.

Following the examples

  1. First, set up a sample application and configure it to work with MONEI.

    • You could do that from scratch by following our Getting Started guide.
    • To save you time, we recommend cloning our example repo that gives you a pre-configured sample app ready-to-go.

      • You could use the same config or update it the with your “secrets” that you see in Dashboard > Sub-accounts as described above.
  2. Run an iex session with iex -S mix and add some variable bindings and aliases to it (to save some time):

iex> alias Gringotts.{Response, CreditCard, Gateways.Monei}
iex> opts = [currency: "EUR"] # The default currency is EUR, and this is just for an example.
iex> card = %CreditCard{first_name: "Jo",
                        last_name: "Doe",
                        number: "4200000000000000",
                        year: 2019, month: 12,
                        verification_code:  "123", brand: "VISA"}

We’ll be using these in the examples below.

TODO

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

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, card, opts)
authorize(number(), Gringotts.CreditCard, keyword()) :: Gringotts.Response

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.

MONEI returns an ID string which can be used to:

Note

A stand-alone pre-authorization expires in 72hrs.

Example

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

iex> opts = [currency: "EUR"] # The default currency is EUR, and this is just for an example.
iex> card = %Gringotts.CreditCard{first_name: "Jo", last_name: "Doe", number: "4200000000000000", year: 2019, month: 12, verification_code:  "123", brand: "VISA"}
iex> auth_result = Gringotts.authorize(:payment_worker, Gringotts.Gateways.Monei, 40, card, opts)
iex> auth_result.id # This is the authorization ID
Link to this function capture(amount, paymentId, opts)
capture(number(), String.t(), keyword()) :: Gringotts.Response

Captures a pre-authorized amount.

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

Note

MONEI allows partial captures and unlike many other gateways, does not release the remaining amount back to the payment source. Thus, the same pre-authorisation ID can be used to perform multiple captures, till:

  • all the pre-authorized amount is captured or,
  • the remaining amount is explicitly “reversed” via void/2. [citation-needed]

Example

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

iex> opts = [currency: "EUR"] # The default currency is EUR, and this is just for an example.
iex> card = %Gringotts.CreditCard{first_name: "Jo", last_name: "Doe", number: "4200000000000000", year: 2019, month: 12, verification_code:  "123", brand: "VISA"}
iex> capture_result = Gringotts.capture(:payment_worker, Gringotts.Gateways.Monei, 35, auth_result.id, opts)
Link to this function purchase(amount, card, opts)
purchase(number(), Gringotts.CreditCard, keyword()) :: Gringotts.Response

Transfers amount from the customer to the merchant.

MONEI 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> opts = [currency: "EUR"] # The default currency is EUR, and this is just for an example.
iex> card = %Gringotts.CreditCard{first_name: "Jo", last_name: "Doe", number: "4200000000000000", year: 2019, month: 12, verification_code:  "123", brand: "VISA"}
iex> purchase_result = Gringotts.purchase(:payment_worker, Gringotts.Gateways.Monei, 40, card, opts)
Link to this function refund(amount, paymentId, opts)
refund(number(), String.t(), keyword()) :: Gringotts.Response

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

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

The end customer will always see two bookings/records on his statement. Refer MONEI’s Backoffice Operations guide.

Example

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

iex> opts = [currency: "EUR"] # The default currency is EUR, and this is just for an example.
iex> card = %Gringotts.CreditCard{first_name: "Jo", last_name: "Doe", number: "4200000000000000", year: 2019, month: 12, verification_code:  "123", brand: "VISA"}
iex> refund_result = Gringotts.refund(:payment_worker, Gringotts.Gateways.Monei, purchase_result.id, opts)
Link to this function store(card, opts)
store(Gringotts.CreditCard, keyword()) :: Gringotts.Response

Stores the payment-source data for later use.

MONEI can store the payment-source details, for example card or bank details which can be used to effectively process One-Click and Recurring payments, and return a registration token for reference.

It is recommended to associate these details with a “Customer” by passing customer details in the opts.

Note

  • One-Click and Recurring payments are currently not implemented.
  • Payment details can be saved during a purchase/3 or capture/3.

Example

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

iex> opts = [currency: "EUR"] # The default currency is EUR, and this is just for an example.
iex> card = %Gringotts.CreditCard{first_name: "Jo", last_name: "Doe", number: "4200000000000000", year: 2019, month: 12, verification_code:  "123", brand: "VISA"}
iex> store_result = Gringotts.store(:payment_worker, Gringotts.Gateways.Monei, card, opts)
Link to this function unstore(arg1, opts)
unstore(String.t(), keyword()) :: Gringotts.Response

WIP

MONEI unstore does not seem to work. MONEI always returns a 403

Deletes previously stored payment-source data.

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(paymentId, opts)
void(String.t(), keyword()) :: Gringotts.Response

Voids the referenced payment.

This method attempts a reversal of the either a previous purchase/3 or authorize/3 referenced by paymentId.

As a consequence, the customer will never see any booking on his statement. Refer MONEI’s Backoffice Operations guide.

Voiding a previous authorization

MONEI will reverse the authorization by sending a “reversal request” to the payment source (card issuer) to clear the funds held against the authorization. If some of the authorized amount was captured, only the remaining amount is cleared. [citation-needed]

Voiding a previous purchase

MONEI 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> opts = [currency: "EUR"] # The default currency is EUR, and this is just for an example.
iex> card = %Gringotts.CreditCard{first_name: "Jo", last_name: "Doe", number: "4200000000000000", year: 2019, month: 12, verification_code:  "123", brand: "VISA"}
iex> void_result = Gringotts.void(:payment_worker, Gringotts.Gateways.Monei, auth_result.id, opts)