Agreements

Overview

Agreements are recurring payment instruments that allow customers to pay invoices automatically. They can be created for bank-based direct debits (Betalingsservice/Leverandørservice) via API, while card agreements require secure customer interaction.

Agreement Types

Agreement States

Note: Processing time varies by agreement type:

• Cards & MobilePay: Created instantly
• BS/LS: Processed in batches during evening/night hours

API Endpoints

Get All Agreements

Retrieve all payment agreements for your customers.

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

Response Example:

[
  {
    "Id": 1,
    "Type": "Card",
    "Status": "Ok",
    "CustomerNumber": "12345",
    "PayerID": "",
    "Details": "Card|Visa|4444xxxxxxxx1234|12/25",
    "StartDate": "2023-01-15T10:30:00Z",
    "ExpireDate": "2025-12-31T23:59:59Z"
  },
  {
    "Id": 2,
    "Type": "BS",
    "Status": "Ok",
    "CustomerNumber": "67890",
    "PayerID": "1234567890",
    "Details": "12345678",
    "StartDate": "2023-01-15T10:30:00Z",
    "ExpireDate": ""
  }
]

Get Single Agreement

Retrieve detailed information for a specific agreement.

GET https://api.farpay.io/v2/agreements/{id}

Parameters:

• id (path) - The agreement's unique identifier

Create Agreement

Create a new bank-based agreement (BS or LS only).

POST https://api.farpay.io/v2/agreements

Request Body:

{
  "BankRegNumber": "1234",
  "BankAccountNumber": "12345678",
  "Type": "BS",
  "CustomerNumber": "12345",
  "PayerID": "1234567890"
}

Cancel Agreement

Cancel an existing agreement.

DELETE https://api.farpay.io/v2/agreements/{id}

Parameters:

• id (path) - The agreement's unique identifier

Agreement Properties

Core Properties

Agreement Details by Type

Creating Bank Agreements

Betalingsservice (BS) Agreement

For private customers with Danish CPR numbers.

Request Body:

{
  "BankRegNumber": "1234",
  "BankAccountNumber": "12345678",
  "Type": "BS",
  "CustomerNumber": "12345",
  "PayerID": "1234567890"
}

Requirements:

• BankRegNumber: 4-digit Danish bank registration number
• BankAccountNumber: 7-8 digit account number
• PayerID: Danish CPR number (10 digits)
• CustomerNumber: Must match existing customer

Leverandørservice (LS) Agreement

For businesses with Danish CVR numbers.

Request Body:

{
  "BankRegNumber": "1234",
  "BankAccountNumber": "12345678",
  "Type": "LS",
  "CustomerNumber": "12345",
  "PayerID": "12345678"
}

Requirements:

• BankRegNumber: 4-digit Danish bank registration number
• BankAccountNumber: 7-8 digit account number
• PayerID: Danish CVR number (8 digits)
• CustomerNumber: Must match existing customer

Card and MobilePay Agreements

Card and MobilePay agreements cannot be created directly via API due to security requirements. They must be created through:

1. Customer interaction in the Payment Window
2. Email invitations sent to customers
3. Order creation with agreement requirements

Creating Card Agreements via Orders

{
  "ExternalID": "AGREEMENT-001",
  "AcceptUrl": "https://company.com/accept",
  "CancelUrl": "https://company.com/cancel",
  "CallbackUrl": "https://company.com/callback",
  "Lang": "da",
  "Agreement": 1,
  "PaymentTypes": "card",
  "Customer": {
    "CustomerNumber": "12345",
    "CustomerName": "John Smith",
    "CustomerEmail": "[email protected]"
  }
}

Agreement Management

Finding Customer Agreements

Agreements are linked to customers and can be found in the customer endpoint:

GET https://api.farpay.io/v2/customers/{customerNumber}

Response includes agreements:

{
  "CustomerNumber": "12345",
  "Name": "John Smith",
  "Email": "[email protected]",
  "Agreements": [
    {
      "Id": 1,
      "Type": "Card",
      "Status": "Ok",
      "Details": "Visa|4444xxxxxxxx1234|12/25"
    }
  ]
}

Canceling Agreements

When an agreement is canceled:

1. Future invoices scheduled for automatic payment become manual invoices
2. Manual invoices receive an FI (Faktura) payment type
3. Customer notification is sent about the cancellation

Cancel Agreement:

DELETE https://api.farpay.io/v2/agreements/1

Agreement Validation

Bank Account Validation

The relationship between bank account and PayerID is critical:

• BS agreements: PayerID (CPR) must match the account owner
• LS agreements: PayerID (CVR) must match the business account owner
• Validation: Financial institutions verify this relationship
• Rejection: Agreements are rejected if no match is found

Business vs Private Accounts

• Betalingsservice: Can hold both private and business accounts
• Leverandørservice: Business accounts only
• Account type: Must match the agreement type

Best Practices

1. Customer Verification: Ensure customer exists before creating agreements
2. Bank Information: Verify bank account details with customers
3. PayerID Validation: Confirm CPR/CVR numbers are correct
4. Agreement Monitoring: Regularly check agreement status
5. Cancellation Handling: Implement proper cancellation workflows
6. Error Handling: Monitor failed agreement creations

Error Handling

Common agreement-related errors:

Integration Examples

Create BS Agreement

// Create Betalingsservice agreement
const agreement = {
  BankRegNumber: "1234",
  BankAccountNumber: "12345678",
  Type: "BS",
  CustomerNumber: "12345",
  PayerID: "1234567890"
};

try {
  const response = await fetch('/agreements', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'your-api-key'
    },
    body: JSON.stringify(agreement)
  });
  
  console.log('Agreement created:', response);
} catch (error) {
  console.error('Agreement creation failed:', error);
}

Monitor Agreement Status

// Check agreement status
const agreements = await fetch('/agreements');
const activeAgreements = agreements.filter(a => a.Status === 'Ok');

console.log(`Active agreements: ${activeAgreements.length}`);

// Check for pending agreements
const pendingAgreements = agreements.filter(a => a.Status === 'Pending');
if (pendingAgreements.length > 0) {
  console.log('Pending agreements:', pendingAgreements);
}

Cancel Agreement

// Cancel agreement
const agreementId = 1;

try {
  await fetch(`/agreements/${agreementId}`, {
    method: 'DELETE',
    headers: {
      'X-API-KEY': 'your-api-key'
    }
  });
  
  console.log('Agreement canceled successfully');
} catch (error) {
  console.error('Agreement cancellation failed:', error);
}

Related Resources

• Customers - Manage customer information
• Orders - Create payment flows and agreements
• Payments - Track payment history
• Invoices - Generate invoices for customers