Mpgs (mpgs v1.1.0)

This module deals with the MasterCard Payment Gateway Service (MPGS).

Check the MPGS API documentation for more details:

https://ap-gateway.mastercard.com/api/documentation/apiDocumentation/rest-json/version/latest/api.html?locale=en_US

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

Link to this function

authenticate_payment(params)

@spec authenticate_payment(map()) :: {:ok, String.t(), String.t()}

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 called MPGS_API_USERNAME.
  • api_password. Required. Optional if there is an env variable called MPGS_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. If true, this function will return a complete html document which can be rendered as a full page.

Return values:

  • {:ok, session, html}. The html value should be rendered on the client's web browser. The session should be used with the capture_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)
Link to this function

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:

Link to this function

refund_transaction(params)

Use this function to refund a paid transaction.

Available map keys:

  • order. Required. The order number used with the capture_payment/1 function.
  • trx. Required. The transaction number used with the capture_payment/1 function.
  • amount. Required.
  • api_username. Required. Optional if there is an env variable called MPGS_API_USERNAME.
  • api_password. Required. Optional if there is an env variable called MPGS_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"
Link to this function

retrieve_transaction(params)

Retrieves details about an existing transaction.

Available map keys:

  • order. Required. The same order number used with the capture_payment/1 function.
  • trx. Required. The same transaction number used with the capture_payment/1 function.
  • api_username. Required. Optional if there is an env variable called MPGS_API_USERNAME.
  • api_password. Required. Optional if there is an env variable called MPGS_API_PASSWORD.
  • api_base. Optional. Defaults to https://ap-gateway.mastercard.com/api/rest/version.
  • api_version. Optional. Defaults to 74.
  • api_merchant. Required.