Overview

A Customer is a person or business that receives invoices from your company and can pay using FarPay's payment technology. Customers can have Payment Instruments (agreements) that enable recurring payments.

A Customer is a person or business that receives invoices from your company and can pay using FarPay's payment technology. Customers can have Payment Instruments (agreements) that enable recurring payments.

Customer Object

Required Properties

Property	Type	Description	Constraints
`CustomerNumber`	string	Unique customer identifier	Max 15 digits
`Name`	string	Customer's full name	Max 255 characters
`Email`	string	Customer's email address	Max 255 characters

Optional Properties

Property	Type	Description	Constraints
`PoBox`	string	Post office box	Max 20 characters
`Street`	string	Street address	Max 255 characters
`AdditionalStreet`	string	Additional address line	Max 255 characters
`HouseNumber`	string	House/building number	Max 10 characters
`PostCode`	string	Postal code	Max 20 characters
`City`	string	City name	Max 255 characters
`Country`	string	Country name	Max 255 characters
`AttachPdfInvoice`	boolean	Include PDF with invoice emails	Default: false
`Language`	string	Communication language	"Danish", "English", "Faroese", "Norwegian"

API Endpoints

Get All Customers

Retrieve all customers in your account.

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

Response Example:

[
  {
    "CustomerNumber": "12345",
    "Name": "John Smith",
    "Email": "john@example.com",
    "Street": "Main Street 123",
    "City": "Copenhagen",
    "PostCode": "1000",
    "Country": "Denmark",
    "AttachPdfInvoice": false,
    "Language": "English"
  }
]

Get Single Customer

Retrieve detailed information for a specific customer.

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

Parameters:

customerNumber (path) - The customer's unique identifier

Response Example:

{
  "CustomerNumber": "12345",
  "Name": "John Smith",
  "Email": "john@example.com",
  "Street": "Main Street 123",
  "City": "Copenhagen",
  "PostCode": "1000",
  "Country": "Denmark",
  "AttachPdfInvoice": false,
  "Language": "English",
  "Agreements": [
    {
      "Id": 1,
      "Type": "Card",
      "Status": "Active",
      "Details": "Visa|4444xxxxxxxx1234|12/25"
    }
  ]
}

Create Customer

Create a new customer in your account.

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

Request Body:

{
  "CustomerNumber": "12345",
  "Name": "John Smith",
  "Email": "john@example.com",
  "Street": "Main Street 123",
  "City": "Copenhagen",
  "PostCode": "1000",
  "Country": "Denmark",
  "AttachPdfInvoice": false,
  "Language": "English"
}

Response: Returns the created customer object with HTTP 201 status.

Update Customer

Update an existing customer's information.

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

Updatable Properties:

Name
Email
All address properties (Street, City, PostCode, etc.)
AttachPdfInvoice
Language

Request Body:

{
  "CustomerNumber": "12345",
  "Name": "John Smith Updated",
  "Email": "john.updated@example.com",
  "Street": "New Street 456",
  "City": "Aarhus",
  "PostCode": "8000",
  "Country": "Denmark",
  "AttachPdfInvoice": true,
  "Language": "Danish"
}

Delete Customer (Beta)

Delete a customer and all associated data.

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

Response Codes:

200 - Customer successfully deleted
400 - CustomerNumber missing from URI
404 - Customer not found

Payment Agreement Requests

Send Agreement Invitation Email

Send an email to a customer inviting them to create a payment agreement.

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

Query Parameters:

type (required) - Payment type to offer
email (required) - Email address to send invitation to

Payment Types:

Type	Description
`mp`	MobilePay Subscriptions
`card`	Visa, MasterCard, or Dankort
`bs`	Betalingsservice (direct debit for private customers)
`ls`	Leverandørservice (direct debit for businesses)
`all`	All available payment types

Example Request:

GET https://api.farpay.io/v2/customers/12345/agreementRequest?type=card&email=customer@example.com

Language Settings

The Language property controls communication language:

Default behavior: If your company communicates in one language, customers reading the same language don't need this property set
Use cases: Set for customers who prefer different languages than your default
Available options: "Danish", "English", "Faroese", "Norwegian"

PDF Invoice Attachments

The AttachPdfInvoice setting controls whether customers receive PDF invoices via email:

true: Customer receives PDF attachments with invoice emails
false: Customer receives invoice emails without PDF attachments

Note: When PDF attachments are enabled, monitoring customer behavior (email opens, downloads) may be less accurate.

Best Practices

Customer Numbers: Use meaningful, unique identifiers that work with your existing systems
Email Validation: Ensure email addresses are valid and active
Address Information: Provide complete address details for better payment processing
Language Preferences: Set appropriate language for international customers
PDF Attachments: Consider customer preferences and monitoring needs when setting this option

Error Handling

Common customer-related errors:

Error	Description	Solution
`CustomerNumber already exists`	Duplicate customer number	Use a unique customer number
`Invalid email format`	Email address is malformed	Check email format
`Customer not found`	Customer doesn't exist	Verify customer number
`Required field missing`	Missing required properties	Include all required fields

Related Resources

Orders - Create payment flows for customers
Agreements - Manage payment instruments
Invoices - Generate invoices for customers