Squareは決済サービスなので、極端に言えば決済額と決済情報（クレジットカード情報など）さえあれば十分です。しかし、決済は金額だけの話ではなく、商品や発送先、値引き、税金など様々な情報が追加されます。
それらをすべて自社データベースに保存して、決済額だけをSquareに送るのも良いですが、逆にSquareに情報を残す方法も用意されています。それが Order APIになります。
Order APIの特徴
Order APIは以下の情報で構成されます。
- 商品情報
- 税情報
- 値引き情報
これらはあらかじめAPIを通じて作成しておくこともできますし、管理画面で作成もできます。さらに商品などは作らずにその場で情報を作成することもできます。
例えば以下はRubyで実行する例です。 商品情報（line_items）、税情報（taxes）、値引き情報（discounts）にそれぞれ対応しています。
catalog_object_id というのは Catalog API で取得できるオブジェクトIDで、商品やカテゴリ、税、ディスカウント情報などが同じオブジェクトという形で取得できます。
response = api.create_order(location.id, {
idempotency_key: SecureRandom.uuid,
reference_id: 'my-order-001',
line_items: [
{
name: 'New York Strip Steak',
quantity: '1',
base_price_money: {amount: 1599, currency: 'JPY'}
},
{
catalog_object_id: 'UUAOONEUM2ROCL2UEW3VLH2I',
quantity: '2',
discounts: [
{
name: 'Sale - $1.00 off',
amount_money: {amount: 100, currency: 'JPY'}
}
]
}
],
taxes: [
{
name: 'State Sales Tax',
percentage: '9'
}
],
discounts: [
{
name: 'Labor Day Sale',
percentage: '5'
},
{
catalog_object_id: 'SG353KJSVUWL35WMO23IIU3U'
}
]
})
オブジェクトIDは以下のように取得できます。
api = SquareConnect::CatalogApi.new
opts = {
types: [
SquareConnect::CatalogObjectType::CATEGORY,
SquareConnect::CatalogObjectType::TAX,
SquareConnect::CatalogObjectType::ITEM,
SquareConnect::CatalogObjectType::ITEM_VARIATION,
SquareConnect::CatalogObjectType::MODIFIER,
SquareConnect::CatalogObjectType::DISCOUNT
].join(',')
}
response = api.list_catalog(opts)
Order APIの返り値には id が入っていますので、それを使って決済処理が行えます。
api.charge(location.id, {
idempotency_key: idempotency_key,
amount_money: {
amount: total_money, currency: 'JPY'
},
card_nonce: card_nonce,
order_id: order_id,
reference_id: 'optional reference #112358',
note: 'optional note'
})
このように order_id として指定することで、決まった商品情報を使って決済ができるようになります。決済処理と注文情報を結びつけて管理したいときであったり、決まった商品、税、値引き情報を使って決済処理を行いたいときに便利でしょう。