Invoice Customers

Version: 3.0.0

Generate an API Key for the Invoice channel before making requests.

Invoice customers are the entities you bill for products or services. Create customer profiles once, then reference them when creating invoices. Each customer stores contact information, a billing address, and a shipping address.

Reusable invoice customers save time and ensure consistent billing information across all invoices. Create them once, reference them in multiple invoices.

Every create and list response returns two identifiers: a display customer_id (a short sequence number) and a data_id (an encrypted token). Always send the data_id token when updating, activating, deactivating, deleting, or fetching a customer. When creating an invoice, pass this data_id token as the invoice's customer_id field.

Available Operations

Action	Method	Endpoint	Description
Create Customer	POST	`https://api.payorc.com/invoice/v1/customers/add`	Create a new customer
Update Customer	POST	`https://api.payorc.com/invoice/v1/customers/update`	Modify customer details
Deactivate	POST	`https://api.payorc.com/invoice/v1/customers/deactivate`	Disable customer
Activate	POST	`https://api.payorc.com/invoice/v1/customers/activate`	Re-enable a deactivated customer
Delete	POST	`https://api.payorc.com/invoice/v1/customers/delete`	Permanently remove a customer
Get Details	GET	`https://api.payorc.com/invoice/v1/customers/details`	Fetch a single customer
List Customers	GET	`https://api.payorc.com/invoice/v1/customers/list`	List all customers

Authentication

Header	Type	Description
`merchant-key`	String	Your merchant key
`merchant-secret`	String	Your merchant secret

Create Customer

Create a new customer profile for invoicing.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/customers/add`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`customer_details.name_prefix`	String	Yes	One of `Mr.`, `Miss`, or `Entity`
`customer_details.name`	String	Yes	Customer full name (1–50 characters)
`customer_details.email`	String	Yes	Customer email address (must be unique per merchant)
`customer_details.code`	Number	Yes	Country dial code (e.g., `91` for India, `971` for UAE)
`customer_details.mobile`	Number	Yes	Customer mobile number (validated against the dial code)
`billing_details.address`	String	No	Billing street address (max 70 characters)
`billing_details.country`	String	Yes	ISO 3166-1 alpha-2 country code
`billing_details.state`	String	Yes	State or province
`billing_details.city`	String	Yes	City
`billing_details.zip_code`	String	No	Postal/ZIP code (5–6 characters)
`shipping_details.same_as_billing_address`	String	Yes	`yes` or `no`
`shipping_details.address`	String	No	Shipping street address (max 70 characters; used when `same_as_billing_address` is `no`)
`shipping_details.country`	String	No	ISO 3166-1 alpha-2 country code
`shipping_details.state`	String	No	State or province
`shipping_details.city`	String	No	City
`shipping_details.zip_code`	String	No	Postal/ZIP code (5–6 characters)

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/customers/add \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "customer_details": {
        "name_prefix": "Miss",
        "name": "Pooja K",
        "email": "[email protected]",
        "code": "91",
        "mobile": "9991234567"
    },
    "billing_details": {
        "address": "Po Box 12322, address",
        "country": "IN",
        "state": "Maharashtra",
        "city": "Nagpur",
        "zip_code": "44044"
    },
    "shipping_details": {
        "same_as_billing_address": "no",
        "address": "Po Box 12322",
        "country": "IN",
        "state": "Maharashtra",
        "city": "Nagpur",
        "zip_code": "54044"
    }
  }'

Example Response

{
    "data": {
        "customer_id": "0000000261",
        "data_id": "b0RENkJZcVV2L3RM"
    },
    "message": "Client Added successfully.",
    "status": "success",
    "code": "00"
}

Use the returned data_id token when updating this customer or when referencing them in the invoice customer_id field.

Update Customer

Modify details of an existing customer. All customer, billing, and shipping fields follow the same validation rules as Create Customer.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/customers/update`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`customer_details.data_id`	String	Yes	Encrypted token of the customer to update
`customer_details.name_prefix`	String	Yes	One of `Mr.`, `Miss`, or `Entity`
`customer_details.name`	String	Yes	Customer full name
`customer_details.email`	String	Yes	Email address
`customer_details.code`	Number	Yes	Country dial code
`customer_details.mobile`	Number	Yes	Mobile number
`billing_details`	Object	Yes	Billing details (replaces existing)
`shipping_details`	Object	Yes	Shipping details (replaces existing)

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/customers/update \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "customer_details": {
        "data_id": "b0RENkJZcVV2L3RM",
        "name_prefix": "Miss",
        "name": "Pooja Kushwaha",
        "email": "[email protected]",
        "code": "91",
        "mobile": "9991234567"
    },
    "billing_details": {
        "address": "456 New Street",
        "country": "AE",
        "state": "Dubai",
        "city": "Dubai",
        "zip_code": "12345"
    },
    "shipping_details": {
        "same_as_billing_address": "no",
        "address": "Po Box 12322",
        "country": "IN",
        "state": "Maharashtra",
        "city": "Nagpur",
        "zip_code": "54044"
    }
  }'

Example Response

{
    "message": "Client updated successfully.",
    "status": "success",
    "code": "00"
}

Deactivate Customer

Deactivate a customer so they cannot be used for new invoices.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/customers/deactivate`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the customer to deactivate

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/customers/deactivate \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "data_id": "b0RENkJZcVV2L3RM"
  }'

Example Response

{
    "message": "Client deactivated successfully",
    "status": "success",
    "code": "00"
}

Deactivated customers can be reactivated at any time. They are not deleted — just hidden from customer selection when creating new invoices.

Activate Customer

Reactivate a previously deactivated customer.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/customers/activate`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the customer to activate

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/customers/activate \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "data_id": "b0RENkJZcVV2L3RM"
  }'

Example Response

{
    "message": "Client activated successfully",
    "status": "success",
    "code": "00"
}

Delete Customer

Permanently delete a customer. This cannot be undone.

Endpoint

Method	URL
POST	`https://api.payorc.com/invoice/v1/customers/delete`

Please use the test credentials for sandbox testing.

Request Body

Field	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the customer to delete

Code Examples

curl -X POST https://api.payorc.com/invoice/v1/customers/delete \
  -H "Content-Type: application/json" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET" \
  -d '{
    "data_id": "b0RENkJZcVV2L3RM"
  }'

Example Response

{
    "message": "Client deleted successfully",
    "status": "success",
    "code": "00"
}

Deleting a customer is permanent and cannot be undone. Existing invoices that reference this customer will retain the data, but the customer cannot be used in new invoices.

Get Customer Details

Retrieve details for a single customer.

Endpoint

Method	URL
GET	`https://api.payorc.com/invoice/v1/customers/details?data_id=DATA_ID`

Pass the encrypted data_id token (not the display customer_id) as the query parameter. Please use the test credentials for sandbox testing.

Query Parameters

Parameter	Type	Required	Description
`data_id`	String	Yes	Encrypted token of the customer to fetch

Code Examples

curl -X GET "https://api.payorc.com/invoice/v1/customers/details?data_id=b0RENkJZcVV2L3RM" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET"

Example Response

{
    "data": {
        "customer_details": {
            "customer_id": "0000000261",
            "data_id": "OVV0cGU4b2MraUF",
            "name_prefix": "Mr.",
            "name": "Rahul K",
            "email": "[email protected]",
            "code": "971",
            "mobile": "9991234567"
        },
        "billing_details": {
            "address": "Po Box 12322, address",
            "country": "AE",
            "state": "Dubai",
            "city": "Dubai",
            "zip_code": "44044"
        },
        "shipping_details": {
            "same_as_billing_address": "no",
            "address": "Po Box 12322",
            "country": "IN",
            "state": "Madhya Pradesh",
            "city": "Jabalpur",
            "zip_code": "54044"
        },
        "status": "Active",
        "submerchant_name": "Qwerty Tech"
    },
    "message": "Details fetched successfully.",
    "status": "success",
    "code": "00"
}

List Customers

Retrieve a paginated list of all customers.

Endpoint

Method	URL
GET	`https://api.payorc.com/invoice/v1/customers/list`

Please use the test credentials for sandbox testing.

Query Parameters

Parameter	Type	Required	Description
`perpage`	Integer	Yes	Number of items per page (1–1000)
`page`	Integer	Yes	Page number (1–1000)
`status`	String	No	Filter by status (`Active` or `Deactivated`)
`name_or_email_mobile`	String	No	Search by name, email, or mobile number
`billing_country`	String	No	Filter by billing country (ISO 3166-1 alpha-2 code)
`customer_id`	String	No	Filter by the display customer ID
`from_date`	Date	No	Filter by customer created date, from this date (format: `YYYY-MM-DD`)
`to_date`	Date	No	Filter by customer created date, up to this date (format: `YYYY-MM-DD`). Must be ≥ `from_date`

Code Examples

curl -X GET "https://api.payorc.com/invoice/v1/customers/list?perpage=10&page=1" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "merchant-secret: YOUR_MERCHANT_SECRET"

Example Response

{
    "data": [
        {
            "customer_details": {
                "customer_id": "0000000261",
                "data_id": "OVV0cGU4b2MraUF",
                "de_customer_id": "0000000261",
                "name_prefix": "Mr.",
                "name": "Rahul K",
                "email": "[email protected]",
                "mobile": "+971 9991234567"
            },
            "billing_details": {
                "address": "Po Box 12322, address",
                "country": "AE",
                "state": "Dubai",
                "city": "Dubai",
                "zip_code": "44044"
            },
            "shipping_details": {
                "same_as_billing_address": "no",
                "address": "Po Box 12322",
                "country": "IN",
                "state": "Madhya Pradesh",
                "city": "Jabalpur",
                "zip_code": "54044"
            },
            "status": "Active",
            "created_date": "19-01-2024 16:41:05",
            "first_txn_date": "-",
            "last_txn_date": "-",
            "submerchant_name": "Qwerty Tech"
        }
    ],
    "message": "List fetched successfully.",
    "status": "success",
    "code": "00",
    "total_records": 1
}

Invoice Customers

On this page