PaymentForms

This document details the three components related to payments: NewPaymentForm, ExistingPaymentForm, and ReversePaymentForm.

1. NewPaymentForm

Purpose

The NewPaymentForm is used to create a new payment from an external source (e.g., credit card, bank transfer) and apply it to a specific invoice. The form is dynamic, rendering different fields based on the payment type selected, as defined in the data model.

Usage

import { NewPaymentForm } from './NewPaymentForm';
import { DataModel, CurrencyType } from '@socotra/ec-react-schemas';

const MakePaymentComponent = ({ dataModel, invoice }: { dataModel: DataModel, invoice: any }) => {
  const handleSubmit = (paymentRequest) => {
    console.log('New Payment Request:', paymentRequest);
    // Handle API call to process the new payment
  };

  return (
    <NewPaymentForm
      accountLocator={invoice.accountLocator}
      invoiceLocator={invoice.locator}
      invoiceBalance={invoice.balance}
      currency={invoice.currency as CurrencyType}
      dataModel={dataModel}
      handleSubmit={handleSubmit}
    />
  );
};

Props

State Management

• The component initializes its state with the invoiceBalance pre-filled as the default payment amount.
• It holds all form data in a single state object.
• When the payment type is changed, the component intelligently resets the nested data object to avoid sending stale data from the previously selected type, while preserving the top-level default values.

Validation

Validation is handled by Ajv . A JSON schema is built dynamically based on the fields defined for the selected payment type in dataModel.payments.

Labels and Translations

UI Labels

Labels are customized via the titles prop.

2. ExistingPaymentForm

Purpose

The ExistingPaymentForm is used to apply a credit that already exists on an account to an outstanding invoice. It is not for new payments, but rather for distributing existing, unapplied funds.

Usage

import { ExistingPaymentForm } from './ExistingPaymentForm';

const ApplyCreditComponent = ({ account, invoice }: { account: any, invoice: any }) => {
  const handleSubmit = (creditDistributionRequest) => {
    console.log('Credit Distribution Request:', creditDistributionRequest);
    // Handle API call to apply the credit
  };

  return (
    <ExistingPaymentForm
      accountLocator={account.locator}
      invoiceLocator={invoice.locator}
      balance={account.unappliedCredit}
      invoiceBalance={invoice.balance}
      currency={invoice.currency}
      handleSubmit={handleSubmit}
    />
  );
};

Props

State Management

The form’s state is simple, primarily managing the amount the user wishes to apply. The balance and invoiceBalance fields are displayed as read-only.

Validation

Validation is handled by Ajv . The schema is defined directly within the component and ensures the amount to apply is greater than zero and does not exceed the available account balance.

Labels and Translations

UI Labels

Labels are customized via the titles prop.

3. ReversePaymentForm

Purpose

The ReversePaymentForm is a simple form used to initiate the reversal of a previously applied payment. Its main function is to capture the reason for the reversal.

Usage

import { ReversePaymentForm } from './ReversePaymentForm';
import { DataModel } from '@socotra/ec-react-schemas';

const ReversePaymentComponent = ({ payment, dataModel }: { payment: any, dataModel: DataModel }) => {
  const handleSubmit = (reverseRequest) => {
    console.log('Payment Reversal Request:', reverseRequest);
    // Handle API call to reverse the payment
  };

  return (
    <ReversePaymentForm
      amount={payment.amount}
      currency={payment.currency}
      reversalTypes={dataModel.reversalTypes}
      handleSubmit={handleSubmit}
    />
  );
};

Props

State Management

The component’s state manages the selected reversalType. The amount is displayed as a read-only field. The list of reversal reasons is filtered to only show types that are not for new payments.

Validation

Validation is handled by Ajv . The schema, defined within the component, simply requires that a reversalType be selected from the list.

Labels and Translations

UI Labels

Labels are customized via the titles prop.