Create and Manage Your Customers Using the PayGood API

Customers represent the people or organizations you transact with through PayGood. Every customer is scoped to a specific merchant. Use entityType: "individual" for a person and entityType: "organization" for a business.

Create an individual customer

Send a POST /merchants/{merchantId}/customers request with firstName, lastName, and email. Include an idempotencyKey to make the request safely retryable.

curl -X POST https://api.paygood.co/merchants/mer_01hxy8m1nqk9g3x3y3p0azq2bg/customers \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityType": "individual",
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "idempotencyKey": "cust-create-001"
  }'

PayGood returns the created customer record with a unique customerId.

{
  "customerId": "cus_01hxy4m2nqk9g3x3y3p0azq1cf",
  "name": "Jane Smith",
  "displayName": "Jane Smith",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@example.com",
  "entityType": "individual",
  "phone": "+15551234567",
  "createdAt": "2024-06-01T12:00:00Z"
}

Create an organization customer

For a business customer, set entityType to organization and pass organizationName instead of firstName and lastName.

curl -X POST https://api.paygood.co/merchants/mer_01hxy8m1nqk9g3x3y3p0azq2bg/customers \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "entityType": "organization",
    "organizationName": "Acme Corp",
    "email": "billing@acmecorp.com",
    "phone": "+15559876543",
    "idempotencyKey": "cust-create-002"
  }'

{
  "customerId": "cus_01hxy5n3prk9h4y4z4q1bar2dg",
  "name": "Acme Corp",
  "displayName": "Acme Corp",
  "organizationName": "Acme Corp",
  "email": "billing@acmecorp.com",
  "entityType": "organization",
  "phone": "+15559876543",
  "createdAt": "2024-06-01T12:05:00Z"
}

Retrieve a customer

Fetch a customer record at any time by their customerId using GET /customers/{id}.

curl -X GET https://api.paygood.co/customers/cus_01hxy4m2nqk9g3x3y3p0azq1cf \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY'

{
  "customerId": "cus_01hxy4m2nqk9g3x3y3p0azq1cf",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "entityType": "individual",
  "phone": "+15551234567",
  "createdAt": "2024-06-01T12:00:00Z"
}

List merchant customers

To retrieve all customers linked to your merchant, use GET /merchants/{merchantId}/customers. Results are returned as a paginated list.

curl -X GET https://api.paygood.co/merchants/mer_01hxy8m1nqk9g3x3y3p0azq2bg/customers \
  -H 'Authorization: Bearer $PAYGOOD_API_KEY'

The response contains an items array and a page object for cursor-based pagination.

{
  "items": [
    {
      "customerId": "cus_01hxy5n3prk9h4y4z4q1bar2dg",
      "name": "Acme Corp",
      "email": "billing@acmecorp.com",
      "entityType": "organization",
      "createdAt": "2024-06-01T12:05:00Z"
    }
  ],
  "page": {
    "hasMore": false,
    "nextCursor": null
  }
}

Pass the nextCursor value as a query parameter on your next request to fetch the following page of results.

Get Started

Guides

Merchant Onboarding

Create and Manage Your Customers Using the PayGood API

Create an individual customer

Create an organization customer

Retrieve a customer

List merchant customers

​Create an individual customer

​Create an organization customer

​Retrieve a customer

​List merchant customers

Create an individual customer

Create an organization customer

Retrieve a customer

List merchant customers