CUSTOMER PAYMENT PORTAL
CLIENT-FRIENDLY README
======================

1. PURPOSE
-----------
This document explains the complete Customer Payment Portal payment
flow. It identifies the exact page or code file responsible for each
step, the information sent to MyFatoorah, how it is sent, what
MyFatoorah returns, how the payment is verified, how the fixed-length
record is updated, and who receives email/SMS notifications.

Application: ASP.NET Web Forms
Framework: .NET Framework 4.8
Language: VB.NET
Payment Provider: MyFatoorah Hosted Payment Page
Environment: MyFatoorah Test Environment

The Customer Payment Portal does NOT collect or store card details.
Card details are entered on the MyFatoorah Hosted Payment Page.


2. CUSTOMER PAYMENT PAGE
------------------------
Customer-facing page:
    Default.aspx

The customer enters/selects:
    Payment Option
    Customer Name
    Email
    Mobile Number

Current payment options:
    Option 1 - 1 KWD
    Option 2 - 5 KWD
    Option 3 - 10 KWD
    Option 4 - 20 KWD
    Option 5 - 50 KWD


3. CUSTOMER VALIDATION
----------------------
Customer-side validation is performed by JavaScript before the
server-side payment process.

It checks:
    - Payment option selected.
    - Customer Name entered.
    - Email entered and valid.
    - Mobile Number entered and valid.

Server-side validation is also performed by:
    Default.aspx.vb


4. INITIAL PAYMENT RECORD
-------------------------
After validation, Default.aspx.vb creates a record in:

    App_Data\PaymentRecords.txt

Initial values:
    PaymentStatus = PENDING
    PaymentId     = Empty
    InvoiceId     = Empty
    EmailSent     = FALSE
    SmsSent       = FALSE

The PENDING record is created before the customer is redirected to
MyFatoorah.


5. FIXED-LENGTH RECORD FORMAT
-----------------------------
Each record is exactly 650 characters.

Defined fields = 320 characters.
Reserved space = 330 characters.

Field                         Size
------------------------------------------------
OrderId                       10 characters
CustomerName                  50 characters
Email                        100 characters
Mobile                        20 characters
OptionName                    30 characters
Amount                        15 characters
PaymentId                     30 characters
InvoiceId                     20 characters
PaymentStatus                 15 characters
CreatedDate                   20 characters
EmailSent                      5 characters
SmsSent                        5 characters
Reserved Space               330 characters
------------------------------------------------
Total                        650 characters

The 330 reserved characters are currently blank and are not separate
named fields. They are reserved for future expansion.


6. WHO SENDS THE PAYMENT REQUEST?
----------------------------------
The customer page is:
    Default.aspx

The server-side code is:
    Default.aspx.vb

The MyFatoorah communication code is:
    MyFatoorahService.vb

The sequence is:

    Customer
       |
       v
    Default.aspx
       |
       v
    Default.aspx.vb
       |
       v
    MyFatoorahService.vb
       |
       v
    MyFatoorah


7. HOW IS THE CREATE PAYMENT REQUEST SENT?
------------------------------------------
The application sends:

    HTTP POST /v3/payments

The data is:
    JSON

The JSON is placed in:
    HTTP request body

It is NOT sent through a query string.


8. EXACT DATA SENT TO MYFATOORAH
--------------------------------
The current Create Payment request contains:

    PaymentMethod
    Order.Amount
    Customer.Name
    Customer.Email
    Customer.Mobile.CountryCode
    Customer.Mobile.Number
    IntegrationUrls.Redirection
    MetaData.OrderId

Current value:
    PaymentMethod = CARD

Order.Amount:
    Selected payment amount.

Customer.Name:
    Name entered on Default.aspx.

Customer.Email:
    Email entered on Default.aspx.

Customer.Mobile.CountryCode:
    +965 in the current implementation.

Customer.Mobile.Number:
    Mobile number entered on Default.aspx, normalized by the
    application for the MyFatoorah request.

IntegrationUrls.Redirection:
    The URL to which MyFatoorah returns the customer after payment.
    The current project uses PaymentResult.aspx.

MetaData.OrderId:
    The application's internal OrderId.

Card details are NOT included in this request.


9. WHAT MYFATOORAH RETURNS AFTER CREATE PAYMENT
-----------------------------------------------
MyFatoorah returns a JSON HTTP response.

The application uses:

    InvoiceId
    PaymentId
    PaymentURL
    PaymentCompleted
    TransactionDetails

Important:

    InvoiceId is stored in the application's payment record.

    PaymentURL is used to redirect the customer to the MyFatoorah
    Hosted Payment Page.

This Create Payment response is NOT a query string.


10. CUSTOMER GOES TO MYFATOORAH
-------------------------------
The application redirects the customer to PaymentURL.

The customer then enters card details on the MyFatoorah Hosted
Payment Page and completes the payment.

The Customer Payment Portal does not collect or store card details.


11. WHICH PAGE DOES MYFATOORAH RETURN TO?
-----------------------------------------
The current project uses:

    PaymentResult.aspx

This is OUR application page name.

PaymentResult.aspx is NOT a page name required by MyFatoorah.
The application can use another page if the configured Redirection
URL is changed.

After payment processing, MyFatoorah redirects the customer's browser
to the configured Redirection URL and includes:

    paymentId

as a query-string parameter.

Example:

    PaymentResult.aspx?paymentId=XXXXXXXX

Therefore:

    Create Payment request = HTTP POST + JSON body
    Payment result redirect = browser redirect + paymentId query string


12. WHICH PAGE VERIFIES THE PAYMENT?
------------------------------------
Customer-facing page:
    PaymentResult.aspx

Server-side verification:
    PaymentResult.aspx.vb

PaymentResult.aspx.vb:

    1. Reads paymentId from the query string.
    2. Calls MyFatoorah Get Payment Details.
    3. Receives payment details as JSON.
    4. Reads Invoice.Status and Transaction.Status.
    5. Determines the application's PaymentStatus.
    6. Updates PaymentRecords.txt.
    7. Displays the payment result.
    8. Initiates email/SMS after successful payment.


13. PAYMENT DETAILS REQUEST
---------------------------
PaymentResult.aspx.vb sends:

    GET /v3/payments/{paymentId}

The paymentId comes from the query string received in the
MyFatoorah redirect.

The response is JSON.

The application reads the payment information required for
verification, including:

    Invoice.Id
    Invoice.Status
    Transaction.Status
    Transaction.PaymentId
    Amount information
    Customer information

The browser redirect itself is NOT treated as proof of payment.
The application calls MyFatoorah to verify the payment details.


14. WHO SETS PaymentStatus = PAID?
----------------------------------
PaymentStatus is an APPLICATION field in:

    App_Data\PaymentRecords.txt

It is set by:

    PaymentResult.aspx.vb

When MyFatoorah returns:

    Invoice.Status = PAID
    Transaction.Status = SUCCESS

the application sets:

    PaymentStatus = PAID

Then PaymentResult.aspx.vb updates the record with:

    PaymentId
    InvoiceId
    PaymentStatus

MyFatoorah does NOT directly write PaymentStatus = PAID into
PaymentRecords.txt.


15. OTHER PAYMENT STATUSES
--------------------------
The current application handles:

    PAID
    FAILED
    CANCELLED
    INPROGRESS
    AUTHORIZED
    PENDING

These values are determined by the application from the payment
information returned by MyFatoorah.


16. WHERE IS THE RESULT DISPLAYED?
----------------------------------
Customer-facing page:

    PaymentResult.aspx

It displays:

    Payment Status
    Payment ID
    Invoice ID
    Transaction Status
    Purchased Option
    Amount

For a successful payment:

    Payment Successful.


17. WHO RECEIVES THE EMAIL?
---------------------------
The confirmation email is sent to the customer's email address
entered on:

    Default.aspx

The call is made by:

    PaymentResult.aspx.vb

The actual email implementation is:

    Services\EmailService.vb

Flow:

    PaymentResult.aspx.vb
          |
          v
    EmailService.vb
          |
          v
    Customer's Email Address


18. WHO RECEIVES THE SMS?
-------------------------
The confirmation SMS is sent to the customer's mobile number
entered on:

    Default.aspx

The call is made by:

    PaymentResult.aspx.vb

The actual SMS implementation is:

    Services\SmsService.vb

Flow:

    PaymentResult.aspx.vb
          |
          v
    SmsService.vb
          |
          v
    Customer's Mobile Number


19. IS MOBILE NUMBER REQUIRED?
------------------------------
CURRENT APPLICATION:

    Mobile Number is REQUIRED.

Reason:

    The current application uses the customer's mobile number for
    SMS confirmation.

If SMS is required:
    Keep Mobile Number required.

If SMS is NOT required:
    Mobile Number can be made optional and SMS can be skipped.

This is an application requirement for the current SMS feature.
It should not be described as a card-detail requirement of the
MyFatoorah Hosted Payment Page.


20. DUPLICATE EMAIL/SMS PREVENTION
----------------------------------
The application prevents duplicate notifications when
PaymentResult.aspx is refreshed.

Before email:
    Check EmailSent.

After successful email:
    EmailSent = TRUE

Before SMS:
    Check SmsSent.

After successful SMS:
    SmsSent = TRUE


21. MYFATOORAH WEBHOOK
----------------------
Webhook page:
    MyFatoorahWebhook.aspx

Server-side code:
    MyFatoorahWebhook.aspx.vb

The webhook is DIFFERENT from the customer redirect.

Customer redirect:
    MyFatoorah
        -> customer's browser
        -> PaymentResult.aspx?paymentId=XXXXXXXX

Webhook:
    MyFatoorah
        -> server-to-server HTTP POST
        -> MyFatoorahWebhook.aspx

The webhook data is JSON in the HTTP request body.
It is NOT sent through a query string.

The webhook is NOT an SMS and is NOT a customer mobile notification.


22. WEBHOOK INFORMATION
-----------------------
For the configured payment-status-change event, the application
reads:

    Event.Code
    Event.Name

    Invoice.Id
    Invoice.Status
    Invoice.ExternalIdentifier

    Transaction.Status
    Transaction.PaymentId

The webhook also contains a MyFatoorah signature header.

MyFatoorahWebhook.aspx.vb validates the signature before processing
the payment information.


23. WEBHOOK PROCESSING
----------------------
MyFatoorahWebhook.aspx.vb:

    1. Accepts HTTP POST.
    2. Reads the JSON body.
    3. Reads the MyFatoorah signature.
    4. Validates the signature.
    5. Reads invoice information.
    6. Reads transaction information.
    7. Determines PaymentStatus.
    8. Finds the payment record.
    9. Updates PaymentId, InvoiceId and PaymentStatus.
   10. Returns a successful response to MyFatoorah.

The webhook does not display the payment result.
The webhook does not send the customer email.
The webhook does not send the customer SMS.


24. COMPLETE PAYMENT SEQUENCE
-----------------------------
STEP 1
Customer opens:
    Default.aspx

STEP 2
Customer selects a payment option and enters:
    Customer Name
    Email
    Mobile Number

STEP 3
JavaScript validates the information.

STEP 4
Default.aspx.vb creates a PENDING record in:
    App_Data\PaymentRecords.txt

STEP 5
Default.aspx.vb calls:
    MyFatoorahService.vb

STEP 6
MyFatoorahService.vb sends:
    HTTP POST /v3/payments
    JSON request body

STEP 7
The request contains:
    PaymentMethod
    Order.Amount
    Customer.Name
    Customer.Email
    Customer.Mobile.CountryCode
    Customer.Mobile.Number
    IntegrationUrls.Redirection
    MetaData.OrderId

STEP 8
MyFatoorah returns a JSON Create Payment response.

STEP 9
The application reads InvoiceId and PaymentURL.

STEP 10
The application stores InvoiceId in the payment record.

STEP 11
The application redirects the customer to PaymentURL.

STEP 12
The customer enters card details on the MyFatoorah Hosted
Payment Page.

STEP 13
The customer completes the payment.

STEP 14
MyFatoorah redirects the browser to:

    PaymentResult.aspx?paymentId=XXXXXXXX

STEP 15
PaymentResult.aspx.vb reads paymentId from the query string.

STEP 16
PaymentResult.aspx.vb sends:

    GET /v3/payments/{paymentId}

STEP 17
MyFatoorah returns payment details as JSON.

STEP 18
PaymentResult.aspx.vb reads:

    Invoice.Status
    Transaction.Status
    Transaction.PaymentId

STEP 19
PaymentResult.aspx.vb determines PaymentStatus.

STEP 20
PaymentResult.aspx.vb updates:

    PaymentId
    InvoiceId
    PaymentStatus

in:

    App_Data\PaymentRecords.txt

STEP 21
PaymentResult.aspx displays the result to the customer.

STEP 22
For successful payment, PaymentResult.aspx.vb calls
EmailService.vb and the email is sent to the customer's email.

STEP 23
If SMS notification is enabled, PaymentResult.aspx.vb calls
SmsService.vb and the SMS is sent to the customer's mobile number.

STEP 24
EmailSent and SmsSent are updated after successful sending.

STEP 25
Separately, MyFatoorah can send a payment-status webhook to:

    MyFatoorahWebhook.aspx

STEP 26
MyFatoorahWebhook.aspx.vb validates and processes the webhook and
updates the corresponding payment record.


25. FILE RESPONSIBILITIES
-------------------------
Default.aspx
    Customer-facing payment page.

Default.aspx.vb
    Server-side validation, payment-record creation, Create Payment
    API call, InvoiceId storage and customer redirection.

PaymentResult.aspx
    Customer-facing payment result page.

PaymentResult.aspx.vb
    Reads paymentId, verifies payment, determines PaymentStatus,
    updates the record, displays the result and initiates
    notifications.

MyFatoorahService.vb
    Sends Create Payment and Get Payment Details API requests.

MyFatoorahWebhook.aspx
    Receives MyFatoorah server-to-server webhook requests.

MyFatoorahWebhook.aspx.vb
    Validates and processes webhook data and updates the payment
    record.

PaymentRecord.vb
    Creates, reads and updates fixed-length payment records.

Services\EmailService.vb
    Sends customer confirmation email.

Services\SmsService.vb
    Sends customer confirmation SMS.


26. NOTIFICATION DESTINATIONS
-----------------------------
Payment result:
    Customer sees it on PaymentResult.aspx.

Email:
    Customer's email address entered on Default.aspx.

SMS:
    Customer's mobile number entered on Default.aspx.


27. CONFIGURATION
-----------------
Web.config contains configuration for:

MyFatoorahApiKey
MyFatoorahWebhookSecret
MyFatoorahRedirectionUrl
MyFatoorahWebhookUrl

EmailFromEmail
EmailAppPassword

TwilioAccountSid
TwilioAuthToken
TwilioFromMobile

Secret values must not be placed in this README or exposed in source
code.


28. LOCAL TESTING
-----------------
Local application:
    https://localhost:44368/

For local MyFatoorah redirection and webhook testing, an ngrok HTTPS
URL is used because MyFatoorah must reach the local web page from
the internet.

Production should use the client's HTTPS domain instead of ngrok.


29. TESTING COMPLETED
---------------------
The following have been tested:

    Successful payment
    Failed payment
    PaymentResult.aspx redirection
    Payment record creation
    InvoiceId update
    PaymentId update
    PaymentStatus update
    MyFatoorah webhook notification
    Email confirmation
    SMS confirmation
    Duplicate email prevention
    Duplicate SMS prevention
    650-character fixed-length record


30. CLIENT ITEMS TO CONFIRM BEFORE PRODUCTION
---------------------------------------------
1. SMS notification

   If SMS is required:
       Mobile Number remains required.
       SMS remains enabled.

   If SMS is not required:
       Mobile Number can be made optional.
       SMS can be disabled/removed.


2. Payment options

   Confirm that the final options are:
       1 KWD
       5 KWD
       10 KWD
       20 KWD
       50 KWD


3. Production URLs

   Confirm the production HTTPS domain for:
       Redirection URL
       Webhook URL


4. MyFatoorah production configuration

   Confirm the production MyFatoorah API configuration and webhook
   configuration.


31. PRODUCTION CHECKLIST
------------------------
Before production deployment:

    - Replace MyFatoorah test configuration with production
      configuration.
    - Configure the production HTTPS Redirection URL.
    - Configure the production HTTPS Webhook URL.
    - Configure the production MyFatoorah webhook.
    - Configure production email.
    - Configure SMS if required.
    - Confirm whether Mobile Number remains mandatory.
    - Keep API keys, webhook secrets, email passwords and SMS
      credentials outside the source code and README.


END OF README
=============
