Payment Sets

Overview

Payment Sets represent collections of payments that were processed together on a specific date with the same payment type. This is particularly relevant for:

• Betalingsservice (BS) payments
• Leverandørservice (LS) payments
• Bank transfers and other batch-processed payments

API Endpoints

Get Payment Sets

Retrieve payment sets for a specific date range.

GET https://api.farpay.io/v2/paymentsets

Query Parameters:

• fromDate (optional) - Start date (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)
• toDate (optional) - End date (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS)

Response Example:

[
  {
    "ID": 1,
    "PaymentDate": "2023-01-15T00:00:00Z",
    "Amount": 12500.50,
    "PaymentType": "BS",
    "PaymentStatus": "Paid",
    "PaymentCount": 45
  },
  {
    "ID": 2,
    "PaymentDate": "2023-01-15T00:00:00Z",
    "Amount": 8750.25,
    "PaymentType": "LS",
    "PaymentStatus": "Paid",
    "PaymentCount": 23
  }
]

Get Payment Set Details

Retrieve detailed information for a specific payment set, including all individual payments.

GET https://api.farpay.io/v2/paymentsets/{paymentSetId}

Parameters:

• paymentSetId (path) - The payment set's unique identifier

Response Example:

{
  "PayeeParty": {
    "ID": {
      "Value": "12345678",
      "schemaID": "DK:CVR"
    }
  },
  "BankTotal": {
    "NumberOfPayments": 45,
    "Payment": 12500.50
  },
  "Payments": [
    {
      "AgreementNumber": "BS-001",
      "PaymentType": "BS",
      "PaymentStatus": "Paid",
      "PaymentSign": "Payment",
      "Amount": 250.00,
      "PaymentReference": "REF-001",
      "PaymentDate": "2023-01-15T00:00:00Z",
      "InvoiceNumber": "INV-001",
      "CustomerNumber": "12345",
      "InvoiceId": 123,
      "PaymentInfo": "Customer payment",
      "PaymentId": 456
    }
  ]
}

Payment Set Properties

Core Properties

Payment Set Details Properties

Payee Party Properties

Bank Total Properties

Individual Payment Properties

Date Format Options

Date-Only Format

When using YYYY-MM-DD format, the system automatically sets:

• fromDate: Beginning of the day (00:00:00)
• toDate: End of the day (23:59:59)

Date-Time Format

For more precise control, use YYYY-MM-DD HH:MM:SS format.

Examples

Get payments for a single day:

GET https://api.farpay.io/v2/paymentsets?fromDate=2023-01-15&toDate=2023-01-15

Get payments for a specific time range:

GET https://api.farpay.io/v2/paymentsets?fromDate=2023-01-15 09:00:00&toDate=2023-01-15 17:00:00

Use Cases

Reconciliation

Payment sets are ideal for reconciling bank statements with your payment records:

1. Get payment sets for the date range matching your bank statement
2. Compare totals with bank statement amounts
3. Verify individual payments using the detailed view

Reporting

Generate reports on payment processing:

// Get all BS payments for January 2023
const response = await fetch('https://api.farpay.io/v2/paymentsets?fromDate=2023-01-01&toDate=2023-01-31', {
  headers: {
    'X-API-KEY': 'your-api-key',
    'Accept': 'application/json'
  }
});

const paymentSets = await response.json();
const bsPayments = paymentSets.filter(set => set.PaymentType === 'BS');

Batch Processing

Monitor batch payment processing:

// Check if today's payments have been processed
const today = new Date().toISOString().split('T')[0];
const response = await fetch(`https://api.farpay.io/v2/paymentsets?fromDate=${today}&toDate=${today}`);

const todaysSets = await response.json();
console.log(`Processed ${todaysSets.length} payment sets today`);

Error Handling

Common Error Responses

Date Validation

• fromDate must be before or equal to toDate
• Date format must be YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
• Invalid date formats will return a 400 error

Best Practices

1. Use appropriate date ranges - Avoid very large date ranges that may timeout
2. Cache payment set data - Payment sets don't change once created
3. Handle empty responses - Check for 204 status when no data is found
4. Validate totals - Always verify payment set totals match individual payments

Related Endpoints

• Payments - Individual payment information
• Agreements - Payment agreement management
• Invoices - Invoice and payment tracking