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

# Payment Operations

Base URL: `/v1/payment-ops`

## Authentication

All endpoints require authentication using a Bearer token in the Authorization header:

```
Authorization: Bearer <your_token>
```

## Types

### PaymentRailResponse

```typescript
interface PaymentRailResponse {
  externalId: string;
  bankName: string;
  fedNowEnabled: boolean;
  rtpEnabled: boolean;
  achEnabled: boolean;
  wireEnabled: boolean;
  limits: {
    fedNow?: { daily: number; transaction: number };
    rtp?: { daily: number; transaction: number };
    ach?: { daily: number; transaction: number };
    wire?: { daily: number; transaction: number };
  };
  windows: {
    fedNow?: string;
    rtp?: string;
    ach?: string;
    wire?: string;
  };
}
```

## Endpoints

### Get Rail Eligibility

Retrieves payment rail eligibility information for a specific routing number.

```
GET /eligibility/{routingNumber}
```

#### Parameters

| Name          | Type   | In   | Required | Description                 |
| ------------- | ------ | ---- | -------- | --------------------------- |
| routingNumber | string | path | Yes      | 9-digit bank routing number |

#### Response

```typescript
// 200 OK
{
  "externalId": "chase123",
  "bankName": "JP Morgan Chase",
  "fedNowEnabled": true,
  "rtpEnabled": true,
  "achEnabled": true,
  "wireEnabled": true,
  "limits": {
    "fedNow": {
      "daily": 500000,
      "transaction": 100000
    },
    // ... other rail limits
  },
  "windows": {
    "fedNow": "24/7",
    "rtp": "24/7",
    "ach": "Mon-Fri 8:00-17:00 EST"
  }
}

// 404 Not Found
{
  "error": "Bank not found"
}
```

### Get Rail Limits

Retrieves transaction limits for a specific routing number.

```
GET /limits/{routingNumber}
```

#### Parameters

| Name          | Type   | In   | Required | Description                 |
| ------------- | ------ | ---- | -------- | --------------------------- |
| routingNumber | string | path | Yes      | 9-digit bank routing number |

#### Response

```typescript
// 200 OK
{
  "bankName": "JP Morgan Chase",
  "limits": {
    "fedNow": {
      "daily": 500000,
      "transaction": 100000
    },
    // ... other rail limits
  }
}

// 404 Not Found
{
  "error": "Bank not found"
}
```

### Get Fallback Options

Retrieves fallback payment rail options when preferred rail is unavailable.

```
GET /fallback/{routingNumber}
```

#### Parameters

| Name          | Type   | In    | Required | Description                             |
| ------------- | ------ | ----- | -------- | --------------------------------------- |
| routingNumber | string | path  | Yes      | 9-digit bank routing number             |
| rail          | string | query | No       | Desired rail (default: 'fedNowEnabled') |

#### Response

```typescript
// 200 OK
{
  "fallbackRails": ["RTP", "ACH", "Wire"]
}

// 404 Not Found
{
  "error": "Bank not found"
}
```

### Get Directory Status

Retrieves the current status of the FedNow directory.

```
GET /directorystatus
```

#### Response

```typescript
// 200 OK
{
  "totalFedNowBanks": 2487
}
```

### Sync FedNow Directory

Manually triggers a sync of the FedNow directory.

```
POST /sync-fednow
```

#### Response

```typescript
// 200 OK
{
  "message": "Sync completed successfully"
}
```

## Error Responses

All endpoints can return the following errors:

```typescript
// 401 Unauthorized
{
  "error": "Authentication required"
}

// 403 Forbidden
{
  "error": "Invalid or expired token"
}

// 500 Internal Server Error
{
  "error": "Internal server error"
}
```

## Rate Limits

* 100 requests per minute per API key
* Rate limit headers included in response:
  * `X-RateLimit-Limit`
  * `X-RateLimit-Remaining`
  * `X-RateLimit-Reset`

## Example Usage

### JavaScript/TypeScript

```typescript
const getEligibility = async (routingNumber: string) => {
  const response = await fetch(
    `/v1/payment-ops/eligibility/${routingNumber}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return await response.json();
};
```

### cURL

```bash
# Get rail eligibility
curl -X GET "https://api.tokensource.com/v1/payment-ops/eligibility/021000021" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get fallback options
curl -X GET "https://api.tokensource.com/v1/payment-ops/fallback/021000021?rail=fedNowEnabled" \
  -H "Authorization: Bearer YOUR_API_KEY"
```