# Payment Lifecycle and Request Structure

The **EnKash Payment Gateway** provides a secure and scalable platform for processing digital payments. To initiate a transaction, you must create a well-structured **payment request** containing essential payment details.

## <span style="color:#7b2cbf">Payment Lifecycle</span>

Understanding payment statuses helps in managing transaction states effectively:

| **Status**           | **Description**                                        |
| -------------------- | ------------------------------------------------------ |
| `CREATED`            | Payment request initialized.                           |
| `AUTHORIZED`         | Payment authorized post OTP (if applicable).           |
| `PENDING_WITH_BANK`  | Awaiting confirmation from the customer’s bank.        |
| `SUCCESS`            | Payment successfully completed.                        |
| `FAILED`             | Payment failed due to error, decline, or timeout.      |
| `CANCELLED`          | Payment cancelled by the user.                         |
| `PARTIALLY_REFUNDED` | A portion of the transaction amount has been refunded. |
| `REFUNDED`           | Full amount has been refunded.                         |

## <span style="color:#7b2cbf">Payment Request Structure</span>

Submit a JSON payload with required fields based on the selected payment mode:

| **Field**             | **Type** | **Required** | **Description**                                                                                                             |
| --------------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `orderId`             | `string` | Yes        | Unique identifier for the transaction.                                                                                      |
| `paymentDetail`       | `object` | Optional   | Contains `amount` and `currency`.                                                                                           |
| `paymentMode`         | `string` | Yes        | Accepted values: `NET_BANKING`, `UPI`, `CREDIT_CARD`, `DEBIT_CARD`, `PREPAID_CARD`, `PAY_LATER`, `WALLET`, `CORPORATE_CARD` |
| `cardHolderName`      | `string` | Depends      | Required for card-based payments.                                                                                           |
| `cardNumber`          | `string` | Depends      | Required for card-based payments.                                                                                           |
| `cvv`                 | `string` | Depends      | Required for card-based payments.                                                                                           |
| `expiry`              | `string` | Depends      | Format: `MM/YY`. Required for card-based payments.                                                                          |
| `bankCode`            | `string` | Depends      | Required for `NetBanking`, `BNPL`, and `Wallet` modes.                                                                      |
| `bnplPaymentOptionId` | `string` | Depends      | Required for `BNPL` mode.                                                                                                   |
| `vpa`                 | `string` | Depends      | Required for `UPI` mode.                                                                                                    |
| `accountNumber`       | `string` | Depends      | Required for UPI TPV. Must be between 9–36 characters.                                                                      |
| `ifsc`                | `string` | Depends      | Required for UPI TPV. Must match `^[A-Z]{4}0[A-Z0-9]{6}$`.                                                                  |

## <span style="color:#7b2cbf">Example Payment Request</span>

```json
{
  "orderId": "ORD123456789",
  "paymentDetail": {
    "amount": 1000,
    "currency": "INR"
  },
  "paymentMode": "CREDIT_CARD",
  "cardHolderName": "John Doe",
  "cardNumber": "4111111111111111",
  "cvv": "123",
  "expiry": "12/24",
  "bankCode": "HDFC",
  "vpa": "john.doe@upi",
  "accountNumber": "123456789012",
  "ifsc": "HDFC0001234"
}
```

## <span style="color:#7b2cbf">Key Considerations</span>

:::tip[]
**Unique`orderId`** 
Must be unique per transaction to avoid payment duplication.
:::
:::tip[]
**Field Validation** 
Format and validate card/UPI/bank details on the client side to prevent backend errors.
:::
:::tip[]
**Error Handling** 
Implement logic for status transitions`FAILED`,`PENDING_WITH_BANK`,`CANCELLED`
:::
:::tip[]
**Security** 
Ensure sensitive fields are handled over secure connections and never exposed on the client.
:::