Skip to main content
POST
Create a customer

What this endpoint does

Creates an individual or business customer under the current tenant account.

When to use it

Create the customer before issuing verification or customer-owned payment routes.

Before you call

Use a secret API key with customer write access and supply a stable external reference or identity fields required by the request schema.

Money and balance effect

This changes a resource or configuration but does not directly reserve, debit, credit, or settle wallet money.

States and completion

Creation does not approve the customer. Verification and entitlements progress asynchronously.

Safe retries

Send a unique Idempotency-Key for the logical action. If the response is lost, retry the same payload with the same key; never create a new key merely because the first response timed out. Read Customers for the complete workflow.

Authorizations

Authorization
string
header
required

Send the same Wayex API key as Authorization: Bearer <key>.

Headers

Idempotency-Key
string
required

A unique key for this logical action. Reuse the same key and identical payload when retrying after an unknown response.

Required string length: 8 - 255

Body

application/json
type
enum<string>
required
Available options:
business
contact
object
required
businessDetails
object
required
externalCustomerId
string
Minimum string length: 1
requestedEntitlements
enum<string>[]
Available options:
aud_onramp,
aud_offramp,
payment_route,
higher_limits
metadata
object

Response

The created customer.

id
string
required

Unique Wayex identifier for this customer.

Minimum string length: 1
counterpartyId
string
required

The client account (counterparty) this customer belongs to. For API callers this is always your own account id.

Minimum string length: 1
type
enum<string>
required

Whether the customer is an individual (natural person) or a business (legal entity).

Available options:
individual,
business
contact
object
required
verificationStatus
enum<string>
required

Current verification state. Value can only move on the customer's behalf once approved.

Available options:
in_progress,
approved,
rejected,
requires_action
entitlements
object[]
required

The capabilities this customer is cleared for, granted as verification completes.

createdAt
string<date-time>
required

When the customer was created (ISO 8601).

externalCustomerId
string

Your own identifier for this customer, echoed back for cross-referencing.

Minimum string length: 1
businessDetails
object
individualDetails
object
metadata
object