Skip to main content

Customers and Payment Methods

Overview​

NGnair Payments allows you to manage customers and their payment methods. This guide covers the APIs for creating and managing customers, adding payment methods, and handling customer payment information securely.

Authentication​

All API requests must include your authentication token in the request headers:

  • token: Your authentication token

Example:

-H 'token: tok_123456789'

API Reference​

List Customers​

Retrieve a list of customers with pagination support.

Sort Options​

  • order: Specifies the sort direction
    • asc: Ascending order (A to Z, 0 to 9)
    • desc: Descending order (Z to A, 9 to 0)

Filter Operations​

  • contains: Field contains the specified value
  • equals: Field exactly matches the specified value
  • gt: Greater than the specified value
  • lt: Less than the specified value
  • gte: Greater than or equal to the specified value
  • lte: Less than or equal to the specified value
  • neq: Not equal to the specified value
POST /api/gateway/customers
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "page": {
      "page": 1,
      "pageSize": 10,
      "sort": {
        "field": "string",
        "order": "asc" | "desc"
      },
      "filter": [
        {
          "field": "string",
          "operation": "contains" | "equals" | "gt" | "lt" | "gte" | "lte" | "neq",
          "value": "string"
        }
      ],
      "search": "string"
    }
  }
}

Response​

{
  "data": [
    {
      "id": "string",
      "isDefault": boolean,
      "last4": "string",
      "brand": "string",
      "expires": "string",
      "name": "string",
      "city_state": "string",
      "zip": "string",
      "email": "string",
      "phone": "string"
    }
  ],
  "page": {
    "total": number,
    "range": {
      "from": number,
      "to": number
    },
    "page": number,
    "pageSize": number
  }
}

Add Customer​

Create a new customer with payment information.

POST /api/gateway/addCustomer
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "form": {
      "nameOnCard": "string",
      "email": "string",
      "phone": "string",
      "billingAddress": "string",
      "billingCity": "string",
      "billingState": "string",
      "billingZip": "string",
      "billingCountry": "string",
      "skipMultiTokenConvert": boolean,
      "gpecomm": {
        "id": "string",
        "cvv": "string"
      },
      "card": {
        "cvc": "string",
        "expiryDate": "string",
        "cardToken": "string"
      },
      "ach": {
        "accountNumber": "string",
        "routingNumber": "string",
        "accountType": "string",
        "accountHolderType": "string"
      }
    }
  }
}

Response​

{
  "customerID": "string",
  "paymentCardID": "string"
}

Get Customer Details​

Retrieve detailed information about a specific customer.

POST /api/gateway/customer
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "customerID": "string"
  }
}

Response​

{
  "id": "string",
  "nameOnCard": "string",
  "email": "string",
  "phone": "string",
  "billingAddress": "string",
  "billingCity": "string",
  "billingState": "string",
  "billingZip": "string",
  "billingCountry": "string",
  "paymentCards": [
    {
      "cardID": "string",
      "type": "string",
      "isDefault": boolean,
      "last4": "string",
      "brand": "string",
      "expires": "string",
      "cvc": "string",
      "accountNumber": "string",
      "routingNumber": "string",
      "accountType": "string",
      "accountHolderType": "string",
      "gpEcommID": "string"
    }
  ]
}

Update Customer​

Update an existing customer's information.

POST /api/gateway/updateCustomer
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "customerID": "string",
    "form": {
      "nameOnCard": "string",
      "email": "string",
      "phone": "string",
      "billingAddress": "string",
      "billingCity": "string",
      "billingState": "string",
      "billingZip": "string",
      "billingCountry": "string"
    }
  }
}

Response​

{
  "customerID": "string"
}

Delete Customer​

Remove a customer and their associated payment methods.

POST /api/gateway/deleteCustomer
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "customerID": "string"
  }
}

Response​

{
  "customerID": "string"
}

Add Payment Method​

Add a new payment method to an existing customer.

POST /api/gateway/addPaymentMethod
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "customerID": "string",
    "form": {
      "setAsDefault": boolean,
      "skipMultiTokenConvert": boolean,
      "card": {
        "cvc": "string",
        "expiryDate": "string",
        "cardToken": "string"
      },
      "ach": {
        "accountNumber": "string",
        "routingNumber": "string",
        "accountType": "string",
        "accountHolderType": "string"
      },
      "gpecomm": {
        "id": "string",
        "cvv": "string"
      }
    }
  }
}

Response​

{
  "customerID": "string",
  "paymentCardID": "string"
}

Delete Payment Method​

Remove a payment method from a customer.

POST /api/gateway/deletePaymentMethod
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "customerID": "string",
    "cardID": "string"
  }
}

Response​

{
  "customerID": "string"
}

Set Default Payment Method​

Set a payment method as the default for a customer.

POST /api/gateway/setDefaultPaymentMethod
-H 'token: string'
-H 'Content-Type: application/json'
{
  "data": {
    "customerID": "string",
    "cardID": "string"
  }
}

Response​

{
  "customerID": "string"
}

Sample API Requests​

List Customers Example​

Request:

POST /api/gateway/customers
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "page": {
      "page": 1,
      "pageSize": 10,
      "sort": {
        "field": "email",
        "order": "asc"
      },
      "filter": [
        {
          "field": "city_state",
          "operation": "contains",
          "value": "New York"
        }
      ],
      "search": "john"
    }
  }
}

Response:

{
  "data": [
    {
      "id": "cust_123456789",
      "isDefault": true,
      "last4": "4242",
      "brand": "visa",
      "expires": "12/25",
      "name": "John Doe",
      "city_state": "New York, NY",
      "zip": "10001",
      "email": "john.doe@example.com",
      "phone": "+1234567890"
    }
  ],
  "page": {
    "total": 1,
    "range": {
      "from": 1,
      "to": 1
    },
    "page": 1,
    "pageSize": 10
  }
}

Add Customer Example​

Request:

POST /api/gateway/addCustomer
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "form": {
      "nameOnCard": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "billingAddress": "123 Main St",
      "billingCity": "New York",
      "billingState": "NY",
      "billingZip": "10001",
      "billingCountry": "US",
      "card": {
        "cvc": "123",
        "expiryDate": "12/25",
        "cardToken": "tok_visa_4242"
      }
    }
  }
}

Response:

{
  "customerID": "cust_123456789",
  "paymentCardID": "card_123456789"
}

Add Payment Method Example​

Request:

POST /api/gateway/addPaymentMethod
-H 'token: tok_123456789'
-H 'Content-Type: application/json'
{
  "data": {
    "customerID": "cust_123456789",
    "form": {
      "setAsDefault": true,
      "card": {
        "cvc": "123",
        "expiryDate": "12/25",
        "cardToken": "tok_visa_4242"
      }
    }
  }
}

Response:

{
  "customerID": "cust_123456789",
  "paymentCardID": "card_987654321"
}