Payin Intent

Api Endpoint:

This API for Payin Intent will be a POST request.

{BaseUrl}/user/sendPayinRequest

Description

The Payin Intent API allows a user to initiate a payment request. This is typically used in payment gateway integrations where a customer is asked to pay a specified amount using their UPI App. Upon successful initiation, a payment URL is generated for the customer to complete the transaction.

Request:

Request Header

The request must include the following headers for authentication:

Request Header

{
 "apiKey": "your api key",
 "token": "your token",
 "content-type": "application/json"
}

• apiKey: Your unique API key provided by PayHub.
• token: A token that validates your session or request.
• content-type: Specifies that the request body is in JSON format.

Request Body

The body of the request should include the following parameters:

Request Body

{
  "amount": "100",
  "username": "customer name",
  "phone": "customer phone number",
  "customer_email": "customer email",
  "orderId":"Merchant's order id"(Optional)
}

• upiId: The UPI ID of the customer to whom the payment request is being sent.
• amount: The amount to be paid by the customer.
• username: The name of the customer.
• phone: The phone number of the customer.
• customer_email: The email address of the customer.

Body schema

Request body schema

 {
  "amount": {
    "type": "number",
    "format": "float(10,2)",   // up to 2 decimals
    "min": 1,
    "max": 10000
  },
  "username": {
    "type": "string",
    "maxLength": 100
  },
  "phone": {
    "type": "string",
    "maxLength": 13,
    "pattern": "^(\\+91)?[6-9]\\d{9}$" // Indian mobile: 10 digits, optional +91
  },
  "customer_email": {
    "type": "string",
    "maxLength": 254
  },
  "orderId": {
    "type": "string",
    "maxLength": 25,   // recommended
    "optional": true   
  }
};

Possible Responses:

Success Response

A successful response indicates that the payin request has been initiated and includes a URL for the customer to complete the payment.

Success Response

{
    "responseCode": 200,
    "responseMessage": "Success",
    "responseData": {
        "url": "upi://pay/pay?pa=9810922270@kotak&pn=tushant&tn=1835279766&tr=1835279766&am=100&cu=INR",
        "gpayUrl": "tez://upi/pay?pa=9810922270%40kotak&pn=tushant&tn=1835279766&tr=1835279766&am=100&cu=INR",
        "phonepeUrl": "phonepe://upi/pay?pa=9810922270%40kotak&pn=tushant&tn=1835279766&tr=1835279766&am=100&cu=INR",
        "paytmUrl": "paytmmp://upi/pay?pa=9810922270%40kotak&pn=tushant&tn=1835279766&tr=1835279766&am=100&cu=INR",
        "transaction_id": "1835279766"
    }
}

• responseCode: 200 - Indicates a successful request.
• responseMessage: Success - A message indicating the request was successful.
• responseData: Contains the payment URL and transaction details.
  • url: A generic UPI URL that redirects the customer to their UPI app to complete the payment.
  • gpay: A UPI URL specifically formatted for Google Pay.
  • phonepe: A UPI URL specifically formatted for PhonePe.
  • paytm: A UPI URL specifically formatted for Paytm.
  • transaction_id: A unique identifier for the transaction.

Error Responses

If there is an issue with the request, one of the following error responses will be returned:

Invalid API Key

Invalid API Key

{
  "responseCode": 401,
  "responseMessage": "Invalid apiKey"
}

• responseCode: 401 - Indicates forbidden access due to an invalid API key.
• responseMessage: Invalid apiKey - A message indicating the provided API key is invalid.

Invalid User

Invalid User

{
  "responseCode": 400,
  "responseMessage": "User does not exist"
}

• responseCode: 400 - Indicates a bad request due to a non-existent user.
• responseMessage: User does not exist - A message indicating the user specified in the request does not exist.

Invalid Details

Invalid Details

{
  "responseCode": 400,
  "responseMessage": "Invalid details"
}

• responseCode: 400 - Indicates a bad request due to invalid details.
• responseMessage: Invalid details - A message indicating that some of the details provided in the request are invalid.

Notes

• Ensure that all required parameters are provided and valid.
• Check the response codes to handle different outcomes appropriately in your application.
• For security, keep your API key and token confidential.

By following this documentation, you can integrate and use the Payin Intent API effectively in your payment gateway system.