Create a customer

Credentials

Adds a customer to the seller's customer list. first_name, last_name, email, phone and status are required. The response returns the new customer's guid; use it with /customers/{guid}.

The request names the phone fields phone and additional_phone and sends the address fields at the top level; responses name them phone_number and additional_phone_number and nest the address in address. Fields the API doesn't know are ignored.

Send Authorization: Bearer <auth_token>, the token from POST /auth-tokens. Hosts, tokens and the error format: Hosts, authentication and errors.

Parameters

This endpoint takes no path, query or header parameters.

Request body

Content type: application/json

The customer to create.

Field Type Required Description
customer_external_id string no Your own customer id, unique among the seller's customers (409 otherwise). It isn't returned when you read the customer.
first_name string yes First name, at least 2 characters.
middle_name string no Middle name, at least 2 characters.
last_name string yes Last name, at least 2 characters.
email string yes A valid email address.
phone string yes Main phone number, 3–20 characters. Returned as phone_number.
additional_phone string no Second phone number, 3–20 characters. Returned as additional_phone_number.
company_name string no Company name, at least 2 characters.
country string no Country, at least 2 characters. Returned inside address.
city string no City, at least 2 characters. Returned inside address.
street string no Street, at least 2 characters. Returned inside address.
building_number string no Building number, e.g. 12 or 12A. Returned inside address.
floor string no Floor, at least 1 character. Returned inside address.
zip string no Postal code. Returned inside address.
description string no Your note about the customer.
birthday string no Date of birth, YYYY-MM-DD.
status integer yes 0 – inactive, 1 – active, 2 – draft.
payment_tokens array no Payment tokens to save for the customer.
payment_tokens[].token string yes The payment token to save. PayMe stores it as given.
payment_tokens[].token_data string no A JSON object encoded as a string, e.g. the card mask and brand: {"card_mask":"4580 **** **** 0000","card_brand":"visa"}. Must be valid JSON.

Request example

{
  "customer_external_id": "CUST-1001",
  "first_name": "Dana",
  "last_name": "Levi",
  "email": "dana@example.com",
  "phone": "0501234567",
  "status": 1,
  "country": "Israel",
  "city": "Tel Aviv",
  "street": "Rothschild",
  "building_number": "12A",
  "birthday": "1990-05-17",
  "payment_tokens": [
    {
      "token": "8f3a2c1d9e7b4a60",
      "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
    }
  ]
}

Code samples

curl

curl -X POST 'https://payme-store-staging.payme.io/api/customers' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "customer_external_id": "CUST-1001",
  "first_name": "Dana",
  "last_name": "Levi",
  "email": "dana@example.com",
  "phone": "0501234567",
  "status": 1,
  "country": "Israel",
  "city": "Tel Aviv",
  "street": "Rothschild",
  "building_number": "12A",
  "birthday": "1990-05-17",
  "payment_tokens": [
    {
      "token": "8f3a2c1d9e7b4a60",
      "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
    }
  ]
}'

Node.js

const response = await fetch("https://payme-store-staging.payme.io/api/customers", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "customer_external_id": "CUST-1001",
    "first_name": "Dana",
    "last_name": "Levi",
    "email": "dana@example.com",
    "phone": "0501234567",
    "status": 1,
    "country": "Israel",
    "city": "Tel Aviv",
    "street": "Rothschild",
    "building_number": "12A",
    "birthday": "1990-05-17",
    "payment_tokens": [
      {
        "token": "8f3a2c1d9e7b4a60",
        "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
      }
    ]
  }),
});

console.log(await response.text());

Python

import requests

response = requests.post(
    "https://payme-store-staging.payme.io/api/customers",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "customer_external_id": "CUST-1001",
        "first_name": "Dana",
        "last_name": "Levi",
        "email": "dana@example.com",
        "phone": "0501234567",
        "status": 1,
        "country": "Israel",
        "city": "Tel Aviv",
        "street": "Rothschild",
        "building_number": "12A",
        "birthday": "1990-05-17",
        "payment_tokens": [
            {
                "token": "8f3a2c1d9e7b4a60",
                "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}",
            },
        ],
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "customer_external_id": "CUST-1001",
  "first_name": "Dana",
  "last_name": "Levi",
  "email": "dana@example.com",
  "phone": "0501234567",
  "status": 1,
  "country": "Israel",
  "city": "Tel Aviv",
  "street": "Rothschild",
  "building_number": "12A",
  "birthday": "1990-05-17",
  "payment_tokens": [
    {
      "token": "8f3a2c1d9e7b4a60",
      "token_data": "{\"card_mask\":\"4580 **** **** 0000\",\"card_brand\":\"visa\"}"
    }
  ]
}
BODY;

$ch = curl_init('https://payme-store-staging.payme.io/api/customers');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Responses

201 — Customer created. (success)

Field Type Description
guid string The new customer's id (a UUID). Use it in /customers/{guid}.
created_at string Creation time, ISO 8601 (UTC). 
{
  "guid": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "created_at": "2026-11-09T10:00:00.000Z"
}

400 — A required field is missing, a field is invalid, or the body isn't valid JSON. (error)

Field Type Description
status_error_details string What went wrong. Validation messages are in Hebrew unless you send Accept-Language: en.
status_error_code integer 501 for a validation error or a body that isn't valid JSON, 999 for any other error.
validation_errors object The fields that failed validation. Each key is a field name; its value maps each failed rule to a message.
session string Trace id of the request. Quote it when you contact PayMe support. 
{
  "status_error_details": "Field validation failed.",
  "validation_errors": {
    "email": {
      "is_email": "The value must be a valid email address."
    }
  },
  "status_error_code": 501,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}

401 — The Authorization header is missing, or the access token is invalid or expired. Get a new token with POST /refresh-exchanges or POST /auth-tokens. (error)

Field Type Description
status_error_details string What went wrong.
status_error_code integer 999.
session string Trace id of the request. Quote it when you contact PayMe support. 
{
  "status_error_details": "Unauthorized",
  "status_error_code": 999,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}

409 — customer_external_id is already used by another of the seller's customers. (error)

Field Type Description
status_error_details string What went wrong.
status_error_code integer 999.
session string Trace id of the request. Quote it when you contact PayMe support. 
{
  "status_error_details": "Customer external id already exist",
  "status_error_code": 999,
  "session": "f3a1c2b0-9e4d-11ef-8c1a-0242ac120002"
}

500 — Server error. Contact PayMe support and quote the session. (error)

Field Type Description
status_error_details string What went wrong.
status_error_code integer 999.
session string Trace id of the request. Quote it when you contact PayMe support.