# 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

<mark style="color:green;">`POST`</mark> <mark style="color:blue;">`{Domain}/api/reconcile_polling.php`</mark>

**Headers**

<table><thead><tr><th width="254">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr><tr><td><strong>Token:</strong> A required header for authentication. Must be set to:</td><td><p></p><pre><code>Will share with documentation kit
</code></pre></td></tr></tbody></table>

**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

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

**Response**

#### Success Response

```json
{
  "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

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

#### Verification Failed

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

#### Invalid User

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

#### Missing Parameters

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

#### Invalid Date Format

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

### Example Request

```json
{
  "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.