> ## Documentation Index
> Fetch the complete documentation index at: https://docs.caibo.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Customer

> Create customer profiles in the Caibo IPG system for payment processing and account management.

# Overview

Customer creation is the first step in establishing a relationship with your users for payment processing. The Caibo IPG API allows you to create comprehensive customer profiles that include personal information, contact details, and preferences for future payment transactions.

<Note>
  Customer creation typically happens during the registration or onboarding process and is essential for tracking payment history, managing saved payment methods, and providing personalized payment experiences.
</Note>

## Why Create Customer Profiles?

Creating customer profiles provides several benefits:

* **Payment History Tracking**: Maintain a complete record of all customer transactions
* **Saved Payment Methods**: Enable customers to store payment methods for faster checkout
* **Personalized Experience**: Customize payment flows based on customer preferences
* **Compliance**: Meet regulatory requirements for customer identification and verification
* **Analytics**: Generate insights on customer payment behavior and preferences

## Required Parameters

When creating a new customer, the following information is typically required:

* **name**: Customer's full name (required)
* **email**: Customer's email address (required)
* **phone**: Customer's phone number (optional)
* **address**: Customer's billing address (optional)
* **memberId**: Customer member identifier for integration with existing systems (optional)

## Customer Data Structure

### Essential Information

* **Personal Details**: Name, email, phone number, date of birth
* **Contact Information**: Primary email and phone for notifications
* **Unique Identifier**: System-generated customer ID for tracking

### Optional Information

* **Address Details**: Billing and shipping addresses for payment verification
* **Member Integration**: Connection with existing membership or loyalty systems
* **Preferences**: Payment method preferences, currency, and notification settings

## Security & Privacy

### Data Protection

* **PCI Compliance**: All payment data handled according to PCI DSS standards
* **Encryption**: Customer data encrypted in transit and at rest
* **Access Control**: Role-based access to customer information
* **Audit Trail**: Complete audit log of customer data access and changes

### Privacy Controls

* **Data Retention**: Configurable data retention policies
* **Right to Deletion**: Support for customer data deletion requests
* **Consent Management**: Track and manage customer consent preferences
* **Data Export**: Provide customer data exports upon request

## Integration Examples

### Update Customer Information

```javascript theme={null}
// Update customer profile
const updateData = {
  email: 'newemail@example.com',
  phone: '+1234567890',
  preferences: {
    currency: 'USD',
    notifications: true
  }
};

const response = await fetch('/api/customers/12345', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
});
```

### Get Payment Methods

```javascript theme={null}
// Retrieve user's saved payment methods
const paymentMethods = await fetch('/api/users/payment-methods/12345', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json'
  }
});

const methods = await paymentMethods.json();
console.log('Saved payment methods:', methods);
```

## Error Handling

### Common Error Scenarios

* **Customer Not Found**: HTTP 404 when customer ID doesn't exist
* **Unauthorized Access**: HTTP 401 for invalid authentication
* **Validation Errors**: HTTP 400 for invalid customer data
* **Server Errors**: HTTP 500 for internal processing errors

### Error Response Format

```json theme={null}
{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer with ID 12345 not found",
    "details": {
      "customerId": "12345",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }
}
```

## Best Practices

### Customer Data Management

1. **Regular Updates**: Keep customer information current
2. **Validation**: Validate all customer data before storage
3. **Deduplication**: Prevent duplicate customer records
4. **Segmentation**: Use customer data for targeted experiences

### Performance Optimization

1. **Caching**: Cache frequently accessed customer data
2. **Pagination**: Use pagination for large customer lists
3. **Selective Loading**: Load only required customer data fields
4. **Async Processing**: Handle bulk operations asynchronously

### Security Best Practices

1. **Access Control**: Implement proper role-based access
2. **Data Minimization**: Store only necessary customer data
3. **Regular Audits**: Conduct regular security audits
4. **Incident Response**: Have procedures for data breaches

## Compliance Considerations

### GDPR Compliance

* **Lawful Basis**: Ensure lawful basis for data processing
* **Data Subject Rights**: Support all GDPR data subject rights
* **Privacy by Design**: Implement privacy-first architecture
* **DPO Consultation**: Consult with Data Protection Officer

### PCI DSS Requirements

* **Secure Storage**: Never store sensitive payment data
* **Access Logging**: Log all access to customer payment data
* **Network Security**: Secure network transmission of data
* **Regular Testing**: Conduct regular security testing

## Monitoring & Analytics

### Key Metrics

* **Customer Growth**: Track new customer registrations
* **Profile Completeness**: Monitor customer profile completion rates
* **Payment Method Usage**: Analyze payment method preferences
* **Customer Lifetime Value**: Calculate customer value metrics

### Reporting

* **Customer Demographics**: Age, location, and preference analysis
* **Payment Behavior**: Payment method and frequency analysis
* **Support Metrics**: Customer service interaction tracking
* **Retention Analysis**: Customer retention and churn analysis

## Next Steps

<Card title="Payment Methods" icon="credit-card" href="/ipg/payment-methods">
  Explore available payment methods
</Card>

<Card title="Authentication" icon="key" href="/ipg/authentication">
  Learn about API authentication
</Card>

<Card title="Webhooks" icon="webhook" href="/ipg/callbacks">
  Set up payment status notifications
</Card>


## OpenAPI

````yaml api POST /customers
openapi: 3.0.4
info:
  title: FinHub API
  description: >-
    FinHub API provides services for the Caibo platform to support client's
    applications
  version: v1
servers:
  - url: https://apay.caibo.digital
    description: Caibo APay server (Test and Production share base; method IDs differ)
security: []
paths:
  /customers:
    post:
      tags:
        - Customers
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/Client'
          application/json:
            schema:
              $ref: '#/components/schemas/Client'
          text/json:
            schema:
              $ref: '#/components/schemas/Client'
          application/*+json:
            schema:
              $ref: '#/components/schemas/Client'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    Client:
      required:
        - email
        - name
      type: object
      properties:
        id:
          type: integer
          format: int64
        ownerId:
          type: integer
          format: int64
        userId:
          type: integer
          format: int64
          nullable: true
        ownerName:
          type: string
          nullable: true
        name:
          maxLength: 100
          minLength: 0
          type: string
        email:
          maxLength: 100
          minLength: 0
          type: string
          format: email
        address:
          maxLength: 255
          minLength: 0
          type: string
          nullable: true
        phone:
          maxLength: 20
          minLength: 0
          type: string
          nullable: true
        memberId:
          maxLength: 50
          minLength: 0
          type: string
          nullable: true
        hasPaymentRequests:
          type: boolean
          nullable: true
        totalDeposits:
          type: number
          format: double
          nullable: true
        createDate:
          type: string
          format: date-time
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}

````