Digital Means of Payment Configuration

This section details the configuration settings required for integrating with a digital payment gateway. The settings are defined in the application's configuration file (apps.py).

Configuration Parameters

gateway_base_url: The base URL of the payment gateway's API.
- Example: "http://41.175.18.170:8070/api/mobile/v1/"
endpoint_payment: The endpoint for processing payments.
- Example: "mock/payment"
endpoint_reconciliation: The endpoint for reconciling payments.
- Example: "mock/reconciliation"
payment_gateway_api_key: The API key for authenticating with the payment gateway. It is retrieved from environment variables.
payment_gateway_basic_auth_username: The username for basic authentication with the payment gateway. It is retrieved from environment variables.
payment_gateway_basic_auth_password: The password for basic authentication with the payment gateway. It is retrieved from environment variables.
payment_gateway_timeout: The timeout setting for requests to the payment gateway, in seconds.
- Example: 5
payment_gateway_auth_type: The type of authentication used by the payment gateway. It can be either 'token' or 'basic'.
- Example: "basic"
payment_gateway_class: The class that handles interactions with the payment gateway.
- Example: "payroll.payment_gateway.MockedPaymentGatewayConnector"
receipt_length: The length of the receipt generated for transactions.
- Example: 8

Example Configuration

{
    "gateway_base_url": "http://41.175.18.170:8070/api/mobile/v1/",
    "endpoint_payment": "mock/payment",
    "endpoint_reconciliation": "mock/reconciliation",
    "payment_gateway_api_key": os.getenv('PAYMENT_GATEWAY_API_KEY'),
    "payment_gateway_basic_auth_username": os.getenv('PAYMENT_GATEWAY_BASIC_AUTH_USERNAME'),
    "payment_gateway_basic_auth_password": os.getenv('PAYMENT_GATEWAY_BASIC_AUTH_PASSWORD'),
    "payment_gateway_timeout": 5,
    "payment_gateway_auth_type": "basic",
    "payment_gateway_class": "payroll.payment_gateway.MockedPaymentGatewayConnector",
    "receipt_length": 8
}

Integrating the Payment Gateway

To integrate the payment gateway, you need to define a class that extends the PaymentGatewayConnector and implements the necessary methods to handle payment and reconciliation requests.

Example Implementation of Payment Gateway Integration

from payroll.payment_gateway.payment_gateway_connector import PaymentGatewayConnector

class MockedPaymentGatewayConnector(PaymentGatewayConnector):
    def send_payment(self, invoice_id, amount, **kwargs):
        payload = {"invoiceId": str(invoice_id), "amount": str(amount)}
        response = self.send_request(self.config.endpoint_payment, payload)
        if response:
            response_text = response.text
            expected_message = f"{invoice_id} invoice of {amount} accepted to be paid"
            if response_text == expected_message:
                return True
        return False

    def reconcile(self, invoice_id, amount, **kwargs):
        payload = {"invoiceId": str(invoice_id), "amount": str(amount)}
        response = self.send_request(self.config.endpoint_reconciliation, payload)
        if response:
            return response.text == "true"
        return False

Environment Variables

Make sure to set the following environment variables in your environment:

PAYMENT_GATEWAY_API_KEY: Your API key for the payment gateway.
PAYMENT_GATEWAY_BASIC_AUTH_USERNAME: Your username for basic authentication.
PAYMENT_GATEWAY_BASIC_AUTH_PASSWORD: Your password for basic authentication.

You can use either basic authentication or token authentication. Set the following variable accordingly:

Payment Flow for Online Payroll Payments

When the payment_method of a Payroll is set to StrategyOnlinePayment, the configuration described below is required for the payment and reconciliation process.

Instructions for Making a Payment

Populate/Generate Payroll: Ensure the payroll has payment_method='StrategyOnlinePayment'.
Accept or Reject Payroll: Use the maker-checker logic to either accept or reject the payroll.
Accepted Payroll:
- Navigate to Legal and Finance (Payments) -> Accepted Payrolls.
- Click the Make Payment button. This triggers the payment flow defined in the configuration.
Invoice Submission:
- If all invoices are sent successfully, go to the view reconciliation summary.
- Invoices that were accepted will have their status changed from Accepted to Approved for Payment.
Close Payroll:
- In the same view, click the Accept and Close Payroll button.
Task View:
- Go to payroll details and click the Tasks view.
- At the top of the searcher, you should see a Reconciliation task.
Accept or Reject Task:
- Accept or reject the reconciliation task.
- If accepted, the reconciliation flow is triggered. Payments are reconciled if the feedback from the payment gateway is successful without any issues. The status for the benefit will be Reconciled. The payroll will now be visible in Payrolls -> Reconciled Payrolls.
Error Handling:
- Even if the payroll is reconciled, some benefits might not be paid due to errors.
- The status will remain Approved for Payment.
- Errors can be viewed by clicking the Error button.
- Unpaid Payroll's invoices can be recreated during re-creation of payroll in reconciled payroll
Recreate Unpaid Invoices:
- Unpaid payroll invoices can be recreated during the re-creation of payroll in the reconciled payroll section.
- The unpaid invoices will be included in the new payroll.
- Use the Create Payroll from Unpaid Invoices button available when you go to Legal and Finance -> Reconciled Payrolls -> View Reconciled Payroll -> Create Payment from Failed Invoice.