# PaymentsService

Defined in: [packages/synapse-sdk/src/payments/service.ts:38](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L38)

PaymentsService - Filecoin Pay client for managing deposits, approvals, and payment rails

## Constructors

### Constructor

> **new PaymentsService**(`client`): `PaymentsService`

Defined in: [packages/synapse-sdk/src/payments/service.ts:45](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L45)

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `client` | `Client`\<`Transport`, `Chain`, `Account`\> | Client instance for balance checks, nonce management, and epoch calculations |

#### Returns

`PaymentsService`

## Methods

### accountInfo()

> **accountInfo**(`token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<\{ `availableFunds`: `bigint`; `funds`: `bigint`; `lockupCurrent`: `bigint`; `lockupLastSettledAt`: `bigint`; `lockupRate`: `bigint`; \}\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:68](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L68)

Get detailed account information from the payments contract

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `token` | `string` | `TOKENS.USDFC` | The token to get account info for (defaults to USDFC) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<\{ `availableFunds`: `bigint`; `funds`: `bigint`; `lockupCurrent`: `bigint`; `lockupLastSettledAt`: `bigint`; `lockupRate`: `bigint`; \}\>

Account information including funds, lockup details, and available balance

***

### allowance()

> **allowance**(`spender`, `token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`bigint`\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:142](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L142)

Check the current ERC20 token allowance for a spender

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `spender` | `` `0x${string}` `` | `undefined` | The address to check allowance for |
| `token` | `string` | `TOKENS.USDFC` | The token to check allowance for (defaults to USDFC) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`bigint`\>

The current allowance amount as bigint

***

### approve()

> **approve**(`spender`, `amount`, `token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:174](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L174)

Approve an ERC20 token spender

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `spender` | `` `0x${string}` `` | `undefined` | The address to approve as spender |
| `amount` | `bigint` | `undefined` | The amount to approve |
| `token` | `string` | `TOKENS.USDFC` | The token to approve spending for (defaults to USDFC) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Transaction response object

***

### approveService()

> **approveService**(`service`, `rateAllowance`, `lockupAllowance`, `maxLockupPeriod`, `token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:210](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L210)

Approve a service contract to act as an operator for payment rails
This allows the service contract (such as Warm Storage) to create and manage payment rails on behalf
of the client

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `service` | `` `0x${string}` `` | `undefined` | The service contract address to approve |
| `rateAllowance` | `bigint` | `undefined` | Maximum payment rate per epoch the operator can set |
| `lockupAllowance` | `bigint` | `undefined` | Maximum lockup amount the operator can set |
| `maxLockupPeriod` | `bigint` | `undefined` | Maximum lockup period in epochs the operator can set |
| `token` | `string` | `TOKENS.USDFC` | The token to approve for (defaults to USDFC) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Transaction response object

***

### balance()

> **balance**(`token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`bigint`\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:49](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L49)

#### Parameters

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `token` | `string` | `TOKENS.USDFC` |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`bigint`\>

***

### decimals()

> **decimals**(`_token`): `number`

Defined in: [packages/synapse-sdk/src/payments/service.ts:131](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L131)

#### Parameters

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `_token` | `string` | `TOKENS.USDFC` |

#### Returns

`number`

***

### deposit()

> **deposit**(`amount`, `token`, `options?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:309](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L309)

#### Parameters

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `amount` | `bigint` | `undefined` |
| `token` | `string` | `TOKENS.USDFC` |
| `options?` | [`DepositOptions`](/reference/filoz/synapse-sdk/payments/interfaces/depositoptions/) | `undefined` |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

***

### depositWithPermit()

> **depositWithPermit**(`amount`, `token`, `deadline?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:372](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L372)

Deposit funds using ERC-2612 permit to approve and deposit in a single transaction
This method creates an EIP-712 typed-data signature for the USDFC token's permit,
then calls the Payments contract `depositWithPermit` to pull funds and credit the account.

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `amount` | `bigint` | `undefined` | Amount of USDFC to deposit (in base units) |
| `token` | `string` | `TOKENS.USDFC` | Token identifier (currently only USDFC is supported) |
| `deadline?` | `bigint` | `undefined` | Unix timestamp (seconds) when the permit expires. Defaults to now + 1 hour. |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Transaction response object

***

### depositWithPermitAndApproveOperator()

> **depositWithPermitAndApproveOperator**(`amount`, `operator?`, `rateAllowance?`, `lockupAllowance?`, `maxLockupPeriod?`, `deadline?`, `token?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:451](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L451)

Deposit funds using ERC-2612 permit and approve an operator in a single transaction
This signs an EIP-712 permit for the USDFC token and calls the Payments contract
function `depositWithPermitAndApproveOperator` which both deposits and sets operator approval.

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `amount` | `bigint` | `undefined` | Amount of USDFC to deposit (in base units) |
| `operator?` | `` `0x${string}` `` | `undefined` | Service/operator address to approve |
| `rateAllowance?` | `bigint` | `undefined` | Max payment rate per epoch operator can set |
| `lockupAllowance?` | `bigint` | `undefined` | Max lockup amount operator can set |
| `maxLockupPeriod?` | `bigint` | `undefined` | Max lockup period in epochs operator can set |
| `deadline?` | `bigint` | `undefined` | Unix timestamp (seconds) when the permit expires. Defaults to now + 1 hour. |
| `token?` | `string` | `TOKENS.USDFC` | Token identifier (currently only USDFC supported) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Transaction response object

***

### getRail()

> **getRail**(`railId`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<\{ `commissionRateBps`: `bigint`; `endEpoch`: `bigint`; `from`: `` `0x${string}` ``; `lockupFixed`: `bigint`; `lockupPeriod`: `bigint`; `operator`: `` `0x${string}` ``; `paymentRate`: `bigint`; `serviceFeeRecipient`: `` `0x${string}` ``; `settledUpTo`: `bigint`; `to`: `` `0x${string}` ``; `token`: `` `0x${string}` ``; `validator`: `` `0x${string}` ``; \}\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:618](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L618)

Get detailed information about a specific rail

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `railId` | `bigint` | The rail ID to query |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<\{ `commissionRateBps`: `bigint`; `endEpoch`: `bigint`; `from`: `` `0x${string}` ``; `lockupFixed`: `bigint`; `lockupPeriod`: `bigint`; `operator`: `` `0x${string}` ``; `paymentRate`: `bigint`; `serviceFeeRecipient`: `` `0x${string}` ``; `settledUpTo`: `bigint`; `to`: `` `0x${string}` ``; `token`: `` `0x${string}` ``; `validator`: `` `0x${string}` ``; \}\>

Rail information including all parameters and current state

#### Throws

Error if the rail doesn't exist or is inactive (contract reverts with RailInactiveOrSettled)

***

### getRailsAsPayee()

> **getRailsAsPayee**(`token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`RailInfo`](/reference/filoz/synapse-sdk/synapse/type-aliases/railinfo/)[]\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:712](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L712)

Get all rails where the wallet is the payee

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `token` | `string` | `TOKENS.USDFC` | The token to filter by (defaults to USDFC) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`RailInfo`](/reference/filoz/synapse-sdk/synapse/type-aliases/railinfo/)[]\>

Array of rail information

***

### getRailsAsPayer()

> **getRailsAsPayer**(`token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`RailInfo`](/reference/filoz/synapse-sdk/synapse/type-aliases/railinfo/)[]\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:687](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L687)

Get all rails where the wallet is the payer

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `token` | `string` | `TOKENS.USDFC` | The token to filter by (defaults to USDFC) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`RailInfo`](/reference/filoz/synapse-sdk/synapse/type-aliases/railinfo/)[]\>

Array of rail information

***

### getSettlementAmounts()

> **getSettlementAmounts**(`railId`, `untilEpoch?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`SettlementResult`](/reference/filoz/synapse-sdk/synapse/interfaces/settlementresult/)\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:553](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L553)

Get the expected settlement amounts for a rail (read-only simulation)

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `railId` | `bigint` | The rail ID to check |
| `untilEpoch?` | `bigint` | The epoch to settle up to (must be <= current epoch; defaults to current). Can be used to preview partial settlements to a past epoch. |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`SettlementResult`](/reference/filoz/synapse-sdk/synapse/interfaces/settlementresult/)\>

Settlement result with amounts and details

***

### revokeService()

> **revokeService**(`service`, `token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:250](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L250)

Revoke a service contract's operator approval

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `service` | `` `0x${string}` `` | `undefined` | The service contract address to revoke |
| `token` | `string` | `TOKENS.USDFC` | The token to revoke approval for (defaults to USDFC) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Transaction response object

***

### serviceApproval()

> **serviceApproval**(`service`, `token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`OutputType`](/reference/filoz/synapse-core/pay/namespaces/operatorapprovals/type-aliases/outputtype/)\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:281](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L281)

Get the operator approval status and allowances for a service

#### Parameters

| Parameter | Type | Default value | Description |
| ------ | ------ | ------ | ------ |
| `service` | `` `0x${string}` `` | `undefined` | The service contract address to check |
| `token` | `string` | `TOKENS.USDFC` | The token to check approval for (defaults to USDFC) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`OutputType`](/reference/filoz/synapse-core/pay/namespaces/operatorapprovals/type-aliases/outputtype/)\>

Approval status and allowances [Pay.operatorApprovals.OutputType](/reference/filoz/synapse-core/pay/namespaces/operatorapprovals/type-aliases/outputtype/)

***

### settle()

> **settle**(`railId`, `untilEpoch?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:522](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L522)

Settle a payment rail up to a specific epoch (sends a transaction)

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `railId` | `bigint` | The rail ID to settle |
| `untilEpoch?` | `bigint` | The epoch to settle up to (must be <= current epoch; defaults to current). Can be used for partial settlements to a past epoch. |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Transaction response object

#### Throws

Error if untilEpoch is in the future (contract reverts with CannotSettleFutureEpochs)

***

### settleAuto()

> **settleAuto**(`railId`, `untilEpoch?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:668](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L668)

Automatically settle a rail, detecting whether it's terminated or active
This method checks the rail status and calls the appropriate settlement method:
- For terminated rails: calls settleTerminatedRail()
- For active rails: calls settle() with optional untilEpoch

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `railId` | `bigint` | The rail ID to settle |
| `untilEpoch?` | `bigint` | The epoch to settle up to (must be <= current epoch for active rails; ignored for terminated rails) |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Transaction response object

#### Throws

Error if rail doesn't exist (contract reverts with RailInactiveOrSettled) or other settlement errors

#### Example

```javascript
// Automatically detect and settle appropriately
const tx = await synapse.payments.settleAuto(railId)
await tx.wait()

// For active rails, can specify epoch
const tx = await synapse.payments.settleAuto(railId, specificEpoch)
```

***

### settleTerminatedRail()

> **settleTerminatedRail**(`railId`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:596](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L596)

Emergency settlement for terminated rails only - bypasses service contract validation
This ensures payment even if the validator contract is buggy or unresponsive (pays in full)
Can only be called by the client after the max settlement epoch has passed

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `railId` | `bigint` | The rail ID to settle |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Transaction response object

***

### walletBalance()

> **walletBalance**(`token?`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`bigint`\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:88](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L88)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `token?` | `string` |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`bigint`\>

***

### withdraw()

> **withdraw**(`amount`, `token`): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>

Defined in: [packages/synapse-sdk/src/payments/service.ts:485](https://github.com/FilOzone/synapse-sdk/blob/32f86959b0bf15557657ea412e31a0897440ca98/packages/synapse-sdk/src/payments/service.ts#L485)

#### Parameters

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `amount` | `bigint` | `undefined` |
| `token` | `string` | `TOKENS.USDFC` |

#### Returns

[`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<`` `0x${string}` ``\>