Home
Guides

Payout Report

Step-by-Step Guide to Accessing and Analyzing Payout Data

The Payout API allows visibility over your payouts.

A payout ID is generated whenever Tap Payments send funds to the merchant's bank account. So the merchant can download the payout report and see the breakdown of the charges, refunds, disputes or released disputes (if any) and the payout summary.

This guide will help you to understand how to generate a report via Dashboard or API for financial reconciliation.

You can check the API Reference here

Overview of Payouts Report

Payout reports in Tap Payments Gateway provide a detailed summary of settlements breakdown and the payout summary, helping merchants reconcile payments with bank deposits, track fees, and monitor disputes. These reports are essential for financial transparency and operational efficiency

Components of a Payout Report

  • Summary Sheet: Includes total payout amount, settlement date, currency, and fees deducted by Tap Payments.
  • Charges Sheet: Lists transactions included in the payout (e.g., charge ID, amount, status, payment method).
  • Additional Sheets (if applicable):
    • Refunds Sheet: Details of refunded transactions affecting the payout.
    • Disputes Sheet: Information on disputed transactions.
    • Dispute_Release Sheet: Funds returned to the merchant after a resolved dispute.

Use Cases of a Payout Report

  • Reconciling payouts with bank statements.
  • Tracking fees to optimize costs.
  • Monitoring dispute trends to improve customer experience.

Access Methods

  • Download via the Tap Dashboard as an Excel or CSV file.
  • Retrieve programmatically using the Payouts API.

Generate via Dashboard

You can download the payout reports from Tap Dashboard

Step 1: Click on Payout

Step 2: Select the Date Range and Click on Download icon


Generate via API

For developers or merchants needing automation, the Payouts API allows programmatic access to payout data. Below are the steps and code samples to generate a payout report using Tap API.

Authentication

Use your Secret API Key in the Authorization header for all API requests.

Example header:

Authorization: Bearer sk_live_**************
Content-Type: application/json

Step 1: List All Payouts

Use the POST /v2/payouts/list endpoint to retrieve a list of payouts within a specific date range. Refer List All Payoutsfor full documentation and code samples.

📘

To receive a webhook response for sent payouts, please reach out to technical support at [email protected].

Sample Request

curl --request POST \
     --url https://api.tap.company/v2/payouts/list \
     --header 'Authorization: Bearer sk_test_GM34ihb****jqenoQFHS2' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "period": {
    "date": {
      "from": "1722160390000",
      "to": "1722505990000"
    }
  },
  "merchants": [
    "599242"
  ]
}
'

Expected Response:

{
	"object": "list",
	"live_mode": true,
	"api_version": "V2",
	"count": 2,
	"has_more": false,
	"payouts": [
		{
			"id": "payout_33010824251893",
			"status": "PAID_OUT",
			"date": 1722538620000,
			"amount": 369705.279,
			"currency": "SAR",
			"merchant_id": "****3612",
			"wallet": {
				"id": "****3612",
				"legacy_id": "****3612",
				"country": "SA",
				"bank": {
					"id": "37",
					"country": "SA",
					"name": "S FRANSI",
					"swift": "****SARI",
					"beneficiary": {
						"name": "**** Insurance Co",
						"iban": "XXXXX8096"
					}
				}
			},
			"settlements_available": true,
			"bank_reference": "****240801",
			"reference": {
				"uti": "****2421400OL",
				"uetr": "****-45be6c7bbed7",
				"bank_reference": "****240801"
			}
		},
		{
			"id": "payout_33310724247908",
			"status": "PAID_OUT",
			"date": 1722444780000,
			"amount": 403869.939,
			"currency": "SAR",
			"merchant_id": "****3612",
			"wallet": {
				"id": "****3612",
				"legacy_id": "****3612",
				"country": "SA",
				"bank": {
					"id": "37",
					"country": "SA",
					"name": "S FRANSI",
					"swift": "****SARI",
					"beneficiary": {
						"name": "**** Insurance Co",
						"iban": "XXXXX8096"
					}
				}
			},
			"settlements_available": true,
			"bank_reference": "****240731",
			"reference": {
				"uti": "****2421300WI",
				"uetr": "****-52d59060932e",
				"bank_reference": "****240731"
			}
		}
	]
}

Step 2: Retrieve a Specific Payout (Optional)

If you need details for a specific payout, use the same list endpoint and provide the payout ID received from the previous step. Refer Download Payouts doc

Sample Request

curl --request POST \
  --url https://api.tap.company/v2/payouts/list \
  --header 'Authorization: Bearer sk_live_QqkE*****9Y7RPHtbzl' \
  --header 'Content-Type: application/json' \
  --data '{
	"payouts": {
		"payout_id": [
			"payout_33010824251893"
		]
	},
	"merchants": [
		"12345"
	]
}'

Expected Response: 

{
	"object": "list",
	"live_mode": true,
	"api_version": "V2",
	"count": 1,
	"has_more": false,
	"payouts": [
		{
			"id": "payout_33010824251893",
			"status": "PAID_OUT",
			"date": 1722538620000,
			"amount": 369705.279,
			"currency": "SAR",
			"merchant_id": "****3612",
			"wallet": {
				"id": "****3612",
				"legacy_id": "****3612",
				"country": "SA",
				"bank": {
					"id": "37",
					"country": "SA",
					"name": "S FRANSI",
					"swift": "****SARI",
					"beneficiary": {
						"name": "**** Insurance Co",
						"iban": "XXXXX8096"
					}
				}
			},
			"settlements_available": true,
			"bank_reference": "****240801",
			"reference": {
				"uti": "****2421400OL",
				"uetr": "****-45be6c7bbed7",
				"bank_reference": "****240801"
			}
		}
	]
}

Step 3: Download the Payout File

Use the POST /v2/payouts/download endpoint to download a detailed payout report in a zipped folder containing sheets for each report respectively. Refer Download Payouts doc.

Sample Request :

curl --request POST \
  --url https://api.tap.company/v2/payouts/download \
  --header 'Authorization: Bearer sk_live_QqkEI*****Jy9Y7RPHtbzl' \
  --header 'Content-Type: application/json' \
  --data '{
	"payouts": {
		"payout_id": [
			"payout_33010824251893"
		]
	},
	"merchants": [
		"24923612"
	]
}'

Sample Response

You need to save the raw content as a zipped file.

�A�.�I.����H~[
����q?͕�Q����UJ)Q�9���̶5�����?����o�����~L�O���s���������ǯ����W��������_�������çg����/�+��|������L\�7�����x�t�=>|��/�1~�����ǹx�����1w����)?������Y�9���_�a�o��g���d���_���_Q���S?��Q�%W�:1�П����rI-e�Ϗ�^�O�~c�Yj��j*(5���7G�C����;��y�ur(���������A�\�~���ڿ��!�VSG�!����3����ob8����;<�8ux�i�X��x�-�Lj�xTD.ef^�(Q�(D�&� �mQe����7������1�1:(�;}����r�c'��n8>��

Step 4: Automate Report Generation (Optional)

To generate reports regularly (e.g., weekly), you can schedule the required reports using APIs

Analyze Reports

Once you have generated a payout report, use it to gain insights and ensure financial accuracy.

Key Metrics to Monitor:

  • Total Payout Amount: Net amount settled to your bank account (e.g., 8.16 SAR).
  • Fees: Transaction and gateway fees deducted by Tap Payments.
  • Settlement Date: Date the payout was processed (e.g., 2023-10-29).
  • Disputes and Refunds: Track chargebacks or resolved disputes (Dispute_Release entries).

Reconciliation Use Case:

  • Compare the total payout amount in the Summary Sheet with your bank statement to ensure all funds were deposited.
  • Verify that fees align with your agreement with Tap Payments.
  • Check the Charges Sheet to match transactions with your internal records.

Data Visualization:

  • Import the Excel file into tools like Microsoft Excel, Tableau, or Power BI.
  • Example: Create a bar chart showing payout amounts by month to identify revenue trends.

Actionable Insights:

  • Identify high fee patterns and negotiate better rates with Tap Payments.
  • Address recurring disputes by improving checkout processes or customer support.
  • Use settlement dates to optimize cash flow planning.

Best Practices

Follow these recommendations to manage payout reports effectively:

Data Security:

  • Use HTTPS for all API requests to ensure secure data transmission.
  • Store API keys securely (e.g., in a vault or environment variables).
  • Comply with PCI DSS standards when handling payout data.

Regular Audits:

  • Perform monthly reconciliations by comparing payout reports with bank statements.
  • Verify Dispute_Release entries to ensure recovered funds are correctly credited.

Backup Reports:

  • Store downloaded reports in encrypted cloud storage (e.g., AWS S3, Google Drive).
  • Retain reports for at least 7 years to comply with tax and audit requirements.

Team Collaboration:

  • Share reports with your finance team for reconciliation.
  • Use role-based access in the Tap Dashboard to restrict sensitive data to authorized users.

Troubleshooting

Address common issues when generating payout reports:

Dashboard Issues:

  • Problem: Payout report not visible or incomplete.
  • Solution: Check date filters, ensure payout access is enabled, or contact Tap support at [email protected].

API Issues:

  • Problem: 1260 Payout data not available.
  • Solution: Ensure that the following tag is as true in the payout response. If this is false, it means the file generation is in progress. Please try after 1-2 hours or contact Tap Support team 
    		"settlements_available": true,

File Download Issues:

  • Problem: Downloaded Excel file is corrupted.
  • Solution: Re-download the file using the /v2/payouts/download endpoint or check the API response for errors.

Support Resources:

Updated 2 days ago