# External Payment API Documentation

## Overview
The External Payment API allows you to manage payment transactions conducted through various external rails.

### Allowed Categories
- `EXTERNAL_WIRE`
- `EXTERNAL_ACH`
- `EXTERNAL_CHECK`
- `EXTERNAL_FEDNOW`
- `EXTERNAL_RTP`
- `EXTERNAL_TRANSFER`

### Request Parameters
| Parameter                | Type        | Description  |
|--------------------------|-------------|--------------|
| `category`               | string      | The external rail the funds moved on  |
| `financial_account_token` | uuid        | Unique identifier for the financial account or card that will send the funds. |
| `business_account_token`  | uuid        | Token for the business account. |
| `result`                 | string      | External Payment result to be returned.  |
| `status`                 | string      | Book transfer status to be returned.  |
| `begin`                  | date-time   | Only entries created after the specified time.  |
| `ending_before`          | string      | A cursor for retrieving the previous page of results. |
| `end`                    | date-time   | Only entries created before the specified time.  |
| `page_size`              | integer     | Page size for pagination (1 to 100). Defaults to 50. |
| `starting_after`         | string      | A cursor for retrieving the next page of results. |

### Response Format
HTTP Status: `200 OK`

```json
{
  "data": [
    {
      "status": "PENDING",
      "token": "2e0c...3cf2",
      "created": "2023-07-18T00:25:30.520Z",
      "updated": "2023-07-18T00:25:30.520Z",
      "result": "APPROVED",
      "category": "EXTERNAL_WIRE",
      "settled_amount": 0,
      "pending_amount": 0,
      "currency": "USD",
      "events": [
        {
          "amount": 0,
          "type": "EXTERNAL_WIRE_INITIATED",
          "result": "APPROVED",
          "detailed_results": ["APPROVED"],
          "created": "2023-07-18T00:25:30.520Z",
          "token": "2e0c...3cf2",
          "memo": "Payment initiated",
          "effective_date": "2023-07-18"
        }
      ],
      "user_defined_id": "UniqueID123",
      "financial_account_token": "2e0c...3cf2",
      "payment_type": "DEPOSIT"
    }
  ],
  "has_more": true
}
```

### Error Codes
- `400`: A parameter in the query does not match the valid queries for the endpoint.
- `401`: Authentication errors including invalid or missing API key.
- `429`: Rate limits exceeded.

## Example cURL Request
```bash
curl --request GET \
     --url 'https://sandbox.lithic.com/v1/external_payments?page_size=50' \
     --header 'accept: application/json'
```

## Note
Ensure to handle various response codes properly in your implementation.