@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.
• session. Optional. A new session will be created if this key does not exist.
• 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. Optional if the session is provided and it already contains the card data.
• expiry_month. Required. The card's 2-digit expiry month. Optional if the session is provided and it already contains the card data.
• expiry_year. Required. The card's 2-digit expiry year. Optional if the session is provided and it already contains the card data.
• security_code. Required. The card's 3-digit (or 4-digit) CVV code. Optional if the session is provided and it already contains the card data.
• 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.

If you are not PCI compliant, you should provide a session which already contains card details.

This session is obtained by the MPGS gateway through the Hosted Session Integration guide:

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",

  # include a session which contains card details:
  session: "SESSION2483924783297489234",
  # or include card details:
  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)

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 calling authenticate_payment/1 first.
• currency. Optional. Defaults to KWD.
• amount. Required. The same amount used with the authenticate_payment/1 function.
• order. Required. The same order number used with the authenticate_payment/1 function.
• trx. Required. The same transaction number used with the authenticate_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.

Returns true if the MPGS API is operational, false otherwise.

Available map keys:

• api_base. Optional. Defaults to https://ap-gateway.mastercard.com/api/rest/version.
• api_version. Optional. Defaults to 74.

Mpgs.check_connectivity()
true

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"

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.