Skip to content

Client management

The Client Management operations includes APIs for managing client accounts. Client types include RESELLER and MERCHANT.

Operations

Create a Client

Request

Create a new client account. Client types include reseller and merchant.

Security
ApiKeyAuth
Headers
Client-Idstring, (ulid)required
X-Acting-As-Client-Idstring, (ulid)

The child client this request acts on behalf of. A reseller still authenticates as itself — Api-Key and Client-Id stay the reseller's — and names the child here.

This works only from a parent to its own children. Merchants have no children, so a merchant calling as itself omits the header. Sending your own client ULID here is not the same as omitting it, and is rejected on some operations.

Bodyapplication/json
parent_idstring, non-emptyrequired

Unique identifier of the parent client account (reseller or ISO).

typestring(ClientType)required

The type of client account.

Enum ValueDescription
reseller

Reseller — a client that resells services to merchants.

merchant

Merchant — a client that processes payments.

dbastring, non-emptyrequired

Doing Business As (DBA) name for the new client.

addressArray of objects(ClientAddress)

One or more client addresses. Each address carries a type identifying its purpose (legal, billing, or physical).

primary_phonePhone (string) or null(PhoneNullable)
One of:

Phone number. The phone number must contain between 10 and 12 digits and can contain spaces, a leading + symbol (when used with a country code), and the special characters (, ), -, and .. Alphabetical characters are not allowed.

string (tel)(Phone)
support_phonePhone (string) or null(PhoneNullable)
One of:

Phone number. The phone number must contain between 10 and 12 digits and can contain spaces, a leading + symbol (when used with a country code), and the special characters (, ), -, and .. Alphabetical characters are not allowed.

string (tel)(Phone)
websitestring, (url)

URL of client website

admin_contact_detailsobject(ClientAdminContactDetailsInput)required

Contact information for the primary admin user, supplied when creating a client. The four required properties must each carry a value — null is rejected, and so is an empty string.

metadataobject or null, <= 50 properties(Metadata)

Key-value pairs for storing additional information on the transaction. Send null to clear all metadata.

At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected.

{
  "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "type": "reseller",
  "dba": "Acme Jewelry",
  "address": [
    { … }
  ],
  "primary_phone": "+18005551234",
  "support_phone": "+18005551234",
  "website": "https://www.acme.com",
  "admin_contact_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+18005551234",
    "time_zone": "America/New_York"
  },
  "metadata": {
    "order_id": "ORD-10432",
    "sales_channel": "web",
    "customer_reference": "cust-8891"
  }
}

Responses

Client account created successfully

Headers
x-request-idstring, (uuid)^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}...required

Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

Bodyapplication/json
idstring, non-emptyrequired

Unique identifier for the newly created client assigned by the API server.

parent_idstring, non-emptyrequired

Unique identifier of the parent client account.

typestring(ClientType)required

The type of client account.

Enum ValueDescription
reseller

Reseller — a client that resells services to merchants.

merchant

Merchant — a client that processes payments.

dbastring, non-emptyrequired

Doing Business As (DBA) name of the newly created client.

addressArray of objects(ClientAddress)

One or more client addresses. Each address carries a type identifying its purpose (legal, billing, or physical).

primary_phonePhone (string) or null(PhoneNullable)
One of:

Phone number. The phone number must contain between 10 and 12 digits and can contain spaces, a leading + symbol (when used with a country code), and the special characters (, ), -, and .. Alphabetical characters are not allowed.

string (tel)(Phone)
support_phonePhone (string) or null(PhoneNullable)
One of:

Phone number. The phone number must contain between 10 and 12 digits and can contain spaces, a leading + symbol (when used with a country code), and the special characters (, ), -, and .. Alphabetical characters are not allowed.

string (tel)(Phone)
websitestring or null, (url)

URL of client website. Null when the client was created without one — the gateway returns the field rather than omitting it.

admin_contact_detailsobject(ClientAdminContactDetails)required

Contact information for the primary admin user of a client account, as returned on a response. The four required properties are always present and may be null, because a client created through an internal path is not held to the rules ClientAdminContactDetailsInput applies. A request uses ClientAdminContactDetailsInput to create and ClientAdminContactDetailsUpdate to amend.

api_keystring, non-emptyrequired

API key issued for the new client. Returned once, on this response only — store it, because no later call returns it again.

metadataobject or null, <= 50 properties(Metadata)

Key-value pairs for storing additional information on the transaction. Send null to clear all metadata.

At most 50 keys. Keys may contain letters, digits, hyphens, and underscores, up to 40 characters. Values are strings up to 500 characters. Every limit below is enforced; a request that exceeds any of them is rejected.

correlation_idstring(CorrelationId)

Identifier the gateway assigns to the request and carries across the services that handled it. Quote it when reporting a problem.

Response
{
  "id": "CLIENT-3MTWBWLKDIWHU7IX28A3TQPA",
  "parent_id": "CLIENT-01JMRSPCK7XVNP3KS8F2W4T6Y",
  "type": "reseller",
  "dba": "Acme Jewelry",
  "address": [
    { … }
  ],
  "primary_phone": "+18005551234",
  "support_phone": "+18005551234",
  "website": "https://www.acme.com",
  "admin_contact_details": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+18005551234",
    "time_zone": "America/New_York"
  },
  "api_key": "pk_live_01KFDKXMQ637EKEAY410MSQSXB",
  "metadata": {
    "order_id": "ORD-10432",
    "sales_channel": "web",
    "customer_reference": "cust-8891"
  },
  "correlation_id": "01KFDKXMQ637EKEAY410MSQSXB"
}