Customer（顧客）

Customers（顧客）オブジェクトは、同一の顧客に対する複数回の課金を可能にします。このAPIによって、顧客の作成、削除、更新ができるようになります。その他にも、特定の顧客の情報を取得したり、顧客一覧のリストを取得したりすることができます。

Attributes

Name	Type	Description
object	string	固定値`customer`
id	string	`/cust(_test)?_[0-9a-z]+/`に一致する`CUSTOMER_ID`。
livemode	boolean	本番モード (`true`) あるいはテストモード(`false`) 顧客。
location	string	現在の`customer`オブジェクトを取得するためのAPIパス。
cards	list	顧客に紐づく cards（カード）のList（リスト）。
created_at	string	ISO 8601 形式 (`YYYY-MM-DDThh:mm:ssZ`)で顧客が作成されたUTC日時。
default_card	object_id_expandable	課金を作成する際にデフォルトで利用されるカードのCARD_ID。デフォルトカードは顧客に割り当てられる最初のカード。削除されると、最後に追加されたカードがデフォルトカードとなる。顧客にカードが登録されていない場合、nullの値が表示される。
deleted	boolean	顧客が削除されたかどうか。
description	string	顧客の説明。
email	string	顧客に紐づけられたメールアドレス。
linked_accounts	list	TBD
metadata	object	顧客用のカスタムメタデータ（例:`{"customer-id": 42}`) 。

Example

JSON Response

{
  "object": "customer",
  "id": "cust_test_no1t4tnemucod0e51mo",
  "livemode": false,
  "location": "/customers/cust_test_no1t4tnemucod0e51mo",
  "deleted": false,
  "metadata": {},
  "cards": {
    "object": "list",
    "data": [
      {
        "object": "card",
        "id": "card_test_no1t4tnemucod0e51mo",
        "livemode": false,
        "location": "/customers/cust_test_no1t4tnemucod0e51mo/cards/card_test_no1t4tnemucod0e51mo",
        "deleted": false,
        "street1": "1448/4 Praditmanutham Road",
        "street2": null,
        "city": "Bangkok",
        "state": null,
        "phone_number": "0123456789",
        "postal_code": "10320",
        "country": "th",
        "financing": "credit",
        "bank": "Bank of the Unbanked",
        "brand": "Visa",
        "fingerprint": "XjOdjaoHRvUGRfmZacMPcJtm0U3SEIIfkA7534dQeVw=",
        "first_digits": null,
        "last_digits": "4242",
        "name": "Somchai Prasert",
        "expiration_month": 12,
        "expiration_year": 2024,
        "security_code_check": true,
        "tokenization_method": null,
        "created_at": "2019-12-31T12:59:59Z"
      }
    ],
    "limit": 20,
    "offset": 0,
    "total": 1,
    "location": "/customers/cust_test_no1t4tnemucod0e51mo/cards",
    "order": "chronological",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-12-31T12:59:59Z"
  },
  "default_card": "card_test_no1t4tnemucod0e51mo",
  "description": "Additional information about Somchai Prasert",
  "email": "somchai.prasert@example.com",
  "created_at": "2019-12-31T12:59:59Z"
}

新しい顧客の作成

- POST https://api.omise.co/customers

新しい顧客のオブジェクト情報を返します。

Request Parameters

Name	Type	Description
card	string	(任意) 新しいカードとして顧客に追加するための未使用の[トークン識別子]（/ tokens-api）。
description	string	(任意だが推奨) 顧客の説明。 Opn Paymentsに、顧客に関する追加の詳細情報を提供し、不正防止の検査を改善します。
email	string	(任意だが推奨) 顧客のメールアドレス。 Opn Paymentsに、顧客の電子メールアドレスを提供し、不正防止の検査を改善します。
linked_account	string	(任意) TBD
metadata	object	(任意) 顧客用のカスタムメタデータ（例:`{"customer-id": 42}`) 。

Example

新しい顧客の作成し、Cardオブジェクトをひも付ける

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers \
  -u $OMISE_SECRET_KEY: \
  -d "description=Additional information about Somchai Prasert." \
  -d "email=somchai.prasert@example.com" \
  -d "card=tokn_test_5g5mep9yrko3vx2f0hx"

<?php

$customer = OmiseCustomer::create(array(
  'email' => 'john.doe@example.com',
  'description' => 'John Doe (id: 30)',
  'card' => 'tokn_test_4xs9408a642a1htto8z'
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const customer = await omise.customers.create({
  description: 'John Doe (id: 34)',
  email: 'john.doe@example.com',
  card: 'tokn_test_no1t4tnemucod0e51mo',
});
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.create({
  email: "john.doe@example.com",
  description: "John Doe (id: 30)",
  card: "tokn_test_4xs9408a642a1htto8z"
})

var token = await RetrieveToken();
var customer = await Client.Customers.Create(new CreateCustomerRequest
{
    Email = "john.doe@example.com",
    Description = "John Doe (id: 30)",
    Metadata = new Dictionary<string, object>
    {
        { "user_id", 30 }
    },
    Card = token.Id,
});

Console.WriteLine($"created customer: {customer.Id}");

Request<Customer> request = new Customer.CreateRequestBuilder()
        .email("john.doe@omise.co")
        .description("This cool customer!")
        .card("tokn_test_4xs9408a642a1htto8z")
        .build();
Customer customer = client().sendRequest(request);

System.out.printf("Created customer: %s", customer.getId());

import omise

customer = omise.Customer.create(
    email="john.doe@example.com",
    description="John Doe (id: 30)",
    card="tokn_test_no1t4tnemucod0e51mo",
)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Customer{}
err := client.Do(result, &operations.CreateCustomer{
	Email:       "john.doe@example.com",
	Description: "John Doe (id: 30)",
	Card:        "tokn_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.create(
  email:       "john.doe@example.com",
  description: "John Doe (id: 30)",
  card:        "tokn_test_4xs9408a642a1htto8z"
)

新しい顧客の作成

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers \
  -u $OMISE_SECRET_KEY: \
  -d "description=Additional information about Somchai Prasert." \
  -d "email=somchai.prasert@example.com"

<?php

$customer = OmiseCustomer::create(array(
  'email' => 'john.doe@example.com',
  'description' => 'John Doe (id: 30)'
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const customer = await omise.customers.create({
  description: 'John Doe (id: 34)',
  email: 'john.doe@example.com',
});
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.create({
  email: "john.doe@example.com",
  description: "John Doe (id: 30)"
})

var customer = await Client.Customers.Create(new CreateCustomerRequest
{
    Email = "john.doe@example.com",
    Description = "John Doe (id: 30)",
    Metadata = new Dictionary<string, object>
    {
        { "user_id", 30 }
    }
});

Console.WriteLine($"created customer: {customer.Id}");

Request<Customer> request = new Customer.CreateRequestBuilder()
        .email("john.doe@omise.co")
        .description("This cool customer!")
        .build();
Customer customer = client().sendRequest(request);

System.out.printf("Created customer: %s", customer.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.create(
    email="john.doe@example.com", description="John Doe (id: 30)"
)

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Customer{}
err := client.Do(result, &operations.CreateCustomer{
	Email:       "john.doe@example.com",
	Description: "John Doe (id: 30)",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.create(
  email:       "john.doe@example.com",
  description: "John Doe (id: 30)"
)

顧客の削除

- DELETE https://api.omise.co/customers/{id}

顧客を永久に削除します。この操作はロールバックできませんので、慎重に行いましょう。

Example

顧客の削除

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -X DELETE \
  -u $OMISE_SECRET_KEY:

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xtrb759599jsxlhkrb');
$customer->destroy();
$customer->isDestroyed(); # => true

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const customer = await omise.customers.destroy('cust_test_no1t4tnemucod0e51mo');
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")
customer.destroy
customer.destroyed? # => true

var customer = RetrieveCustomer();
customer = await Client.Customers.Destroy(customer.Id);
Console.WriteLine($"destroy customer: {customer.Id}");

Request<Customer> request = new Customer.DeleteRequestBuilder("cust_test_4xtrb759599jsxlhkrb").build();
Customer customer = client().sendRequest(request);

System.out.printf("Destroy customer: %s", customer.getId());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
customer.destroy()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Deletion{}
err := client.Do(result, &operations.DestroyCustomer{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.destroy("cust_test_4xtrb759599jsxlhkrb")

顧客リストの取得

- GET https://api.omise.co/customers

customerに属するすべてのお客様のアカウントオブジェクトの list を返します。

Request Parameters

Name	Type	Description
from	string	(任意, default: `1970-01-01T00:00:00Z`) ISO 8601 形式(`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日時。
limit	integer	(任意, default: `20`) 返されるレコードの数。
offset	integer	(任意, default: `0`) 返される最初のレコードのオフセット(先頭からスキップするレコードの数)。
order	string	(任意, default: `chronological`, one of: `chronological`, `reverse_chronological`) listのオーダーが`chronological` (古い順) or `reverse_chronological` (新しい順)で返されます。エントリがない場合は `null`となります。
to	string	(任意) ISO 8601形式 (`YYYY-MM-DDThh:mm:ssZ`)で返されたレコードの最新のUTC日付と時刻。

Example

顧客リストの取得

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers \
  -u $OMISE_SECRET_KEY:

$customer = OmiseCustomer::retrieve();

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const customer = await omise.customers.list();
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customers = Omise::Customer.list

var customers = await Client.Customers.GetList(order: Ordering.Chronological);
Console.WriteLine($"total customers: {customers.Total}");

Request<ScopedList<Customer>> request = new Customer.ListRequestBuilder().build();
ScopedList<Customer> customers = client().sendRequest(request);

System.out.printf("Total no. of customers: %d", customers.getTotal());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customers = omise.Customer.retrieve()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.CustomerList{}
err := client.Do(result, &operations.ListCustomers{
	operations.List{
		From:  time.Now().Add(-1 * time.Hour),
		Limit: 100,
	},
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.list

顧客情報の取得

- GET https://api.omise.co/customers/{id}

顧客(Customer)オブジェクト作成時に返された顧客IDを指定し、既存の顧客の詳細情報を取得します。

Example

顧客情報の取得

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -u $OMISE_SECRET_KEY:

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xtrb759599jsxlhkrb');

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const customer = await omise.customers.retrieve('cust_test_no1t4tnemucod0e51mo');
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")

var customerId = "cust_test_5665s8r7it17q4wo78a";
var customer = await Client.Customers.Get(customerId);
Console.WriteLine($"customer's email: {customer.Email}");

Request<Customer> request = new Customer.GetRequestBuilder("cust_test_4xtrb759599jsxlhkrb").build();
Customer customer = client().sendRequest(request);

System.out.printf("Customer email: %s", customer.getEmail());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.ScheduleList{}
err := client.Do(result, &operations.RetrieveCustomer{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")

顧客情報の更新

- PATCH https://api.omise.co/customers/{id}

指定した顧客の情報を必要な部分のみ更新します。更新後、その顧客オブジェクトが返されます。

Request Parameters

Name	Type	Description
card	string	(任意) 新しいカードとして顧客に追加するための未使用の[トークン識別子]（/ tokens-api）。
default_card	string	(任意) 課金を作成する際にデフォルトで利用されるカードのCARD_ID。デフォルトカードは顧客に割り当てられる最初のカード。削除されると、最後に追加されたカードがデフォルトカードとなる。顧客にカードが登録されていない場合、nullの値が表示される。
description	string	(任意だが推奨) 顧客の説明。 Opn Paymentsに、顧客に関する追加の詳細情報を提供し、不正防止の検査を改善します。
email	string	(任意だが推奨) 顧客のメールアドレス。 Opn Paymentsに、顧客の電子メールアドレスを提供し、不正防止の検査を改善します。
linked_account	string	(任意) TBD
metadata	object	(任意) 顧客用のカスタムメタデータ（例:`{"customer-id": 42}`) 。

Example

顧客へカードをひも付ける

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "card=tokn_test_5g5mep9yrko3vx2f0hx"

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xtrb759599jsxlhkrb');
$customer->update(array(
  'card' => 'tokn_test_4xs9408a642a1htto8z'
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const customer = await omise.customers.update(
  'cust_test_no1t4tnemucod0e51mo',
  { card: 'tokn_test_no1t4tnemucod0e51mo' },
);
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")
customer.update(card: "tokn_test_4xs9408a642a1htto8z")

var token = await RetrieveToken();

var customerId = "cust_test_5665s8r7it17q4wo78a";
var customer = await Client.Customers.Update(customerId, new UpdateCustomerRequest
{
    Card = token.Id
});

Console.WriteLine($"updated customer: {customer.Id}");

Request<Customer> request = new Customer.UpdateRequestBuilder("cust_test_4xtrb759599jsxlhkrb")
        .card("tokn_test_4xs9408a642a1htto8z")
        .build();
Customer customer = client().sendRequest(request);

System.out.printf("Updated customer: %s", customer.getId());

import omise

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
customer.update(card="tokn_test_no1t4tnemucod0e51mo")

# alteratively
# customer.card = "tokn_test_no1t4tnemucod0e51mo"
# customer.update()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Customer{}
err := client.Do(result, &operations.UpdateCustomer{
	CustomerID: "cust_test_no1t4tnemucod0e51mo",
	Card:       "tokn_test_no1t4tnemucod0e51mo",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.update("cust_test_4xtrb759599jsxlhkrb", [
  card: "tokn_test_4xs9408a642a1htto8z",
])

顧客情報の更新

curl
node.js

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "default_card=card_test_5g021zls9ei5suyryss"

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const customer = await omise.customers.update(
    'cust_test_no1t4tnemucod0e51mo',
    { default_card: 'card_test_no1t4tnemucod0e51mo' }
);
console.log(customer);

顧客情報の更新

curl
php
node.js
ruby
C#
java
python
go
elixir

curl https://api.omise.co/customers/cust_test_5g0221fe8iwtayocgja \
  -X PATCH \
  -u $OMISE_SECRET_KEY: \
  -d "email=somchai.prasert@example.com" \
  -d "description=Another description"

<?php

$customer = OmiseCustomer::retrieve('cust_test_4xtrb759599jsxlhkrb');
$customer->update(array(
  'email' => 'john.smith@example.com',
  'description' => 'Another description'
));

const omise = require('omise')({
  secretKey: 'skey_test_no1t4tnemucod0e51mo',
});

const customer = await omise.customers.update(
  'cust_test_no1t4tnemucod0e51mo',
  {
    email: 'john.smith@example.com',
    description: 'Gold card customer',
  },
);
console.log(customer);

require "omise"

Omise.secret_api_key = "skey_test_4xs8breq3htbkj03d2x"

customer = Omise::Customer.retrieve("cust_test_4xtrb759599jsxlhkrb")
customer.update({
  email: "john.smith@example.com",
  description: "Another description"
})

var customerId = "cust_test_5665s8r7it17q4wo78a";
var customer = await Client.Customers.Update(customerId, new UpdateCustomerRequest
{
    Email = "john.smith@example.com",
    Description = "John Smith",
    Metadata = new Dictionary<string, object>
    {
        { "user_id", 99 }
    }
});

Console.WriteLine($"updated customer: {customer.Id}");

Request<Customer> request = new Customer.UpdateRequestBuilder("cust_test_4xtrb759599jsxlhkrb")
        .email("another@email.com")
        .description("Another description")
        .build();
Customer customer = client().sendRequest(request);

System.out.printf("Updated email: %s", customer.getEmail());

import omise

omise.api_secret = "skey_test_no1t4tnemucod0e51mo"

customer = omise.Customer.retrieve("cust_test_no1t4tnemucod0e51mo")
customer.update(email="somchai.prasert@example.com", description="Another description")

# Or alternatively:
customer.email = "somchai.prasert@example.com"
customer.description = "Another description"
customer.update()

client, _ := omise.NewClient(
	"pkey_test_no1t4tnemucod0e51mo",
	"skey_test_no1t4tnemucod0e51mo",
)

result := &omise.Customer{}
err := client.Do(result, &operations.UpdateCustomer{
	CustomerID:  "cust_test_no1t4tnemucod0e51mo",
	Email:       "john.smith@example.com",
	Description: "Another Description",
})
if err != nil {
	log.Fatalln(err)
}
log.Println(result)

Omise.configure(secret_key: "skey_test_4xs8breq3htbkj03d2x")

Omise.Customer.update("cust_test_4xtrb759599jsxlhkrb", [
  email:       "john.smith@example.com",
  description: "Another description",
])