# Settlement API

```admonition
icon: fas fa-exclamation-triangle
title: Important: Legacy API
content: This API is no longer compatible and not supported for new implementations. A new settlement API is coming soon.
```

```admonition
icon: fas fa-exclamation-triangle
title: Important: Different Authentication & Implementation
content: The Settlement API uses a different authentication method and implementation compared to other Teya APIs. This API uses SOAP/WCF protocols with username/password authentication instead of OAuth 2.0. Please read the authentication and connection instructions carefully before starting your integration to ensure you use the correct credentials and endpoints.
```

The Settlement API provides programmatic access to merchant settlement data, including payout information, transaction details, and fee breakdowns. This SOAP-based interface enables merchants and their systems to retrieve settlement records for reconciliation, accounting, and financial reporting purposes.

Settlements represent the periodic payouts made to merchants for processed card transactions. Each settlement includes the gross transaction amounts, applicable fees and deductions, and the net payment amount. The API allows you to query settlements by date range, retrieve detailed transaction lists, and examine the specific fees and adjustments applied to each settlement.

## How to connect

The connection process varies depending on whether you are an existing Teya customer and whether you want to integrate directly with the API or through an accounting platform that already supports the integration.
If you are not currently a Teya customer, you will need to request an onboarding through Customer Operations.

If you are already a Teya customer, contact Customer Operations and provide your Merchant ID (MID). They will provide you with:
- Username
- Password
- Service endpoint URL (see [Service Endpoints](#service-endpoints) below)

**For direct API integration:**
1. Use the test credentials provided by Customer Operations
2. Test your integration using the test environment endpoint
3. Once testing is complete, create your production connection using your production MID, username, and password with the production URL

### Accounting platform integration

If your accounting platform already supports SOAP integration with the Settlement API:
1. Contact Customer Operations to obtain your username and password
2. Create the connection directly using the production URL (see [Service Endpoints](#service-endpoints) below)

### Service Endpoints

The Settlement API is available in both test and production environments. All endpoints use HTTPS and SOAP/WCF protocols.

| Environment | URL                                                        |
|-------------|------------------------------------------------------------|
| Test        | `https://test.borgun.is/settlement/creditcard.svc`         |
| Production | `https://services.borgun.is/settlement_3_7/creditcard.svc` |


### Authentication

Access to the Settlement API requires valid credentials and proper permissions. All API requests must be made over HTTPS using SOAP/WCF protocols. Your integration will need to consume the WSDL for the appropriate service endpoint to generate client code.

**Required credentials:**
- Username (provided by Customer Operations)
- Password (provided by Customer Operations)
- Merchant ID (MID)

## API Overview

The Settlement API provides operations for retrieving settlements, deductions and transactions.

### Available Operations

| Area        | Operation name                 | Description                                                      |
|-------------|--------------------------------|------------------------------------------------------------------|
| Settlements | `GetSettlementsByMerchant`     | List all settlements for a merchant within a date range          |
| Settlements | `GetSettlementByRunNumber`     | Get a single settlement by its settlement run number              |
| Transactions| `GetTransactionsByRunNumber`   | List all transactions included in a specific settlement            |
| Deductions | `GetSettlementDeductionItems` | List all deduction items (fees and adjustments) for a settlement |

## General Usage Guidelines

Every API response includes a `ResultStatus` object that indicates whether the operation succeeded or failed. This status object contains three fields:

- `ResultCode` - Numeric code indicating the result
- `ResultText` - Short text description of the result
- `ErrorMessage` - Detailed error message (only present when an error occurs)

| ResultCode | ResultText    | ErrorMessage              | Meaning                                                      |
|------------|---------------|---------------------------|--------------------------------------------------------------|
| `0`        | Success       | NULL                      | Operation completed successfully                             |
| `10`       | Informational | e.g.: Not found           | Non-critical issue occurred (e.g., no records found)         |
| `20`       | Warning       | A warning message         | Operation succeeded but with warnings                        |
| `30`       | Error         | Error condition explained | Operation failed; check `ErrorMessage` for details           |

When `ResultCode` is `0`, the response data is valid and can be processed. For codes `10` and `20`, the operation may have returned partial or empty results, but no error occurred. When `ResultCode` is `30`, the operation failed and you should examine the `ErrorMessage` field to understand what went wrong.

For full parameter and response details of each operation, see [API Reference](/reporting/api-endpoints).