> For the complete documentation index, see [llms.txt](https://docs.pagsmile.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pagsmile.com/reference/payin/payin-reconciliation.md).

# Payin Reconciliation

### Overview

The Payin Reconciliation API allows merchants to retrieve transaction-level Payin records and reconcile them with their internal orders. Each record includes identifiers, amounts, payment methods, transaction statuses, processing fees, and transaction times.

Records are returned in pages for a specified UTC time range. Each request can cover up to 24 hours.

### Before You Start

Use an active merchant account and an enabled App ID for the environment you are calling. The corresponding App Secret Key must be configured and used to generate the `Authorization` header.

{% hint style="info" %}
Use credentials from the same environment as the endpoint. Sandbox credentials cannot be used with the Production endpoint, and Production credentials cannot be used with the Sandbox endpoint.
{% endhint %}

### Endpoint

<table><thead><tr><th width="135.63671875">Environment</th><th width="125.9375">HTTP Method</th><th>URL</th></tr></thead><tbody><tr><td>Sandbox</td><td><code>POST</code></td><td><code>https://gateway-test.pagsmile.com/bill/reconciliation</code></td></tr><tr><td>Production</td><td><code>POST</code></td><td><code>https://gateway.pagsmile.com/bill/reconciliation</code></td></tr></tbody></table>

### Headers

<table><thead><tr><th width="180">Name</th><th width="110">Type</th><th width="120">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Content-Type</code></td><td>string</td><td>Required</td><td>Request content type. Use <code>application/json; charset=UTF-8</code>.</td></tr><tr><td><code>Authorization</code></td><td>string</td><td>Required</td><td>Basic authentication value generated as <code>Basic Base64(app_id:app_secret_key)</code>. The <code>app_id</code> in this header must match the <code>app_id</code> in the Request Body.</td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="180">Name</th><th width="100">Type</th><th width="120">Required</th><th width="230">Constraints</th><th>Description</th></tr></thead><tbody><tr><td><code>app_id</code></td><td>string</td><td>Required</td><td>Must be a valid, enabled App ID.</td><td>Merchant application ID obtained from the Pagsmile dashboard.</td></tr><tr><td><code>timestamp</code></td><td>string</td><td>Required</td><td>Format: <code>yyyy-MM-dd HH:mm:ss</code>.</td><td>Time when the request is sent.</td></tr><tr><td><code>version</code></td><td>string</td><td>Optional</td><td>Default: <code>2.0</code>.</td><td>API version.</td></tr><tr><td><code>start_time</code></td><td>string</td><td>Required</td><td>UTC time in <code>yyyy-MM-dd HH:mm:ss</code> format.</td><td>Start of the reconciliation time range.</td></tr><tr><td><code>end_time</code></td><td>string</td><td>Required</td><td>UTC time in <code>yyyy-MM-dd HH:mm:ss</code> format. The interval from <code>start_time</code> must not exceed 24 hours.</td><td>End of the reconciliation time range.</td></tr><tr><td><code>page_num</code></td><td>integer</td><td>Optional</td><td>Default: <code>1</code>.</td><td>Page number to retrieve.</td></tr><tr><td><code>page_size</code></td><td>integer</td><td>Optional</td><td>Default: <code>5000</code>. Maximum: <code>10000</code>.</td><td>Maximum number of records returned on each page.</td></tr><tr><td><code>type</code></td><td>string</td><td>Optional</td><td>One of <code>SUCCESS</code>, <code>REFUNDED</code>, <code>CHARGEBACK</code>, or <code>CHARGEBACK_REVERSED</code>. Values are case-sensitive.</td><td>Filters the results by transaction status. If omitted, transactions are not filtered by status.</td></tr></tbody></table>

{% hint style="info" %}
The maximum query interval is 24 hours. To reconcile a longer period, divide it into multiple requests and use pagination when the response contains more records than the selected `page_size`.
{% endhint %}

### Request Sample

```json
{
  "app_id": "161*************24",
  "timestamp": "2026-10-14 10:30:00",
  "version": "2.0",
  "start_time": "2026-10-13 00:00:00",
  "end_time": "2026-10-14 00:00:00",
  "page_num": 1,
  "page_size": 5000,
  "type": "SUCCESS"
}
```

### Success Response

```json
{
  "code": "10000",
  "msg": "Success",
  "page_num": 1,
  "page_size": 5000,
  "total_size": "1",
  "detail_list": [
    {
      "merchant_no": "10********01",
      "app_id": "161*************24",
      "trade_no": "2026************36",
      "out_trade_no": "order_********66",
      "subject": "Order payment",
      "content": "Order payment",
      "order_currency": "BRL",
      "order_amount": "100.00",
      "processing_fee": "3.50",
      "processing_fee_detail": [
        {
          "fee_name": "Processing Fee",
          "fee_amount": 3.50,
          "currency": "BRL"
        }
      ],
      "trade_status": "SUCCESS",
      "method": "PIX",
      "order_time": "2026-10-13 09:30:15",
      "update_time": "2026-10-13 09:31:02"
    }
  ]
}
```

### Response Body

<table><thead><tr><th width="250">Parameter</th><th width="110">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>code</code></td><td>string</td><td>Response code. <code>10000</code> indicates success.</td></tr><tr><td><code>msg</code></td><td>string</td><td>Response message.</td></tr><tr><td><code>page_num</code></td><td>integer</td><td>Current page number.</td></tr><tr><td><code>page_size</code></td><td>integer</td><td>Maximum number of records requested for the page.</td></tr><tr><td><code>total_size</code></td><td>string</td><td>Total number of records matching the query.</td></tr><tr><td><code>detail_list</code></td><td>array</td><td>Payin transaction records returned for the current page. Each object contains the fields described below.</td></tr><tr><td><code>merchant_no</code></td><td>string</td><td>Pagsmile merchant number.</td></tr><tr><td><code>app_id</code></td><td>string</td><td>Merchant application ID associated with the transaction.</td></tr><tr><td><code>trade_no</code></td><td>string</td><td>Pagsmile transaction ID.</td></tr><tr><td><code>out_trade_no</code></td><td>string</td><td>Merchant-defined transaction ID.</td></tr><tr><td><code>subject</code></td><td>string</td><td>Transaction subject submitted when the Payin was created.</td></tr><tr><td><code>content</code></td><td>string</td><td>Transaction description submitted when the Payin was created.</td></tr><tr><td><code>order_currency</code></td><td>string</td><td>Transaction currency in uppercase.</td></tr><tr><td><code>order_amount</code></td><td>string</td><td>Transaction amount, returned with two decimal places.</td></tr><tr><td><code>processing_fee</code></td><td>string</td><td>Total processing fee, returned with two decimal places.</td></tr><tr><td><code>processing_fee_detail</code></td><td>array</td><td>Processing fee breakdown. Returned when fee details are available.</td></tr><tr><td><code>fee_name</code></td><td>string</td><td>Fee component name.</td></tr><tr><td><code>fee_amount</code></td><td>number</td><td>Amount of the fee component.</td></tr><tr><td><code>currency</code></td><td>string</td><td>Currency of the fee component.</td></tr><tr><td><code>trade_status</code></td><td>string</td><td>Current transaction status.</td></tr><tr><td><code>method</code></td><td>string</td><td>Payin payment method.</td></tr><tr><td><code>order_time</code></td><td>string</td><td>Time when the Payin transaction was created.</td></tr><tr><td><code>update_time</code></td><td>string</td><td>Successful payment time when available; otherwise, the latest transaction update time.</td></tr></tbody></table>
