Create a customer

curl --request POST \
  --url https://api.paystack.com/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "email": "jsmith@example.com",
  "country_code": "<string>",
  "metadata": {},
  "merchant_reference": "<string>"
}
'

{
  "status": true,
  "message": "Customer created successfully",
  "code": "ok",
  "data": {
    "id": "cust_01HXYZABC1234567890ABCDEFG",
    "type": "individual",
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "merchant_reference": "ref_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "country_code": "NG",
    "tier": "tier_0",
    "kyc_status": "not_started",
    "metadata": {
      "source": "checkout"
    },
    "created_at": "2026-04-16T16:14:08.000Z",
    "updated_at": "2026-04-16T16:14:08.000Z"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Customers

Create a customer

Creates a new customer scoped to the calling merchant’s integration.

Body

type — required. One of individual, business.
name — required. Full name of the customer. Max 255 chars.
email — required. Valid email. Max 255 chars. Per-integration uniqueness is enforced case-insensitively.
country_code — required. ISO-3166-1 alpha-2 (e.g. NG, KE).
metadata — optional. Free-form Record<string, string>.
merchant_reference — optional. Max 128 chars. Auto-generated as ref_<ULID> when omitted. Per-integration unique.

Example

POST /v1/customers
{
  "type": "individual",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "country_code": "NG"
}

POST

customers

Create a customer

curl --request POST \
  --url https://api.paystack.com/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "email": "jsmith@example.com",
  "country_code": "<string>",
  "metadata": {},
  "merchant_reference": "<string>"
}
'

{
  "status": true,
  "message": "Customer created successfully",
  "code": "ok",
  "data": {
    "id": "cust_01HXYZABC1234567890ABCDEFG",
    "type": "individual",
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "merchant_reference": "ref_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "country_code": "NG",
    "tier": "tier_0",
    "kyc_status": "not_started",
    "metadata": {
      "source": "checkout"
    },
    "created_at": "2026-04-16T16:14:08.000Z",
    "updated_at": "2026-04-16T16:14:08.000Z"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Headers

Idempotency-Key

string

Optional client-supplied key. Identical key + identical body within 24h replays the original response. Identical key + different body returns 409 idempotency_conflict. The hash is over raw bytes — clients retrying must send the byte-identical body; a re-serialised JSON payload will produce a different hash and a 409. Strongly recommended for retry-safe clients.

Pattern: ^[A-Za-z0-9_\-]{8,255}$

Body

application/json

CreateCustomerDto

type

enum<string>

required

Available options:

individual,

business

name

string

required

Required string length: 1 - 255

string<email>

required

Maximum string length: 255

country_code

string

required

Pattern: ^[A-Z]{2}$

metadata

object

merchant_reference

string

Maximum string length: 128

Response

Customer created successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Customer created successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes