Payment Gateway

This endpoint group provides payment-request creation, payment-status lookup, and access to client-side configuration for the default payment gateway. The exposed RPC methods operate on a subscription-scoped context when required and delegate payment processing to the configured gateway implementation.

Endpoints

POST /api/rpc (Method: PaymentGatewayRpc.createPaymentLink)

• Description: Creates a new payment request and returns a unique ID and a payment link.

• Request Body:

  {
    "method": "PaymentGatewayRpc.createPaymentLink",
    "params": {
      "amount": 0,
      "currency": "USD",
      "description": "Optional description"
    }
  }

• Parameters:

  Name	Type	Required	Description
  amount	Number	Yes	Integer payment amount. Must be greater than 0.
  currency	String	Yes	Three-character currency code.
  description	String	No	Optional payment description.

• Response:

  {
    "success": true,
    "data": {
      "..." : "Returned by the payment gateway service"
    }
  }

  The exact response shape is not defined in this file. This method forwards the request to PaymentGatewayService.createPaymentLink(...) after requiring a subscription-scoped context.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "PaymentGatewayRpc.createPaymentLink",
      "params": {
        "amount": 1500,
        "currency": "USD",
        "description": "Order payment"
      }
    }'

POST /api/rpc (Method: PaymentGatewayRpc.getPaymentRequestStatus)

• Description: Retrieves the status of a specific payment request.

• Request Body:

  {
    "method": "PaymentGatewayRpc.getPaymentRequestStatus",
    "params": {
      "requestId": "payment_request_id"
    }
  }

• Parameters:

  Name	Type	Required	Description
  requestId	String	Yes	The internal _id of the payment request.

• Response:

  {
    "success": true,
    "data": {
      "..." : "Returned by the payment gateway service"
    }
  }

  The exact response shape is not defined in this file. This method forwards the lookup to PaymentGatewayService.getPaymentRequestStatus(...) after requiring a subscription-scoped context.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "PaymentGatewayRpc.getPaymentRequestStatus",
      "params": {
        "requestId": "payment_request_id"
      }
    }'

POST /api/rpc (Method: PaymentGatewayRpc.getAvailableGateways)

• Description: Retrieves the client-side configuration for the default payment gateway.

• Request Body:

  {
    "method": "PaymentGatewayRpc.getAvailableGateways",
    "params": {}
  }

• Parameters:

  This method accepts no parameters.

• Response:

  {
    "success": true,
    "data": {
      "selectedGateway": "razorpay",
      "config": {
        "keyId": "..."
      }
    }
  }

  The method looks up available gateways from PaymentGatewayService, requires that a gateway named razorpay is present, and returns the selected gateway name plus a config object containing keyId.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "PaymentGatewayRpc.getAvailableGateways",
      "params": {}
    }'