# Search payments

This endpoint allows for searches and returns payments made in the last twelve months from the date of the query. In case of success, the request will return a response with status 200.

**GET** `/v1/payments/search`

## Request parameters

### Query

- `sort` (string, required)
  Parameter used for ordering a list of payments. Sorting can be done using the following attributes - "date_approved", "date_created", "date_last_updated", "id", "money_release_date". Por exemplo, se você escolher o atributo "date_approved", os pagamentos serão ordenados pela data em que foram aprovados, em ordem crescente ou decrescente.

- `criteria` (string, required)
  It sorts the payments in ascending order (using “asc”) or in descending order (“desc”).

- `external_reference` (string, required)
  It is a payment’s external reference. It could be, for example, a hashcode from the Central Bank, working as a transaction origin identifier.

- `range` (string, required)
  Parameter used to define the payments search interval. The range can refer to the following attributes - "date_created", "date_last_updated", "date_approved", "money_release_date". If not informed, use default "date_created".

- `begin_date` (string, required)
  Defines the beginning of the payment search interval. The format can be a relative date, such as - "NOW-XDAYS", "NOW-XMONTHS", where "NOW-30DAYS", for example, would filter payments from the last 30 days, and "NOW-1MONTH" would filter payments from the last month. Alternatively, an absolute date in the ISO8601 format, such as "2024-08-23", can be used to search for payments up to that specific date. If not provided, the system defaults to "NOW-3MONTHS".

- `end_date` (string, required)
  Defines the end of the payments search interval. Its format can be a relative date - "NOW-XDAYS", "NOW-XMONTHS" - or an absolute date - ISO8601. If not informed, it defaults to "NOW".

- `store_id` (string, optional)
  Parameter used to filter the payment search by the identifier of the store to which the POS (Point of Sale) belongs.

- `pos_id` (string, optional)
  Parameter used to filter payment searches by the Point of Sale (POS) identifier, physical sales points that use a card machine for sales and/or QR codes.

- `collector.id` (string, required)
  Parameter used to filter payment searches by the identification of the person who receives the payment (collector).

- `payer.id` (string, required)
  Parameter used to filter searches by the identification of the person who makes the payment (payer).

## Response parameters

This endpoint has no response body.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | 1 | Params Error. |
| 400 | 3 | Token must be for test. |
| 400 | 5 | Must provide your access_token to proceed. |
| 400 | 1000 | Number of rows exceeded the limits. |
| 400 | 1001 | Date format must be yyyy-MM-dd'T'HH:mm:ss.SSSZ. |
| 400 | 1003 | Invalid sort value. |
| 400 | 1004 | Invalid criteria value. |
| 400 | 2001 | Already posted the same request in the last minute. |
| 400 | 2002 | Customer not found. |
| 400 | 2004 | POST to Gateway Transactions API fail. |
| 400 | 2006 | Card Token not found. |
| 400 | 2007 | Connection to Card Token API fail. |
| 400 | 2009 | Card token issuer can't be null. |
| 400 | 3000 | You must provide your cardholder_name with your card data. |
| 400 | 3001 | You must provide your cardissuer_id with your card data. |
| 400 | 3003 | Invalid card_token_id. |
| 400 | 3004 | Invalid parameter site_id. |
| 400 | 3005 | Not valid action, the resource is in a state that does not allow this operation. For more information see the state that has the resource. |
| 400 | 3006 | Invalid parameter cardtoken_id. |
| 400 | 3007 | The parameter client_id can not be null or empty. |
| 400 | 3008 | Not found Cardtoken. |
| 400 | 3009 | unauthorized client_id. |
| 400 | 3010 | Not found card on whitelist. |
| 400 | 3011 | Not found payment_method. |
| 400 | 3012 | Invalid parameter security_code_length. |
| 400 | 3013 | The parameter security_code is a required field can not be null or empty. |
| 400 | 3014 | Invalid parameter payment_method. |
| 400 | 3015 | Invalid parameter card_number_length. |
| 400 | 3016 | Invalid parameter card_number. |
| 400 | 3017 | The parameter card_number_id can not be null or empty. |
| 400 | 3018 | The parameter expiration_month can not be null or empty. |
| 400 | 3019 | The parameter expiration_year can not be null or empty. |
| 400 | 3020 | The parameter cardholder.name can not be null or empty. |
| 400 | 3021 | The parameter cardholder.document.number can not be null or empty. |
| 400 | 3022 | The parameter cardholder.document.type can not be null or empty. |
| 400 | 3023 | The parameter cardholder.document.subtype can not be null or empty. |
| 400 | 3024 | Not valid action - partial refund unsupported for this transaction. |
| 400 | 3025 | Invalid Auth Code. |
| 400 | 3026 | Invalid card_id for this payment_method_id. |
| 400 | 3027 | Invalid payment_type_id. |
| 400 | 3028 | Invalid payment_method_id. |
| 400 | 3029 | Invalid card expiration month. |
| 400 | 3030 | Invalid card expiration year. |
| 400 | 9062 | Invalid range interval - Must be less than 365 days. |
| 400 | bad request | The attribute [query param name] is not a possible param. |
| 403 | 4 | The caller is not authorized to access this resource. |
| 403 | 3002 | The caller is not authorized to perform this action. |
| 404 | 2000 | Payment not found. |

## Request example

### cURL

```bash
curl -X GET \
  'https://api.mercadopago.com/v1/payments/search?sort=<SORT>&criteria=<CRITERIA>&external_reference=<EXTERNAL_REFERENCE>&range=<RANGE>&begin_date=<BEGIN_DATE>&end_date=<END_DATE>&store_id=<STORE_ID>&pos_id=<POS_ID>&collector.id=<COLLECTOR.ID>&payer.id=<PAYER.ID>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

### Node.js

```javascript
const client = new MercadoPago({ accessToken: config.access_token });
const payment = new Payment(client);

payment.search({ options: {
	 external_reference: 'ID_REF',
	 sort: 'date_created',
	 criteria: 'desc',
	 range: 'date_created',
	 begin_date: 'NOW-30DAYS',
	 end_date: 'NOW',
	 store_id: '47792478',
	 pos_id: '58930090',
	 offset: 0,
	 limit: 30,
} })
	.then(console.log).catch(console.log);
```

### PHP

```php
MercadoPagoConfig::setAccessToken("ACCESS_TOKEN");

$searchRequest = new MPSearchRequest(30, 0, [
  "sort" => "date_created",
  "criteria" => "desc",
  "external_reference" => "ID_REF",
  "range" => "date_created",
  "begin_date" => "NOW-30DAYS",
  "end_date" => "NOW",
  "store_id" => "47792478",
  "pos_id" => "58930090"
]);
$client = new PaymentClient();
$client->search($searchRequest);
```

### Python

```python
import mercadopago
sdk = mercadopago.SDK("ENV_ACCESS_TOKEN")

 filters = {
	"sort": "date_created",
	"criteria": "desc",
	"external_reference": "ID_REF",
	"range": "date_created",
	"begin_date": "NOW-30DAYS",
	"end_date": "NOW",
	"store_id": "47792478",
	"pos_id": "58930090"}

search_request = sdk.payment().search(filters);
print(search_request)
```

### Java

```java
MercadoPagoConfig.setAccessToken("YOUR_ACCESS_TOKEN");

PaymentClient client = new PaymentClient();

Map<String, Object> filters = new HashMap<>();
filters.put("sort", "date_created");
filters.put("criteria", "desc");
filters.put("external_reference", "ID_REF");
filters.put("range", "date_created");
filters.put("begin_date", "NOW-30DAYS");
filters.put("end_date", "NOW");
filters.put("store_id", "47792478");
filters.put("pos_id", "58930090");

MPSearchRequest searchRequest =
  MPSearchRequest.builder().offset(0).limit(30).filters(filters).build();

client.search(searchRequest);
```

### .Net

```csharp
MercadoPagoConfig.AccessToken = "ENV_ACCESS_TOKEN";

var searchRequest = new AdvancedSearchRequest
{
  Limit = 30,
  Offset = 0,
  Sort = "date_created",
  Criteria = "desc",
  Range = "date_created",
  BeginDate = DateTime.Now.Date,
  EndDate = DateTime.Now.AddDays(1).AddMilliseconds(-1),
  Filters = new Dictionary<string, object>
  {
  ["ID_REF"] = "external_reference",
  },
};

var client = new PaymentClient();
ResultsResourcesPage<Payment> results = await
client.SearchAsync(searchRequest);
```

### Ruby

```text
require 'mercadopago'

sdk = Mercadopago::SDK.new('ENV_ACCESS_TOKEN')

filters = {
  sort: 'date_created',
  criteria: 'desc',
  external_reference: 'ID_REF',
  range: 'date_created',
  begin_date: 'NOW-30DAYS',
  end_date: 'NOW',
  store_id: '47792478',
  pos_id: '58930090'
}

payment_response = sdk.payment.search(filters: filters)
payment_response[:response]
```

## Response example

```json
[
  {
  "paging": {
  "total": 17493,
  "limit": 30,
  "offset": 0
  },
  "results": [
  {
  "id": 1,
  "date_created": "2017-08-31T11:26:38.000Z",
  "date_approved": "2017-08-31T11:26:38.000Z",
  "date_last_updated": "2017-08-31T11:26:38.000Z",
  "date_of_expiration": "string",
  "money_release_date": "2017-09-14T11:26:38.000Z",
  "operation_type": "investment",
  "issuer_id": "string",
  "payment_method_id": "visa",
  "payment_type_id": "credit_card",
  "status": "approved",
  "status_detail": "accredited",
  "currency_id": "BRL",
  "description": "Pago Pizza",
  "live_mode": false,
  "sponsor_id": "string",
  "authorization_code": "string",
  "money_release_schema": "string",
  "counter_currency": "string",
  "collector_id": 2,
  "payer": {
  "id": null,
  "email": null,
  "identification": null,
  "type": null
  },
  "metadata": {},
  "additional_info": {},
  "external_reference": "MP0001",
  "transaction_amount": "24.50",
  "transaction_amount_refunded": 0,
  "coupon_amount": 0,
  "differential_pricing_id": "string",
  "deduction_schema": "string",
  "transaction_details": {
  "net_received_amount": null,
  "total_paid_amount": null,
  "overpaid_amount": null,
  "external_resource_url": null,
  "installment_amount": null,
  "financial_institution": null,
  "payment_method_reference_id": null,
  "payable_deferral_period": null,
  "acquirer_reference": null
  },
  "captured": false,
  "binary_mode": false,
  "call_for_authorize_id": "string",
  "statement_descriptor": "string",
  "installments": 1,
  "card": {},
  "notification_url": "string",
  "processing_mode": "Aggregator",
  "merchant_account_id": "string",
  "acquirer": "string",
  "merchant_number": "string"
  }
  ]
  }
]
```