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:
Action | Method | type |
---|---|---|
Pre-authorize | authorize/3 | PA |
Capture | capture/3 | CP |
Refund | refund/3 | RF |
Reversal | void/2 | RV |
Debit | purchase/3 | DB |
Tokenization / Registrations | store/2 |
What’s this last column
type
?
That’s thepaymentType
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:
Key | Remark | Status |
---|---|---|
billing_address | Not implemented | |
cart | Not implemented | |
currency | Implemented | |
customParameters | Not implemented | |
customer | Not implemented | |
invoice | Not implemented | |
merchant | Not implemented | |
shipping_address | Not implemented | |
shipping_customer | Not 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 parameter | MONEI secret |
---|---|
:userId | User ID |
:entityId | Channel ID |
:password | Password |
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
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.
- You could use the same config or update it the with your “secrets”
that you see in
Run an
iex
session withiex -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
-
- Credit
- Rebill
- Recurring payments
- Reporting
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
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
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)
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)
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)
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
orcapture/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)
WIP
MONEI unstore does not seem to work. MONEI always returns a 403
Deletes previously stored payment-source data.
Validates the config dynamically depending on what is the value of required_config
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)