Payin Reconciliation

This API endpoint allows authorized users to retrieve payment transactions based on a specific pid (Partner ID) and date. The API performs authentication using a token and signature verification to ensure secure communication.

Authentication

• Token-based Authentication: The API expects a Token header with a predefined token value.

• Signature Verification: A signature parameter in the request body is used to verify the authenticity of the request.

Retrieve payment transaction

POST {Domain}/api/reconcile_polling.php

Headers

Name	Value
Content-Type	application/json
Token: A required header for authentication. Must be set to:	Will share with documentation kit

Body

Name	Type	Description	Required
pid	string	Partner ID provided to you.	Yes
date	string	Date in DD-MM-YYYY format.	Yes
signature	string	SHA256 hash for signature verification (see below).	Yes

Signature Generation

To generate the signature, compute a SHA256 hash of the concatenated string:

signature = SHA256(pid + secret_key + date)

Example Signature Generation in PHP

$pid = 'your_pid';
$secret_key = 'your_secret_key';
$date = '31-12-2023';
$signature = hash('sha256', $pid . $secret_key . $date);

Response

Success Response

{
  "status": "success",
  "message": "Success",
  "data": [
    {
            "orderCreateDateTime": "October 15, 2023, 2:30 pm",
            "statusChangeDateTime": "October 15, 2023, 2:45 pm",
            "order_id": "ORDdER123456",
            "ref_code": "ABCDdEF123456",
            "amount_requested": 1000,
            "amount_received": 950,
            "transaction_status": "Approved",
            "bank_ref": "UTR1d234567890"
    }
  ]
}

Response Data Fields

Field	Type	Description
orderCreateDateTime	String	The date and time when the order was created.
statusChangeDateTime	String	The date and time when the transaction status changed.
order_id	String	The unique identifier for the customer's order.
ref_code	String	A reference code associated with the transaction.
amount_requested	Integer	The amount requested in the transaction (in smallest currency unit).
amount_received	Integer	The actual amount received (in smallest currency unit).
transaction_status	String	The current status of the transaction (e.g., Approved).
bank_ref	String	Bank reference number or UTR (Unique Transaction Reference).

Error Responses

Unauthorized Access

{
  "status": "error",
  "message": "Unauthorized access"
}

Verification Failed

{
  "status": "error",
  "message": "Verification failed"
}

Invalid User

{
  "status": "error",
  "message": "Invalid User"
}

Missing Parameters

{
  "status": "error",
  "message": "pid not provided"
}

Invalid Date Format

{
  "status": "error",
  "message": "Invalid date format, should be DD-MM-YYYY"
}

Example Request

{
  "pid": "your_pid",
  "date": "31-12-2023",
  "signature": "computed_signature_here"
}

cURL Example

<?php
$token = 'fdfd-fdfd-dfq29EI-dfdfd';
$pid = 'partner123';
$date = '15-10-2023';
$signature = hash('sha256', $pid . $secret_key . $date);

$data = [
    'pid' => $pid,
    'date' => $date,
    'signature' => $signature
];

$ch = curl_init('https://api.example.com/api/reconcile_polling.php');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Token: ' . $token
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Notes

• Placeholders: Replace "your_pid", "your_secret_key", and other placeholders with actual values provided to you.

• Date Format: The date parameter must be in the format DD-MM-YYYY. For example, 31-12-2023.

Rate Limiting

• Each pid is allowed a maximum of 10 API calls per day for this endpoint.

• If the limit is reached, the API will respond with:

  • Status Code: 400 Bad Request

  {
      "status": "error",
      "message": "Today's API Limit Reached for this PID"
  }

Troubleshooting

• Invalid Token: Verify that the Token header is correctly set and matches the required token.

• Signature Mismatch: Ensure that the signature is correctly computed using the SHA256 hash of the concatenated string of pid, secret_key, and date.

• Date Format Issues: Double-check that the date parameter follows the DD-MM-YYYY format and represents a valid date.

Security Considerations

• Keep the secret_key confidential: Do not expose it in client-side code or logs.

• Use HTTPS: Ensure that all requests to the API are made over HTTPS to protect data in transit.

• Validate Responses: Always check the status field in the response to determine if the request was successful.

Change Log

• Version 1.0: Initial release of the API documentation.

---

FAQs

Q1: What should I do if I receive a "Verification failed" message?

• Ensure that you're generating the signature correctly using the concatenation of pid, secret_key, and date in that exact order.

• Verify that the secret_key used matches the one associated with your pid.

Q2: How can I reset my API limit if I reach the maximum number of calls?

• The API limit resets every day at midnight.

Q3: What time zone is used for the date and time fields?

• All date and time fields are in the IST time zone. Please adjust accordingly.