Mpgs (mpgs v1.1.0)
This module deals with the MasterCard Payment Gateway Service (MPGS).
Check the MPGS API documentation for more details:
Summary
Functions
Use this function to start the payment process.
Use this function to capture (charge) the card.
Use this function to refund a paid transaction.
Retrieves details about an existing transaction.
Functions
authenticate_payment(params)
Use this function to start the payment process.
The value of the function is a piece of HTML that should be rendered on the client's browser.
This funciton takes a map and returns a tuple.
Available map keys:
api_username
. Required. Optional if there is an env variable calledMPGS_API_USERNAME
.api_password
. Required. Optional if there is an env variable calledMPGS_API_PASSWORD
.api_base
. Optional. Defaults to https://ap-gateway.mastercard.com/api/rest/version.api_version
. Optional. Defaults to 74.api_merchant
. Required.currency
. Optional. The 3-digit currency code. Defaults to KWD.amount
. Required. It must be a number that indicates the total amount to be paid.card_number
. Required. The 16-digit card number used for the payment.expiry_month
. Required. The card's 2-digit expiry month.expiry_year
. Required. The card's 2-digit expiry year.security_code
. Required. The card's 3-digit (or 4-digit) CVV code.order
. Required. The order number.trx
. Required. The transaction number.response_url
. Required. The URL that will receive the authentication response from the MPGS gateway.browser_agent
. Required. The user's browser agent string.full_page_redirect
. Optional. Iftrue
, this function will return a complete html document which can be rendered as a full page.
Return values:
{:ok, session, html}
. Thehtml
value should be rendered on the client's web browser. Thesession
should be used with thecapture_payment/1
function.{:error, exception}
. An error occurred while processing the authentication request.
Example:
params = %{
api_username: "my-mpgs-username",
api_password: "my-mpgs-password",
api_merchant: "my-mpgs-merchant",
amount: "15",
currency: "KWD",
card_number: "1234567890123456",
expiry_month: "10",
expiry_year: "25",
security_code: "123",
order: "0123456789",
trx: "0987654321",
response_url: "http://example.com/payment/mpgs/response/",
browser_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...Version/16.5.2 Safari/605.1.15",
full_page_redirect: true,
}
{:ok, session, html} = authenticate_payment(params)
# Send and render the html on client's browser.
# After a successful or a failed authentication attempt by the user,
# call the capture_payment/1 function.
params = Map.put(params, :session, session)
{:ok, result} = capture_payment(params)
capture_payment(params)
Use this function to capture (charge) the card.
This function must be used after the authenticate_payment/1
function.
Available map keys:
session
. Required. This is obtained from callingauthenticate_payment/1
first.currency
. Optional. Defaults toKWD
.amount
. Required. The same amount used with theauthenticate_payment/1
function.order
. Required. The same order number used with theauthenticate_payment/1
function.trx
. Required. The same transaction number used with theauthenticate_payment/1
function.api_username
. Required. Optional if there is an env variable calledMPGS_API_USERNAME
.api_password
. Required. Optional if there is an env variable calledMPGS_API_PASSWORD
.api_base
. Optional. Defaults to https://ap-gateway.mastercard.com/api/rest/version.api_version
. Optional. Defaults to 74.api_merchant
. Required.
refund_transaction(params)
Use this function to refund a paid transaction.
Available map keys:
order
. Required. The order number used with thecapture_payment/1
function.trx
. Required. The transaction number used with thecapture_payment/1
function.amount
. Required.api_username
. Required. Optional if there is an env variable calledMPGS_API_USERNAME
.api_password
. Required. Optional if there is an env variable calledMPGS_API_PASSWORD
.api_base
. Optional. Defaults to https://ap-gateway.mastercard.com/api/rest/version.api_version
. Optional. Defaults to 74.api_merchant
. Required.
Example:
order_params = %{
api_username: "my-mpgs-username",
api_password: "my-mpgs-password",
api_merchant: "my-mpgs-merchant",
order: "0123456789",
trx: "0987654321",
amount: "15",
currency: "KWD"
}
{:ok, response} = Mpgs.refund_transaction(params)
response["result"] #=> "SUCCESS"
response["order"]["status"] #=> "REFUNDED"
retrieve_transaction(params)
Retrieves details about an existing transaction.
Available map keys:
order
. Required. The same order number used with thecapture_payment/1
function.trx
. Required. The same transaction number used with thecapture_payment/1
function.api_username
. Required. Optional if there is an env variable calledMPGS_API_USERNAME
.api_password
. Required. Optional if there is an env variable calledMPGS_API_PASSWORD
.api_base
. Optional. Defaults to https://ap-gateway.mastercard.com/api/rest/version.api_version
. Optional. Defaults to 74.api_merchant
. Required.