Customers

The customers endpoint is your access to the FarPay customer database. Use case scenarios are:

• Get all customers
• Get a single customer, with a recurring payment instrument details
• Create a new customer
• Update existing customer
• Send an invitation email to the customer, so that the customer can create a recurring payment instrument.

Remark that all requests must have an X-API-KEY, and a Accept mentioned in the header of the request.

Definitions

Get all customers

Use the https://api.farpay.io/v2/customers for retreiving all customers. The objects hold all the details

Get a single customer

Use the https://api.farpay.io/v2/customers/{customer number} e.g. with customer number= 23.

Create a new customer

To create a customer, the endpoint accepts both XML and JSON as payload of the customer data. In this example JSON is used. Remark that the customer object has a minimum set of required properties, for the system to be used fully. They are:

• CustomerNumber
• Name
• Email

{
  "CustomerNumber": "string",
  "Name": "string",
  "Email": "string",
  "PoBox": "string",
  "Street": "string",
  "AdditionalStreet": "string",
  "HouseNumber": "string",
  "PostCode": "string",
  "City": "string",
  "Country": "string",
  "AttachPdfInvoice": false,
  "Language": "Danish"
}

The AttachPdfInvoice is used when you want to distribute the PDF-invoice with the invoice email. Remark that the common log of monitoring the customer when the invoice is opend, or when downloaded are with this setting inaccurate.

The Language setting should only be used for language variations, meaning of your company communicates in one language, the customers who read the same language, do not need this property to be set, while others can.

Update an existing customer

The customer can be updated by a PUT from https://api.farpay.io/v2/customers/ Compared to the create, there are some limitations of what can be updated. The updates can be done on:

• Name
• All the address properties
• Email
• AttachPdfInvoice
• Language

An example update could be an norewgian customer, now residing in the UK:

{
  "CustomerNumber": "string",
  "Name": "John Smith",
  "PoBox": "2301",
  "Email": "[email protected]",
  "Street": "Marksquare",
  "AdditionalStreet": "Wellington st.",
  "HouseNumber": "4",
  "PostCode": "3422",
  "City": "Bristol",
  "Country": "United Kingdom",
  "AttachPdfInvoice": false,
  "Language": "Norwegian"
}

Delete customer BETA

To delete the customer, the customer and subsequent invoices and payments will be removed from the system.

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

Response

The response will return with a statuscode, corresponding to the outcome of the operation. Available codes are:

Send an email for creating a payment agreement

When you want FarPay to send an email to your customer with the ability to create a recurring payment instrument, the endpoint GET to https://api.farpay.io/v2/customers/{customer number}/agreementRequest?type={type}&email={email}' There are three parmeters that must be set when making this call:

Type values and definition

The type sets what payment instrument shoul be shown, when the customer creates a payment agreement. See values, and the description below.

Back to the overview

Overview

The FarPay API allows you to manage customers and payment instruments. Typical use cases include:

• Retrieving customer data
• Creating and updating customers
• Sending invitation emails to initiate payment agreements
• Managing recurring payment instruments

Authentication

All requests require the following headers:

X-API-KEY: YOUR_API_KEY
Accept: application/json

Endpoints

[GET] /v2/customers

Retrieves all customers from your FarPay database.

Request Example

curl https://api.farpay.io/v2/customers \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

Response Example

[
  {
    "CustomerNumber": "123",
    "Name": "John Doe",
    "Email": "[email protected]"
  }
]

[GET] /v2/customers/{customerNumber}

Retrieves a specific customer and their recurring payment instrument details.

Path Parameters

Request Example

curl https://api.farpay.io/v2/customers/23 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

[POST] /v2/customers

Creates a new customer.

Request Body (JSON)

{
  "CustomerNumber": "string",
  "Name": "string",
  "Email": "string",
  "PoBox": "string",
  "Street": "string",
  "AdditionalStreet": "string",
  "HouseNumber": "string",
  "PostCode": "string",
  "City": "string",
  "Country": "string",
  "AttachPdfInvoice": false,
  "Language": "Danish"
}

Property Descriptions

[PUT] /v2/customers

Updates an existing customer's data.

Request Example

{
  "CustomerNumber": "string",
  "Name": "John Smith",
  "PoBox": "2301",
  "Email": "[email protected]",
  "Street": "Marksquare",
  "AdditionalStreet": "Wellington st.",
  "HouseNumber": "4",
  "PostCode": "3422",
  "City": "Bristol",
  "Country": "United Kingdom",
  "AttachPdfInvoice": false,
  "Language": "Norwegian"
}

Updatable Fields

• Name
• Email
• PoBox
• Street
• AdditionalStreet
• HouseNumber
• PostCode
• City
• Country
• AttachPdfInvoice
• Language

[DELETE] /v2/customers/{customerNumber} (BETA)

Deletes a customer along with associated invoices and payments.

Path Parameters

Request Example

curl -X DELETE https://api.farpay.io/v2/customers/23 \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

Response Codes

[GET] /v2/customers/{customerNumber}/agreementRequest

Sends an email to the customer allowing them to set up a recurring payment agreement.

Path Parameters

Query Parameters

Type Options

Request Example

curl "https://api.farpay.io/v2/customers/23/agreementRequest?type=card&[email protected]" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

Error Codes

Rate Limiting

Rate limits are not currently documented for this API.