Invoices

Overview

Invoices represent bills sent to customers for payment. Each invoice has a payment state that tracks its progress through the payment lifecycle, from creation to completion or failure.

Invoice Payment States

State	Value	Description
Not Paid	100	Initial state when invoice is created
Paid	200	Payment received and matches invoice amount
Scheduled	300	Customer has agreement, payment scheduled
Pending	400	Scheduled payment being processed
Rejected	500	Payment rejected by user, creditor, or financial institution
Chargeback	600	Amount charged back, transaction reversed
Payment Failed	700	Payment failed due to agreement removal or low balance
N/A	1000	System errors or payment system errors

API Endpoints

Get All Invoices

Retrieve all invoices with optional filtering.

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

Query Parameters:

fromDueDate (optional) - Filter from due date (YYYY-MM-DD)
toDueDate (optional) - Filter to due date (YYYY-MM-DD)
paymentStatus (optional) - Filter by payment status (100, 200, 300, 400, 500, 600, 700)

Response Example:

[
  {
    "Id": 123,
    "Created": "2025-09-15T10:30:00Z",
    "InvoiceNumber": "INV-001",
    "PaymentDueDate": "2025-09-15T00:00:00Z",
    "InvoiceAmount": 125.00,
    "ToBePaidAmount": 125.00,
    "PaymentReferenceStatus": "Ok",
    "PaymentType": "MobilePayInvoice",
    "SendStatus": "Queue",
    "ErrorDescription": ""
  }
]

Get Single Invoice

Retrieve detailed information for a specific invoice.

GET https://api.farpay.io/v2/invoices/{invoiceId}

Parameters:

invoiceId (path) - The invoice's unique identifier

Response Example:

{
  "Send": {
    "SentDate": "0001-01-01T00:00:00",
    "ErrorCode": 0,
    "ErrorDescription": "",
    "Channel": "",
    "Status": "Queue",
    "ScheduleSendDate": null,
    "ToAddress": "",
    "Note": ""
  },
  "Id": 74836045,
  "Token": "wN0BNaBoW2DMfx5DeVasQMgs508JbuO8",
  "PaymentDetails": "+71 <000004561237944 +42426240<",
  "MarkedAsPaid": null,
  "Created": "2025-09-24T09:54:57.57",
  "InvoiceTypeCode": "PIE",
  "InvoiceDate": "24-09-2025",
  "InvoiceAmount": 125,
  "TaxAmount": 25,
  "ToBePaidAmount": 125,
  "Ean": null,
  "InvoiceNote": null,
  "InvoiceWasPaidManually": null,
  "InvoiceNumber": "2525",
  "PaymentDueDate": "2025-09-24T00:00:00",
  "Currency": "DKK",
  "Recepient": {
    "CustomerNumber": "1",
    "CompanyNo": null,
    "Gln": null,
    "Name": "John Doe",
    "Email": "[email protected]",
    "Street": null,
    "PostCode": null,
    "PoBox": null,
    "City": null,
    "Country": null,
    "ContactId": null,
    "ContactName": null,
    "ContactPhone": null,
    "ContactEmail": null
  },
  "Buyer": null,
  "Destination": null,
  "SchedulePayment": 0,
  "PaymentReference": null,
  "PaymentStatus": 100,
  "PaymentType": null,
  "InvoiceStatus": "Ok",
  "PaymentRejectedBy": null,
  "PdfInvoice": null,
  "PdfAttachments": null,
  "InvoiceLines": [
    {
      "LineNumber": 1,
      "ProductNumber": null,
      "Description": "Monthly subscription",
      "BasePrice": 100,
      "Quantity": 1,
      "UnitCode": null,
      "DiscountRate": 0,
      "DiscountedPrice": 0,
      "TaxRate": 0.25,
      "TaxAmount": 25,
      "Amount": 125
    }
  ],
  "TextLines": null,
  "Template": null,
  "OrderToken": null
}

Create Invoice

Create a new invoice for a customer.

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

Request Body:

{
  "InvoiceDate": "2025-09-24",
  "InvoiceAmount": 125,
  "TaxAmount": 25,
  "ToBePaidAmount": 125,
  "Recepient": {
    "CustomerNumber": "1"
  },
  "InvoiceLines": [
    {
      "Description": "Monthly subscription",
      "BasePrice": 100,
      "Quantity": 1,
      "TaxRate": 0.25,
      "TaxAmount": 25,
      "Amount": 125
    }
  ]
}

Update Invoice

Update an existing invoice.

PUT https://api.farpay.io/v2/invoices/{invoiceId}

Request Body:

{
  "PaymentDueDate": "2025-09-15",
  "InvoiceLines": [
    {
      "Description": "Updated subscription",
      "Quantity": 1,
      "BasePrice": 150.00,
      "Amount": 150.00
    }
  ]
}

Delete Invoice

Delete an invoice (only possible in certain states).

DELETE https://api.farpay.io/v2/invoices/{invoiceId}

Invoice Properties

Core Properties

Property	Type	Description	Constraints
`Id`	integer	FarPay unique invoice identifier	Auto-generated
`Created`	datetime	Invoice creation timestamp	ISO 8601 format
`InvoiceNumber`	string	Your invoice number	Required, unique
`PaymentDueDate`	date	When payment is due	YYYY-MM-DD format
`InvoiceAmount`	decimal	Total invoice amount	2 decimal places
`ToBePaidAmount`	decimal	Remaining amount to be paid	2 decimal places
`PaymentReferenceStatus`	string	Payment reference status	"Ok", "Error", etc.
`PaymentType`	string	Payment method type	See Payment Types
`SendStatus`	string	Communication status	See Send Status
`ErrorDescription`	string	Error details if any	Optional

Customer Information

Property	Type	Description
`CustomerNumber`	string	Customer's unique identifier
`Name`	string	Customer's full name
`Email`	string	Customer's email address

Invoice Lines

Property	Type	Description
`Description`	string	Line item description
`Quantity`	decimal	Quantity of items
`UnitPrice`	decimal	Price per unit
`TotalPrice`	decimal	Total line price

Payment Types

Type	Description
`MobilePayInvoice`	MobilePay invoice payment
`MobilePaySubscriptions`	MobilePay subscription
`Betalingsservice`	Direct debit for private customers
`Leverandørservice`	Direct debit for businesses
`FI`	Manual payment (Faktura)
`Dankort`	Danish debit card
`Visa`	Visa credit/debit card
`MasterCard`	MasterCard credit/debit card

Send Status

The SendStatus indicates how the invoice will be processed regarding customer communication:

Status	Description
`Queue`	Invoice queued for sending
`Sent`	Invoice sent to customer
`Failed`	Failed to send invoice
`Pending`	Awaiting processing

Invoice Filtering

Date Range Filtering

Filter invoices by due date range:

GET https://api.farpay.io/v2/invoices?fromDueDate=2023-01-01&toDueDate=2023-01-31

Payment Status Filtering

Filter invoices by payment status:

GET https://api.farpay.io/v2/invoices?paymentStatus=200

Available status values: 100, 200, 300, 400, 500, 600, 700

Invoice Lifecycle

Create Invoice - POST invoice details to create new invoice
Send to Customer - Invoice is automatically sent based on SendStatus
Customer Receives - Customer receives invoice via email/SMS
Payment Processing - Customer pays through chosen payment method
Status Updates - Invoice status updates as payment progresses
Completion - Invoice marked as Paid or other final state

Best Practices

Invoice Numbers: Use meaningful, unique identifiers for tracking
Due Dates: Set realistic payment due dates
Payment Types: Choose appropriate payment methods for your customers
Invoice Lines: Provide clear, detailed line item descriptions
Error Handling: Monitor ErrorDescription for failed invoices
Status Monitoring: Regularly check invoice status for payment tracking

Error Handling

Common invoice-related errors:

Error	Description	Solution
`Invoice number already exists`	Duplicate invoice number	Use unique invoice numbers
`Customer not found`	Invalid customer number	Verify customer exists
`Invalid payment type`	Unsupported payment method	Check available payment types
`Invalid due date`	Due date in the past	Set future due dates
`Invoice cannot be updated`	Invoice in locked state	Check current invoice status

Integration Examples

Create Invoice with Multiple Lines

{
  "CustomerNumber": "12345",
  "InvoiceNumber": "INV-002",
  "PaymentDueDate": "2025-09-15",
  "PaymentType": "MobilePayInvoice",
  "InvoiceLines": [
    {
      "Description": "Basic subscription",
      "Quantity": 1,
      "BasePrice": 99.00,
      "Amount": 99.00
    },
    {
      "Description": "Premium add-on",
      "Quantity": 1,
      "BasePrice": 26.00,
      "Amount": 26.00
    }
  ]
}

Monitor Invoice Status

// Check invoice status
const invoice = await fetch(`/invoices/123`);
const status = invoice.PaymentReferenceStatus;

if (status === 'Ok') {
  console.log('Invoice is active');
} else if (status === 'Error') {
  console.log('Invoice has errors:', invoice.ErrorDescription);
}

Related Resources

Customers - Manage customer information
Payments - Track payment history
Orders - Create payment flows
Agreements - Handle recurring payments