Customers

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

Optional Properties

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": "[email protected]",
    "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": "[email protected]",
  "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": "[email protected]",
  "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": "[email protected]",
  "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:

Example Request:

GET https://api.farpay.io/v2/customers/12345/agreementRequest?type=card&[email protected]

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

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

Error Handling

Common customer-related errors:

Related Resources

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