PAYMENT SELECTION PORTAL

1. PROJECT OVERVIEW

Payment Selection Portal is an ASP.NET Web Forms application developed
in VB.NET using .NET Framework 4.8.

The application allows a customer to:

1.  Open the payment selection page.
2.  Select one of five predefined payment options.
3.  Click the Pay button.
4.  Complete the payment through MyFatoorah.
5.  Return to the application after payment.
6.  Verify the payment status with MyFatoorah.
7.  View the final payment result.

The application is designed as a simple customer-facing payment page
without the default ASP.NET template navigation pages.

2. TECHNOLOGY USED

-   ASP.NET Web Forms
-   VB.NET
-   .NET Framework 4.8
-   MyFatoorah Kuwait Test API
-   Newtonsoft.Json
-   System.Net.Http
-   Visual Studio

3. PROJECT STRUCTURE

The main files used by the application are:

Default.aspx Customer payment selection page.

Default.aspx.vb Handles option selection, amount selection, and starts
the MyFatoorah payment process.

MyFatoorahService.vb Contains the MyFatoorah API integration. It creates
the payment and verifies the payment result.

PaymentResult.aspx Displays the payment result to the customer.

PaymentResult.aspx.vb Reads the payment ID returned by MyFatoorah,
verifies the payment, and displays the appropriate status.

Web.config Contains application configuration, including the MyFatoorah
API key.

packages.config Contains the NuGet package information required by the
project.

Global.asax ASP.NET application-level file.

4. PAYMENT OPTIONS

The application currently provides five payment options:

Option 1 - KWD 1.000 Option 2 - KWD 2.500 Option 3 - KWD 5.000 Option
4 - KWD 7.500 Option 5 - KWD 10.000

The selected amount is sent to MyFatoorah when the customer clicks Pay.

5. PAYMENT FLOW

The complete payment sequence is:

Customer opens Default.aspx | v Selects a payment option | v Clicks Pay
| v Application creates payment through MyFatoorah | v Customer is
redirected to MyFatoorah payment page | v Customer completes the payment
| v MyFatoorah redirects customer to PaymentResult.aspx | v Application
receives the Payment ID | v Application verifies the Payment ID with
MyFatoorah | v Transaction status is checked | v Payment result is
displayed

6. PAYMENT STATUS HANDLING

The application handles the following transaction statuses:

SUCCESS Displays “Payment Successful”.

FAILED Displays “Payment Failed”.

INPROGRESS Displays “Payment Pending”.

AUTHORIZE Displays “Payment Pending”.

CANCELED / CANCELLED Displays “Payment Cancelled”.

Any other status Displays “Payment Status Unknown”.

7. MYFATOORAH CONFIGURATION

The MyFatoorah API key is configured in Web.config.

Example:

Do not commit or publicly share a real API key.

The current project is configured for the MyFatoorah TEST environment.

Test API base URL:

https://apitest.myfatoorah.com

Before deployment, make sure the correct API key and environment are
configured for the intended environment.

8. PAYMENT METHOD

The current implementation uses MyFatoorah PaymentMethodId 2, which is
used for Visa/Mastercard card payments.

If the client later requires additional MyFatoorah payment methods, the
payment creation logic in MyFatoorahService.vb will need to be updated.

9. CALLBACK AND ERROR URL

After payment, MyFatoorah redirects the customer back to:

PaymentResult.aspx

The application uses the current website address to build the callback
and error URLs.

For local development, MyFatoorah normally requires a publicly
accessible URL for the callback. A public HTTPS tunnel such as ngrok can
be used during local testing.

For production, use the actual public HTTPS website URL.

10. HOW TO RUN THE PROJECT

1.  Open the PaymentSelectionPortal solution in Visual Studio.

2.  Make sure .NET Framework 4.8 is installed.

3.  Restore the NuGet packages if required.

4.  Open Web.config.

5.  Configure the MyFatoorah API key.

6.  Build the solution.

7.  Run the application.

8.  Open the payment selection page.

9.  Select one of the five options.

10. Click Pay.

11. Complete the payment using the MyFatoorah test payment environment.

12. Confirm that the application redirects to the Payment Result page.

13. TESTING COMPLETED

The payment flow has been tested with all five configured payment
amounts:

-   KWD 1.000
-   KWD 2.500
-   KWD 5.000
-   KWD 7.500
-   KWD 10.000

The following scenarios have also been tested:

-   Successful payment
-   Failed payment
-   Payment pending/in-progress handling
-   Payment result verification
-   Payment ID display
-   Correct payment amount display
-   Return to the payment selection page

12. SECURITY NOTES

-   Never expose the MyFatoorah API key in source code, screenshots,
    emails, GitHub repositories, or other public locations.
-   Use HTTPS for the production website.
-   Use a production MyFatoorah API key only when deploying to the
    production environment.
-   Do not display technical API errors directly to customers.
-   Keep the API key on the server side. It should not be placed in
    client-side JavaScript or HTML.

13. PRODUCTION DEPLOYMENT

Before deploying the application to production:

1.  Replace the test MyFatoorah API key with the correct production key.

2.  Change the MyFatoorah API base URL to the production environment.

3.  Set debug=“false” in Web.config.

4.  Use a public HTTPS domain.

5.  Confirm that the callback and error URLs point to the production
    website.

6.  Test a payment using the appropriate production/test procedure
    provided by the client and MyFatoorah.

7.  Confirm successful, failed, and cancelled payment handling.

8.  PROJECT CLEANUP

The unused ASP.NET template pages were removed from this project,
including:

-   About.aspx
-   Contact.aspx
-   Site.Master
-   Site.Mobile.Master
-   ViewSwitcher.ascx

The project now contains only the files required for the payment portal
and its ASP.NET application configuration.

15. TROUBLESHOOTING

Payment does not start: Check the MyFatoorah API key, internet
connection, and MyFatoorah API configuration.

Customer cannot return to the application: Check that the callback/error
URL is publicly accessible and correctly configured.

Payment result is not displayed: Check that MyFatoorah returned a
Payment ID and that the application can access the MyFatoorah payment
verification API.

Payment amount is incorrect: Check the selected option values in
Default.aspx and confirm that the selected value is being stored before
starting the payment.

Build errors occur: Restore the NuGet packages and make sure the project
targets .NET Framework 4.8.

16. IMPORTANT NOTE

This project is intended as a simple payment selection and MyFatoorah
integration application.

For a larger production system, it is recommended to add a
database/order record system so each customer order, selected option,
payment ID, amount, and payment status can be stored and tracked
independently of the user’s browser session.

17. CONTACT / MAINTENANCE

For future changes, the main files to modify are:

-   Default.aspx Change payment options and page design.

-   Default.aspx.vb Change payment selection and payment-start logic.

-   MyFatoorahService.vb Change MyFatoorah API integration.

-   PaymentResult.aspx Change payment result page design.

-   PaymentResult.aspx.vb Change payment result/status handling.

-   Web.config Change application and MyFatoorah configuration.
