SSL_PAYMENT_API.md

SSL Payment Integration - Backend API Requirements

This document outlines the backend API endpoints required for SSLCommerz payment integration.

Required API Endpoints

1. Initiate SSL Payment

Endpoint: POST /ssl/initiate-payment

Request Body:

{
  "parcelId": "string",
  "amount": "number",
  "customerName": "string",
  "customerEmail": "string",
  "customerPhone": "string",
  "customerAddress": "string",
  "productName": "string",
  "productCategory": "string"
}

Response:

{
  "success": true,
  "paymentUrl": "https://sandbox.sslcommerz.com/gwprocess/v4/gw.php?sessionkey=...",
  "sessionKey": "string"
}

2. Verify SSL Payment

Endpoint: POST /ssl/verify-payment

Request Body:

{
  "transactionId": "string",
  "valId": "string",
  "parcelId": "string"
}

Response:

{
  "success": true,
  "transactionId": "string",
  "amount": "number",
  "status": "VALID"
}

SSLCommerz Integration Steps

1. Get SSLCommerz Credentials:

   • Store ID
   • Store Password
   • API URL (Sandbox: https://sandbox.sslcommerz.com, Live: https://securepay.sslcommerz.com)

2. Initiate Payment:

   • Create session using SSLCommerz API
   • Generate payment URL
   • Return URL to frontend

3. Success/Failure Callback:

   • SSLCommerz will redirect to success/failure URL
   • Verify payment using val_id and tran_id
   • Update parcel payment status
   • Create payment record

4. IPN (Instant Payment Notification):

   • SSLCommerz will send IPN to your server
   • Verify and process payment

Environment Variables Required

SSL_STORE_ID=your_store_id
SSL_STORE_PASSWORD=your_store_password
SSL_API_URL=https://sandbox.sslcommerz.com (for testing)
SSL_SUCCESS_URL=https://yourdomain.com/dashboard/payment/success
SSL_FAIL_URL=https://yourdomain.com/dashboard/payment/fail
SSL_CANCEL_URL=https://yourdomain.com/dashboard/payment/cancel
SSL_IPN_URL=https://yourdomain.com/api/ssl/ipn

Payment Flow

1. User selects SSL payment method
2. Frontend calls /ssl/initiate-payment
3. Backend creates SSL session and returns payment URL
4. User is redirected to SSLCommerz payment page
5. User completes payment
6. SSLCommerz redirects to success/failure URL
7. Frontend calls /ssl/verify-payment to verify
8. Backend verifies and updates payment status

Notes

• Use SSLCommerz sandbox for testing
• Switch to live URL for production
• Always verify payments server-side
• Handle IPN for reliable payment confirmation
• Store transaction IDs for reference