Payout Reconciliation

This API endpoint allows authorized clients to retrieve approved payout transactions for a specific Partner ID (PID) on a given date. The API requires authentication via a header token and a signature. Each PID is limited to 10 API calls per day

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 payout transaction

POST {baseurl}/payout/api/payout_reconcile_polling.php

Note : Replace {baseurl} with the actual url to the API Endpoint

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	Your Partner ID assigned by the system.	Yes
date	string	Date in DD-MM-YYYY format.	Yes
signature	string	The SHA-256 hash signature for verification purposes. (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);

• pid : Your Partner ID.

• secret_key : Your secret key retrieved from the system (provided upon registration).

• date : The date for which you are requesting data, in DD-MM-YYYY format

Daily Request Limit

Limit: 10 requests per day per pid . If the limit is exceeded, the API will respond with an error message indicating that the daily limit has been reached.

Response

Success Response

{
    "status": "success",
    "message": "Success",
    "data": [
        {
            "orderCreateDateTime": "October 15, 2023, 10:30 am",
            "statusChangeDateTime": "October 15, 2023, 2:45 pm",
            "order_id": "ORg123456",
            "ref_code": "abc123def456",
            "amount_requested": 1000,
            "amount_processed": 950,
            "transaction_status": "Approved",
            "bank_ref": "UTR98j654321"
        },
        // ... more transactions
        ]
}

Response Data Fields

Field	Type	Description
orderCreateDateTime	String	The date and time when the payout request was created.
statusChangeDateTime	String	The date and time when the transaction status changed.
order_id	String	The unique identifier for the order.
ref_code	String	A reference code associated with the transaction.
amount_requested	Integer	The amount requested for payout.
amount_processed	Integer	The actual amount processed.
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 (Invalid or Missing Token)

//Status Code : 401 Unauthorized
{
  "status": "error",
  "message": "Unauthorized access"
}

Missing Parameters

Possible Messages :

• "pid not provided"

• "date not provided"

• "signature not provided"

//Status Code : 400 Bad Request
{
  "status": "error",
  "message": "pid not provided"
}

Invalid Date Format

Message: "Invalid date format, should be DD-MM-YYYY"

//Status Code : 400 Bad Request
{
  "status": "error",
  "message": "Invalid date format, should be DD-MM-YYYY"
}

Verification Failed(Invalid Signature)

Message: "verification failed"

//Status Code : 401 Unauthorized
{
  "status": "error",
  "message": "Verification failed"
}

API Limit Reached

//Status Code : 400 Bad Request
{
    "status": "error",
    "message": "Today's API Limited Reached for this PID"
}

Invalid User(PID Not Found)

//Status Code : 400 Bad Request
{
  "status": "error",
  "message": "Invalid User"
}

Example Request

POST {Baseurl}/payout/api/payout_reconcile_polling.php HTTP/1.1
Host: yourapi.com
Content-Type: application/json
Token: ZXvbnvnbvsdDEI9

{
  "pid": "partner123",
  "date": "15-10-2023",
  "signature": "5e884898da28047151d0e56f8dc6292773603d0d6aabbddc9d.."
}

Request with missing Token

POST /api/retrievePayouts HTTP/1.1
Host: yourapi.com
Content-Type: application/json

{
"pid": "partner123",
"date": "15-10-2023",
"signature": "5e884898da28047151d0e56f8dc6292773603d0d6aabbddc9d..."
}

Response

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

Validation Rules

• Token Validation: The Tokenheader must match the required token.

• Required Parameters: pid, date and signature must be provided in the request body.

• Date Format: The date must be in DD-MM-YYYY format and represent a valid date.

• Signature Verification: The signature must match the SHA-256 hash of the concatenated pid, secret_key and date.

• API Limit: No more that 10 requests per pid per day.

---

Implementation Details

Signature Generation Example in PHP

<?php
$pid = 'partner123';
$date = '15-10-2023';
$secret_key = 'your_secret_key'; // Retrieved from your account details
$str = $pid . $secret_key . $date;
$signature = hash('sha256', $str);
?>

Notes

• Time Format: Replace Dates and times in the response are formatted as Month Day, Year, Hour:Minute am/pm (e.g., "October 15, 2023, 2:45 pm").

• Amount Fields: amount_requested and amount_processed are integer values. Ensure that you interpret them according to your currency's smallest unit (e.g., cents for USD).

• Secure Storage: Keep your secret_key secure and do not expose it in client-side code or logs.

Error Handling

• Always check for HTTP status codes in the response.

• In case of an error, refer to the message field in the response body for more details.

• Handle different error scenarios in your application (e.g., prompting the user to retry or contact support).

Contact Information

If you have any questions or need assistance, please contact our support team.

Change Log

• Version 1.0: Initial release of the API documentation.