Manage Customers with the API

In Payabli, customers are the entities that buy goods and services and make payments to your paypoints (merchants). This guide explains how to manage customers with the API.

Custom identifiers

By default, when working with the API on any task that involves customer data, you must include at least one of these identifier fields:

• firstname and lastname
• email
• customerId

These tasks include things like making transactions, working with customer records, managing invoices, and more. Payabli first searches to match customer records based on your custom identifiers. If you don’t have any custom identifiers set, then Payabli falls back to matching on customerId.

Payabli recommends using the system-generated customerId field to identify customers for ease of integration and consistency. However, you can configure custom identifiers, which lets you decide which customer profile fields to use to uniquely identify and associate customer records and payments.

Custom identifiers cascade from org parent to child entities, so you can set them at the organization level and have them apply to all child paypoints. This is useful if you want to use a specific field across all your customers, such as email or clientId.

For example. if your company uses the customer’s email address as their unique identifier, you can choose email as the identifier. If your organization prefers to identify customers by a field called clientId, you can create that custom field in Payabli and set it as an identifier. This means that every API call that involves a customer must include the clientID because Payabli uses that field to search for customers.

Pass custom identifiers in the customerData.additionalData object like this:

1
"customerData": {
2
  "additionalData": {
3
    "YourCustomIdentifier": "123"
4
      }
5
    }

Create a customer

To create a customer record, send a POST request to the /api/Customer/single/{entry} endpoint. For complete details, see the API reference for this endpoint.

The add customer request has these optional parameters:

The body is where you include information about the customer, including identifiers. An identifier is required to create customer records. You can change your identifier settings in Settings > Custom Fields in PartnerHub.

When you create a new customer record, Payabli first looks for an existing customer based on matching any of your configured identifier fields. If Payabli doesn’t find a match, then it attempts to match based on the CustomerNumber field, if included. If there is no match, Payabli creates a new customer.

This example creates a customer record. It includes firstname and lastname as the minimum required identifiers, as set in the example account.

1
curl -X POST https://api-sandbox.payabli.com/api/Customer/single/8cfec329267 \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "address1": "123 Bishop\'s Trail",
6
  "city": "Mountain City",
7
  "country": "US",
8
  "customerNumber": "12356ACB",
9
  "email": "irene@canizalesconcrete.com",
10
  "firstname": "Irene",
11
  "identifierFields": [
12
    "email"
13
  ],
14
  "lastname": "Canizales",
15
  "state": "TN",
16
  "timeZone": -5,
17
  "zip": "37612"
18
}'

A successful request returns a JSON response. The customerId value is the Payabli-generated identifier that you can use with other endpoints to manage the customer and make transactions.

1
{
2
  "isSuccess": true,
3
  "responseData": {
4
    "AdditionalFields": {
5
      "key": "value"
6
    },
7
    "Address1": "123 Bishop's Trail",
8
    "Balance": 0,
9
    "City": "Mountain City",
10
    "Country": "US",
11
    "Created": "2024-03-13T12:49:56Z",
12
    "customerId": 17264,
13
    "customerNumber": "12356ACB",
14
    "customerStatus": 0,
15
    "customerSummary": {
16
      "numberofTransactions": 30,
17
      "recentTransactions": [
18
        {
19
          "EntrypageId": 0,
20
          "FeeAmount": 1,
21
          "PayorId": 1551,
22
          "PaypointId": 226,
23
          "SettlementStatus": 2,
24
          "TotalAmount": 30.22,
25
          "TransStatus": 1
26
        }
27
      ],
28
      "totalAmountTransactions": 1500,
29
      "totalNetAmountTransactions": 1500
30
    },
31
    "Email": "irene@canizalesconcrete.com",
32
    "Firstname": "Irene",
33
    "IdentifierFields": [
34
      "email"
35
    ],
36
    "Lastname": "Canizales",
37
    "LastUpdated": "2024-03-13T12:49:56Z",
38
    "MFA": false,
39
    "MFAMode": 0,
40
    "pageidentifier": "null",
41
    "ParentOrgName": "The Pilgrim Planner",
42
    "PaypointDbaname": "Gruzya Adventure Outfitters",
43
    "PaypointEntryname": "41035afaa7",
44
    "PaypointLegalname": "Gruzya Adventure Outfitters, LLC",
45
    "State": "TN",
46
    "TimeZone": -5,
47
    "Zip": "37612"
48
  },
49
  "responseText": "Success"
50
}

Import customers

You can import a list of customers into Payabli using the API. This is useful if you have a large number of customers to add at once, or if you want to automate the process. Before you get started, download the example CSV file and open it with the editor of your choice. Use it as an example to help you build your import file.

To import a list of customer, send a POST request to the /api/Import/customersForm/{entrypoint} endpoint, with an attached CSV file.

When importing customers, there is an optional query parameter:

This example imports customerImport.csv for the entrypoint e56ce00572.

1
curl -X POST https://api-sandbox.payabli.com/api/Import/customersForm/8cfec329267 \
2
     -H "requestToken: <apiKey>" \
3
     -H "Content-Type: multipart/form-data" \
4
     -F file=@<file1>

A successful request returns a JSON response with the number of added and rejected records, and any errors. The imported data is now available for use, and you can confirm by checking PartnerHub or PayHub.

1
{
2
  "isSuccess": true,
3
  "pageIdentifier": "null",
4
  "responseCode": 1,
5
  "responseData": {
6
    "added": 26,
7
    "errors": [
8
      "errors",
9
      "errors"
10
    ],
11
    "rejected": 2
12
  },
13
  "responseText": "Success"
14
}

After you import customers, you can manage them with the API. For example, you can update customer information, check customer status, and run payments for customers.

Customer status

In customer endpoints and endpoints that return customer data, the customer status field is customerStatus.

Managing customers

You can also manage customers via the API. See these endpoint references for more information:

• Update Customer
• Delete Customer
• Get Customer