Skip to main content
Customers represent your buyers in the Orafi system.

​
Available Endpoints

POST /customers/create        # Creating Customers
GET /customers                # Get all customers
GET /customers/{id}           # Get specific customer
DELETE /customers/{id}        # Deleting Customers

​
Customer Object

The Customer model represents an end user who interacts with a merchant on OraFi. It is used to track identity, spending behavior, and financial activity across payments, refunds, and transactions. A customer may exist in test, live, or both environments and can be linked to multiple business profiles over time.

​
Fields

​
id

  • Type: String
  • Primary Key
  • Default: cuid()
  • Database Field: _id
  • Description: Unique identifier for the customer record.

​
firstname

  • Type: String
  • Description: Customer’s first name.

​
lastname

  • Type: String
  • Description: Customer’s last name.

​
email

  • Type: String
  • Description: Customer’s email address. Used for identification, receipts, and customer lookup.

​
mode

  • Type: Mode[]
  • Description: Indicates the environment(s) in which the customer has interacted. A customer may exist in:
    • Test mode
    • Live mode
    • Both environments

​
totalSpent

  • Type: Int
  • Default: 0
  • Description: Aggregate amount spent by the customer across all completed transactions. Used for analytics, segmentation, and filtering.

​
Relationships (High-Level)

These relationships exist for tracking activity and ownership but are not required for basic customer reads.
  • Business Profiles A customer may be associated with one or more business profiles through interactions.
  • Transactions Tracks all financial transactions linked to the customer.

​
Notes

  • Customers are typically created automatically during successful payments.
  • Manual customer creation is intended for edge cases such as migrations or enterprise workflows.
  • Customer records are merchant-scoped and cannot be accessed across businesses.
  • totalSpent reflects successful, finalized transactions only.

​
Creating Customers

Creating customers manually is intended for rare and specific use cases.
In most situations, customers are created automatically during payment flows and do not need to be managed directly.

​
When to Create Customers Manually

Manual customer creation may be appropriate in the following cases:
  • Pre-registration
    When you want to create customer records before any payment is made.
  • Offline or External Payments
    If a payment occurs outside the platform and needs to be linked to an existing customer.
  • Customer Data Migration
    When importing customers from another system or legacy database.
  • Recurring or Account-Based Billing
    When a persistent customer identity is required before initiating future charges.
  • Customer Support & Reconciliation
    To resolve disputes, track payment history, or reconcile transactions tied to a known customer.

​
Recommendation

For standard checkout, payment links, and hosted payment flows, do not create customers manually.
Let OraFi automatically handle customer creation to ensure consistency and reduce errors.
Create a customer

​
Request Body

​
firstname

  • Type: string
  • Required
  • Description:
    Customer’s first name.

​
lastname

  • Type: string
  • Required
  • Description:
    Customer’s last name.

​
email

  • Type: string
  • Required
  • Format: email
  • Description:
    Customer’s email address. Used for identification, receipts, and transaction records.
curl -X POST https://api.orafi.app/v1/customers/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  }'
Response 
{
    "success": true,
    "message": "Customer created successfully",
    "data": {
        "id": "cmjx0kiie0003v86cfqsve9fj",
        "firstname": "Melvin",
        "lastname": "Charles",
        "email": "[email protected]",
        "mode": [
            "test"
        ],
        "totalSpent": 0
    }
}

​
Retrieving Customers

The Get Customers endpoint allows you to filter customers based on their spending behavior, environment mode, and pagination controls. All query parameters are optional
Get all customers

​
Query Parameters

​
amountSpent

  • Type: string
  • Allowed Values:
    • BELOW10USDT
    • FROM10TO30USDT
    • FROM30TO100USDT
    • FROM100TO200USDT
    • FROM200TO500USDT
    • ABOVE500USDT
  • Description:
    Filters customers based on their total amount spent within predefined ranges.

​
mode

  • Type: string
  • Allowed Values: live, test
  • Optional
  • Description:
    Filters customers by environment mode.

​
limit

  • Type: number
  • Default: 20
  • Description:
    Maximum number of customers returned per request.

​
cursor

  • Type: string
  • Description:
    Cursor used for pagination.
    When provided, results start after the referenced customer.
curl -X GET https://api.orafi.app/v1/customers/ \
  -H "x-api-key: your_api_key"
Response 
{
    "success": true,
    "message": "Customers fetched successfully",
    "data": {
        "customers": [
            {
                "id": "cmjr4c7qq0000v8hozkzz4em5",
                "firstname": "Melvin",
                "lastname": "Charles",
                "email": "[email protected]",
                "mode": [
                    "test"
                ],
                "totalSpent": 0,
                "userCustomers": [
                    {
                        "createdAt": "2025-12-29T12:12:29.615Z"
                    }
                ]
            },
            {
                "id": "cmjx0jcme0000v86caeyqpy9i",
                "firstname": "James",
                "lastname": "King",
                "email": "[email protected]",
                "mode": [
                    "test"
                ],
                "totalSpent": 0,
                "userCustomers": [
                    {
                        "createdAt": "2026-01-02T15:12:41.123Z"
                    }
                ]
            },
            {
                "id": "cmjx0kiie0003v86cfqsve9fj",
                "firstname": "Melvin",
                "lastname": "Charles",
                "email": "[email protected]",
                "mode": [
                    "test"
                ],
                "totalSpent": 0,
                "userCustomers": [
                    {
                        "createdAt": "2026-01-02T15:13:35.414Z"
                    }
                ]
            }
        ],
        "count": 3,
        "nextCursor": null,
        "hasNextPage": false
    }
}

GET /customers?amountSpent=ABOVE500USDT&mode=live&limit=10
GET /customers?amountSpent=FROM30TO100USDT
GET /customers?mode=live
GET /customers?limit=20&cursor=cus_82jd82jd9
Get specific customer:
Retrieve information about a specific customer

​
Request Body

​
customerId

  • Type: string
  • Required
  • Description: Unique identifier for a customer.
curl -X GET https://api.orafi.app/v1/customers/{customerId} \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key"
Response 
{
    "success": true,
    "message": "Customer fetched successfully",
    "data": {
        "id": "cmjr4c7qq0000v8hozkzz4em5",
        "firstname": "Melvin",
        "lastname": "Charles",
        "email": "[email protected]",
        "mode": [
            "test"
        ],
        "totalSpent": 0,
        "userCustomers": [
            {
                "createdAt": "2025-12-29T12:12:29.615Z"
            }
        ]
    }
}

​
Deleting Customers

Permanently deletes a customer associated with your business profile.
Deleting a customer is irreversible and should only be used in rare situations such as:
  • Duplicate customer records
  • Customers created by mistake
  • Compliance or legal data-removal requests
In most cases, we recommend keeping customer records for transaction history, audits, and reconciliation.

​
Request Body

​
customerId

  • Type: string
  • Required
  • **Description: Unique identifier for a customer.
Delete a customer: 
curl -X DELETE https://api.orafi.app/v1/business/mode \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key"
Response 
{
    "success": true,
    "message": "User Deleted successfully",
    "data": null
}