> ## Documentation Index
> Fetch the complete documentation index at: https://diameterpay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Payments by ID or End-to-End Reference

> POST /v1/payments/search — Look up a payment by Diameter UUID or end-to-end reference ID. Requires com.diameterpay.api/payments.read scope.

Look up a payment using either the Diameter-issued payment UUID or your own end-to-end reference identifier. This is especially useful when you need to reconcile a payment against your own records using the `endToEndId` you assigned at initiation, without needing to store the Diameter `id`. At least one of `paymentId` or `endToEndId` must be provided in the request body.

## Endpoint

```
POST /v1/payments/search
```

**Required scope:** `com.diameterpay.api/payments.read`

## Headers

**Authorization** `string` *required*

`Bearer {access_token}`

## Request Body

**paymentId** `string`

The Diameter-issued UUID of the payment to look up. Provide either `paymentId`, `endToEndId`, or both.

**endToEndId** `string`

Your own end-to-end reference identifier (`endToEndId`) supplied when the payment was created. Provide either `endToEndId`, `paymentId`, or both.

## Response Fields

**data** `object | null`

The matching payment object, or `null` if no payment matching the supplied identifiers was found. When present, the object has the same shape as the [Get Payment](https://diameterpay.mintlify.site/api-reference/payments/get-payment.md) response, including `id`, `e2eId`, `status`, `wire`, and `idAssignedByBank`.

## Example Request — Search by Diameter Payment ID

```bash theme={null}
curl --request POST \
  --url "https://api.diameterpay.com/v1/payments/search" \
  --header "Authorization: Bearer {access_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "paymentId": "d4e5f6a7-b8c9-0123-defa-bc1234567890"
  }'
```

## Example Request — Search by End-to-End Reference

```bash theme={null}
curl --request POST \
  --url "https://api.diameterpay.com/v1/payments/search" \
  --header "Authorization: Bearer {access_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "endToEndId": "PAY-2024-001"
  }'
```

## Example Response — Payment Found

```json theme={null}
{
  "data": {
    "id": "d4e5f6a7-b8c9-0123-defa-bc1234567890",
    "e2eId": "PAY-2024-001",
    "status": "COMPLETED",
    "wire": {
      "initialImad": "0601BANKUS33XXXX0000001",
      "finalImad": "0601BANKUS33XXXX0000002"
    },
    "idAssignedByBank": "FED20240601000001"
  }
}
```

## Example Response — Not Found

```json theme={null}
{
  "data": null
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.