ナビ
楽天ペイ(オンライン決済 LITE版)
メニュー

APIリファレンス

Charge オブジェクト

クレジットカードで決済するために、ユーザーにcheckout-lite.jsから購入手続きをして頂く必要があります。
決済完了後、楽天側でChargeオブジェクトが生成されます。
その後、各APIを呼ぶ事で、決済の確定・払い戻しを行うことができます。

楽天ペイ(オンライン決済 LITE版)で提供するAPIはすべてJSON形式(JavaScript Object Notation)で返されます。
また、APIへのリクエストはHTTPS経由でのみ受け付けます。通常のHTTPでのアクセスはエラーとなります。

object string
固定値 "charge"
open_id string
楽天で作成するユーザを特定できる一意の番号
例: "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD"
id string
楽天側で作成する注文番号
APIへのリクエストの際には{CHARGE_ID}の箇所にセットしてください。
cipher string
"id:cart_id"をPrivate Keyをキーに、暗号化したもの
livemode boolean
true: Live環境本番の決済, false: Live環境テストまたはSandbox環境での決済
currency string
固定値: "jpy"
amount integer
合計金額
point integer
利用ポイントの合計
cart_id string
御社サイト側で設定いただいたCartID
paid boolean
true: 仮売上あり, false: 仮売上なし
captured boolean
true: 実売上あり, false: 実売上なし
status string
固定値: "succeeded"
refunded boolean
true: キャンセル済み, false: 未キャンセル
items hash
id string
御社サイトで設定した商品ID
name string
御社サイトで設定した商品名
quantity integer
御社サイトで設定した商品の個数
unit_price integer
御社サイトで設定した1商品あたりの単価
address hash
送付先情報を提供する設定の店舗様の場合、購入者様が決済時に選択した送付先情報が返却されます。
それ以外の店舗様の場合はnullが返却されます。
送付先情報の提供をご希望の場合はコチラまでお問い合わせ下さい。
country string
国コード
現在は固定値: "JP"
first_name string
名前
first_name_kana string
カナの名前
last_name string
last_name_kana string
カナの姓
address_zip string
郵便番号
address_state string
都道府県
address_city string
市区町村
address_line string
住所
tel string
電話番号
created timestamp
unixタイム(UTC+09:00 日本時間)でのご注文日時を返します
例: 1433862000
updated timestamp
unixタイム(UTC+09:00 日本時間)での決済確定またはキャンセルの日時を返します。
仮売上の状態ではnullになります。
例: 1433948400
レスポンス例
{
	"object": "charge",
	"open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==", 
	"id": "1250000255-20150623-0000168715",
	"cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
	"livemode": false,
	"currency": "jpy",
	"amount": 5000,
	"point": 1000,
	"cart_id": "cart_id1",
	"paid": true,
	"captured": true,
	"status": "succeeded",
	"refunded": false,
	"items": [
		{
			"id": "item_id1",
			"name": "商品名",
			"quantity": 10,
			"unit_price": 100
		},
		{
			"id": "item_id2",
			"name": "商品名",
			"quantity": 20,
			"unit_price": 200
		}
	],
	"address": {
		"country": "JP",
		"first_name": "太郎",
		"first_name_kana": "タロウ",
		"last_name": "楽天",
		"last_name_kana": "ラクテン",
		"address_zip": "158-0094",
		"address_state": "東京都",
		"address_city": "世田谷区",
		"address_line": "玉川1-14-1",
		"tel": "000-0000-0000"
	},
	"created": 1433862000,
	"updated": 1433948400
}
RpayLite\Charge JSON: {
    "object": "charge",
    "open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==",
    "id": "1250000255-20150623-0000168715",
    "cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
    "livemode": false,
    "currency": "jpy",
    "amount": 5000,
    "point": 1000,
    "cart_id": "cart_id1",
    "paid": true,
    "captured": true,
    "status": "succeeded",
    "refunded": false,
    "items": [
        {
            "id": "item_id1",
            "name": "商品名",
            "quantity": 10,
            "unit_price": 100
        },
        {
            "id": "item_id2",
            "name": "商品名",
            "quantity": 20,
            "unit_price": 200
        }
    ],
    "address": {
        "country": "JP",
        "first_name": "太郎",
        "first_name_kana": "タロウ",
        "last_name": "楽天",
        "last_name_kana": "ラクテン",
        "address_zip": "158-0094",
        "address_state": "東京都",
        "address_city": "世田谷区",
        "address_line": "玉川1-14-1",
        "tel": "000-0000-0000"
    },
    "created": 1433862000,
    "updated": 1433948400
}
<jp.co.rakuten.checkout.lite.model.Charge@*** id=1250000255-20150623-0000168715> JSON: {
  "object": "charge",
  "open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==",
  "id": "1250000255-20150623-0000168715",
  "cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
  "livemode": false,
  "currency": "jpy",
  "amount": 5000,
  "point": 1000,
  "cart_id": "cart_id1",
  "paid": true,
  "captured": true,
  "status": "succeeded",
  "refunded": false,
  "items": [
    {
      "id": "item_id1",
      "name": "商品名",
      "quantity": 10,
      "unit_price": 100
    },
    {
      "id": "item_id2",
      "name": "商品名",
      "quantity": 20,
      "unit_price": 200
    }
  ],
  "address": {
    "country": "JP",
    "first_name": "太郎",
    "first_name_kana": "タロウ",
    "last_name": "楽天",
    "last_name_kana": "ラクテン",
    "address_zip": "158-0094",
    "address_state": "東京都",
    "address_city": "世田谷区",
    "address_line": "玉川1-14-1",
    "tel": "000-0000-0000"
  },
  "created": 1433862000,
  "updated": 1433948400
}

決済の確定

商品の出荷直前、または出荷後に該当注文に対して確定処理を実施してください。
確定処理が正常に実施されると店舗様のみ、その旨のメールが送信されます。
仮売上は作成後一定期間が過ぎると確定処理が出来なくなります。

id
必須
string
楽天側で作成する注文番号
処理したい決済のChargeオブジェクトに含まれているidを{CHARGE_ID}の箇所にセットしてください。
定義
Live:
	https://api.lite.checkout.rakuten.co.jp/v1/charges/{CHARGE_ID}/capture
Sandbox:
	https://api.lite.checkout.rakuten.co.jp/sandbox/v1/charges/{CHARGE_ID}/capture 
$ch = \RpayLite\Charge::retrieve({CHARGE_ID});
$ch->capture();
ch = Charge.retrieve({CHARGE_ID});
ch.capture();
リクエスト例
$ curl "https://api.lite.checkout.rakuten.co.jp/sandbox/v1/charges/1250000255-20150623-0000168715/capture" \
-u "sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b": \
-X POST
\RpayLite\RpayLite::setApiKey('sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b');
$ch = \RpayLite\Charge::retrieve("1250000255-20150623-0000168715");
$ch->capture();
RpayLite.setApiKey("sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b");
ch = Charge.retrieve("1250000255-20150623-0000168715");
ch.capture();
レスポンス例
{
    "object": "charge",
	"open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==", 
	"id": "1250000255-20150623-0000168715",
	"cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
	"livemode": false,
	"currency": "jpy",
	"amount": 5000,
	"point": 1000,
	"cart_id": "cart_id1",
	"paid": true,
	"captured": true,
	"status": "succeeded",
	"refunded": false,
	"items": [
		{
			"id": "item_id1",
			"name": "商品名",
			"quantity": 10,
			"unit_price": 100
		},
		{
			"id": "item_id2",
			"name": "商品名",
			"quantity": 20,
			"unit_price": 200
		}
	],
	"address": null,
	"created": 1433862000,
	"updated": 1433948400
}
RpayLite\Charge JSON: {
    "object": "charge",
    "open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==",
    "id": "1250000255-20150623-0000168715",
    "cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
    "livemode": false,
    "currency": "jpy",
    "amount": 5000,
    "point": 1000,
    "cart_id": "cart_id1",
    "paid": true,
    "captured": true,
    "status": "succeeded",
    "refunded": false,
    "items": [
        {
            "id": "item_id1",
            "name": "商品名",
            "quantity": 10,
            "unit_price": 100
        },
        {
            "id": "item_id2",
            "name": "商品名",
            "quantity": 20,
            "unit_price": 200
        }
    ],
    "address": null,
    "created": 1433862000,
    "updated": 1433948400
}
<jp.co.rakuten.checkout.lite.model.Charge@*** id=1250000255-20150623-0000168715> JSON: {
    "object": "charge",
    "open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==",
    "id": "1250000255-20150623-0000168715",
    "cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
    "livemode": false,
    "currency": "jpy",
    "amount": 5000,
    "point": 1000,
    "cart_id": "cart_id1",
    "paid": true,
    "captured": true,
    "status": "succeeded",
    "refunded": false,
    "items": [
        {
            "id": "item_id1",
            "name": "商品名",
            "quantity": 10,
            "unit_price": 100
        },
        {
            "id": "item_id2",
            "name": "商品名",
            "quantity": 20,
            "unit_price": 200
        }
    ],
    "address": null,
    "created": 1433862000,
    "updated": 1433948400
}
エラー例
{
	"errors": [
		{
			"type": "payment_error",
			"code": "credit_card_declined",
			"message": "This credit card cannot be used"
		}
	]
}

決済の払い戻し

決済の金額変更およびキャンセルが行えます。
金額変更は仮売上と実売上どちらのステータスの場合でも行えますが、キャンセル済みの場合には行えません。
金額変更は減額・増額どちらも行えます。金額変更およびキャンセルが正常に実施されると、購入者および店舗様へその旨のメールが送信されます。
Sandboxでは購入者のみにメール送信されます。

確定済みの決済を金額変更およびキャンセルできる期限は決済の確定が実施された日時から翌月末までです。

キャンセルの際には、POSTパラメータを付けずにリクエストしてください。

金額変更の際には、変更後の商品構成として下記のパラメータを必要な分POSTパラメータとして付与してください。
前回(初回の金額変更であれば注文時の商品構成)の商品構成は破棄され、新たにリクエストされた商品構成およびその合計金額で仮売上として決済されます。
確定済み・確定前の決済いずれも金額変更を行い成功すると、決済ステータスは仮売上(paid: true, captured: falseの状態)になりますので、商品提供後に必ず決済の確定処理を行ってください。

レスポンスはリクエストの結果が反映されたChargeオブジェクトが返却されます。

キャンセルの場合
id
必須
string
楽天側で作成する注文番号
処理したい決済のChargeオブジェクトに含まれているidを{CHARGE_ID}の箇所にセットしてください。

金額変更の場合
id
必須
string
楽天側で作成する注文番号
処理したい決済のChargeオブジェクトに含まれているidを{CHARGE_ID}の箇所にセットしてください。
item_id_N
必須
string (N=1~50)
御社サイトで設定した商品ID
item_name_N
必須
string (N=1~50)
御社サイトで設定した商品名
item_quantity_N
必須
string (N=1~50)
御社サイトで設定した商品の個数
item_unit_price_N
必須
string (N=1~50)
御社サイトで設定した1商品あたりの単価
定義
Live:
	https://api.lite.checkout.rakuten.co.jp/v1/charges/{CHARGE_ID}/refund
Sandbox:
	https://api.lite.checkout.rakuten.co.jp/sandbox/v1/charges/{CHARGE_ID}/refund
//キャンセル
$charge = \RpayLite\Charge::retrieve({CHARGE_ID});
$charge->cancel();
//金額変更
$charge = \RpayLite\Charge::retrieve({CHARGE_ID});
$charge->refund({PARAMS});
//キャンセル
Charge ch = Charge.retrieve({CHARGE_ID});
ch = ch.refund();
//金額変更
Charge ch = Charge.retrieve({CHARGE_ID});
ch = ch.update(Map<String, Object> params); 
リクエスト例
$ curl "https://api.lite.checkout.rakuten.co.jp/sandbox/v1/charges/1250000255-20150623-0000168715/refund" \
     -X POST \
     -u "sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b": \
     -d "item_id_1=item-001" \
     -d "item_name_1=商品名1" \
     -d "item_quantity_1=2" \
     -d "item_unit_price_1=1500"
\RpayLite\RpayLite::setApiKey('sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b');
$charge = \RpayLite\Charge::retrieve('1250000255-20150623-0000168715');
$charge->refund([
    "item_id_1" => "item-001",
    "item_name_1" => "商品名1",
    "item_quantity_1" => "2",
    "item_unit_price_1" => "1500"
]);
RpayLite.setApiKey("sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b");
Charge ch = Charge.retrieve("1250000255-20150623-0000168715");
Map<String, Object> params = new HashMap<String, Object>();
params.put("item_id_1", "item-001");
params.put("item_name_1", "商品名1");
params.put("item_quantity_1", "2");
params.put("item_unit_price_1", "1500");
ch = ch.update(params); 
レスポンス例
{
	"object": "charge",
	"open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==",
	"id": "1250000255-20150623-0000168715",
	"cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
	"livemode": false,
	"currency": "jpy",
	"amount": 3000,
	"point": 0,
	"cart_id": "cart_id1",
	"paid": true,
	"captured": false,
	"status": "succeeded",
	"refunded": false,
	"items": [
		{
			"id": "item-001",
			"name": "商品名1",
			"quantity": 2,
			"unit_price": 1500
		}
	],
	"address": null,
	"created": 1433862000,
	"updated": 1433948400
}
RpayLite\Charge JSON: {
    "object": "charge",
    "open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==",
    "id": "1250000255-20150623-0000168715",
    "cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
    "livemode": false,
    "currency": "jpy",
    "amount": 3000,
    "point": 0,
    "cart_id": "cart_id1",
    "paid": true,
    "captured": false,
    "status": "succeeded",
    "refunded": false,
    "items": [
        {
            "id": "item-001",
            "name": "商品名1",
            "quantity": 2,
            "unit_price": 1500
        }
    ],
    "address": null,
    "created": 1433862000,
    "updated": 1433948400
}
<jp.co.rakuten.checkout.lite.model.Charge@*** id=1250000255-20150623-0000168715> JSON: {
    "object": "charge",
    "open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==",
    "id": "1250000255-20150623-0000168715",
    "cipher": "7d2558bba9a49d22a4788dca9395c21289b953571a92388891da8bb6b210a12d",
    "livemode": false,
    "currency": "jpy",
    "amount": 3000,
    "point": 0,
    "cart_id": "cart_id1",
    "paid": true,
    "captured": false,
    "status": "succeeded",
    "refunded": false,
    "items": [
        {
            "id": "item-001",
            "name": "商品名1",
            "quantity": 2,
            "unit_price": 1500
        }
    ],
    "address": null,
    "created": 1433862000,
    "updated": 1433948400
}
エラー例
{
	"errors": [
		{
			"type": "payment_error",
			"code": "credit_card_declined",
			"message": "This credit card cannot be used"
		}
	]
}

決済リストの取得

過去に作成された決済のリストを取得することが出来ます。リストは最新のもの(Charge オブジェクトのcreatedが一番新しいもの)から順に取得されます。
検索条件として矛盾した値を指定した場合エラーにはならず、検索条件に何も当てはまらなかったとして0件として返されます。

limit
任意
integer
取得するCharge オブジェクトの上限数
1から100の間の整数を指定することができます。
デフォルト: 10
offset
任意
integer
Charge オブジェクトを何件目から取得するかを指定できます。0が1件目を取得する値となりますので、offset=49&limit=10であれば最新のCharge オブジェクトの50件目から10件のCharge オブジェクトを取得できます。
デフォルト: 0
payment
任意
hash
決済の状態で絞り込むことが出来ます。
以下の条件はOR検索となります。例えばpayment[captured]=true&payment[paid]=false&payment[refunded]=trueの場合、決済が確定またはキャンセルされたCharge オブジェクトのみ返却されます。
captured boolean
実売上化した決済を取得します。
デフォルト: true
paid boolean
仮売上までの決済を取得します。
デフォルト: true
refunded boolean
キャンセル済みの決済を取得します。
デフォルト: true
id
任意
string
検索したい決済のChargeオブジェクトに含まれているidを指定できます。
デフォルト: null
starting_after
任意
string
Chargeオブジェクトに含まれているidを指定することで、指定したCharge オブジェクトよりも古いCharge オブジェクトを取得できます。
この機能は主にページング処理を実装したリスト表示を行いたい場合に利用します。例えば1ページ目の最後のCharge オブジェクトのidがobj_fooの場合、2ページ目のデータを取得する時にstarting_after=obj_fooとすることで1ページ目の最後のCharge オブジェクトであるobj_fooの次のCharge オブジェクトから指定の件数を取得できます。
デフォルト: null
created
任意
timestampまたはhash
決済の作成日(Charge オブジェクトのcreated)で絞り込むことが出来ます。
unixタイム(UTC+09:00 日本時間)で指定します。
デフォルト: null
gt timestamp
指定のタイムスタンプよりも後に作成されたCharge オブジェクトを取得できます。
デフォルト: null
gte timestamp
指定のタイムスタンプと同時または後に作成されたCharge オブジェクトを取得できます。
デフォルト: null
lt timestamp
指定のタイムスタンプよりも前に作成されたCharge オブジェクトを取得できます。
デフォルト: null
lte timestamp
指定のタイムスタンプと同時または前に作成されたCharge オブジェクトを取得できます。
デフォルト: null
定義
Live:
	https://api.lite.checkout.rakuten.co.jp/v1/charges
Sandbox:
	https://api.lite.checkout.rakuten.co.jp/sandbox/v1/charges
\RpayLite\Charge::all({PARAMS});
Charge.list(Map<String, Object> params);
リクエスト例
$ curl "https://api.lite.checkout.rakuten.co.jp/sandbox/v1/charges" \
-u "sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b": \
-X GET \
-G \
-d "limit=3" \
-d "offset=10" \
-d "payment[paid]=true" \
-d "created[gte]=1498834800" \
-d "created[lte]=1499180400"
\RpayLite\RpayLite::setApiKey('sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b');
$charges = \RpayLite\Charge::all([
    'limit' => 3,
    'offset' => 10,
    'payment[paid]' => 'true',
    'created[gte]' => 1498834800,
    'created[lte]' => 1499180400
]);
RpayLite.setApiKey("sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b");
Map<String, Object> params = new HashMap<String, Object>();
params.put("limit", 3);
params.put("offset", 10);
params.put("payment[paid]", true);
params.put("created[gte]", 1498834800);
params.put("created[lte]", 1499180400);
ChargeCollection chargeList = Charge.list(params);
レスポンス例
{
	"object": "list",
	"url": "/v1/charges",
	"limit": 3,
	"offset": 10,
	"total": 20,
	"data": [
		{
			"object": "charge",
			"open_id": "https://myid.rakuten.co.jp/openid/user/VMUk1L5gzHScrf7iL20OzA==",
			"id": "1250000255-20170704-0000003291",
			"cipher": "321a31abef2fe18c3c210191ee789bba72fecb39aed63ce4bc2e1aad6682177fddbf009565c62d02384b8441463f80a6",
			"livemode": false,
			"currency": "jpy",
			"amount": 5000,
			"point": 1000,
			"cart_id": "cart-id1",
			"paid": true,
			"captured": false,
			"status": "succeeded",
			"refunded": false,
			"items": [
				{
					"id": "item_id1",
					"name": "商品名",
					"quantity": 10,
					"unit_price": 100
				},
				{
					"id": "item_id2",
					"name": "商品名",
					"quantity": 20,
					"unit_price": 200
				}
			],
			"address": null,
			"created": 1499135173,
			"updated": null
		},
		{...},
		{...}
	]
}
RpayLite\ChargeCollection JSON: {
    "object": "list",
    "url": "/v1/charges",
    "limit": 3,
    "offset": 10,
    "total": 20,
    "data": [
        {
            "object": "charge",
            "open_id": "https://myid.rakuten.co.jp/openid/user/VMUk1L5gzHScrf7iL20OzA==",
            "id": "1250000255-20170704-0000003291",
            "cipher": "321a31abef2fe18c3c210191ee789bba72fecb39aed63ce4bc2e1aad6682177fddbf009565c62d02384b8441463f80a6",
            "livemode": false,
            "currency": "jpy",
            "amount": 5000,
            "point": 1000,
            "cart_id": "cart-id1",
            "paid": true,
            "captured": false,
            "status": "succeeded",
            "refunded": false,
            "items": [
                {
                    "id": "item_id1",
                    "name": "商品名",
                    "quantity": 10,
                    "unit_price": 100
                },
                {
                    "id": "item_id2",
                    "name": "商品名",
                    "quantity": 20,
                    "unit_price": 200
                }
            ],
            "address": null,
            "created": 1499135173,
            "updated": null
        },
        {...},
        {...}
    ]
}
<jp.co.rakuten.checkout.lite.model.ChargeCollection@*** id=null> JSON: {
    "object": "list",
    "url": "/v1/charges",
    "limit": 3,
    "offset": 10,
    "total": 20,
    "data": [
        {
            "object": "charge",
            "open_id": "https://myid.rakuten.co.jp/openid/user/VMUk1L5gzHScrf7iL20OzA==",
            "id": "1250000255-20170704-0000003291",
            "cipher": "321a31abef2fe18c3c210191ee789bba72fecb39aed63ce4bc2e1aad6682177fddbf009565c62d02384b8441463f80a6",
            "livemode": false,
            "currency": "jpy",
            "amount": 5000,
            "point": 1000,
            "cart_id": "cart-id1",
            "paid": true,
            "captured": false,
            "status": "succeeded",
            "refunded": false,
            "items": [
                {
                    "id": "item_id1",
                    "name": "商品名",
                    "quantity": 10,
                    "unit_price": 100
                },
                {
                    "id": "item_id2",
                    "name": "商品名",
                    "quantity": 20,
                    "unit_price": 200
                }
            ],
            "address": null,
            "created": 1499135173,
            "updated": null
        },
        {...},
        {...}
    ]
}

Notification オブジェクト

店舗様がDashboardまたはAPIを用いて購入者様へお知らせメールを送信する際に楽天ペイ(オンライン決済 LITE版)は新規にNotification オブジェクトを作成します。
Notification オブジェクトは、店舗様から購入者へのお知らせメール一件ごとに作成され、お知らせ内容などを含みます。
ただし、購入時やキャンセル時に楽天から自動的に購入者様に送られるメールについては、Notification オブジェクトは作成されません。

object string
固定値: "notification"
id string
オブジェクトのID
charge string
購入者(お知らせメールの受信者)の注文の注文番号
type string
現在は固定値: "notification.mail"
subject string
お知らせメールの件名
body string
お知らせメールの本文
created timestamp
お知らせメール送信日時のunixタイム(UTC+09:00 日本時間)
例: 1433862000
レスポンス例
{
  "object": "notification",
  "id": "ntfn_82d8fc8531934446bda3e7c835f79c3a",
  "charge": "1250000255-20150623-0000168715",
  "type": "notification.mail",
  "subject": "通知件名",
  "body": "通知本文",
  "created": 1456116957
}
RpayLite\Notification JSON: {
  "object": "notification",
  "id": "ntfn_82d8fc8531934446bda3e7c835f79c3a",
  "charge": "1250000255-20150623-0000168715",
  "type": "notification.mail",
  "subject": "通知件名",
  "body": "通知本文",
  "created": 1456116957
}
<jp.co.rakuten.checkout.lite.model.Notification@*** id=ntfn_82d8fc8531934446bda3e7c835f79c3a> JSON: {
  "object": "notification",
  "id": "ntfn_82d8fc8531934446bda3e7c835f79c3a",
  "charge": "1250000255-20150623-0000168715",
  "type": "notification.mail",
  "subject": "通知件名",
  "body": "通知本文",
  "created": 1456116957
}

メールの送信

購入者様の注文番号を指定することで、その購入者様の楽天会員に登録されているメールアドレスにお知らせメールを送信することができます。 1注文につき30回まで、注文日から180日までの間で注文の状態を問わずAPIへのリクエストが可能です。
この機能は、購入者様のメール受信を保証するものではありません。

charge
必須
string
注文番号
メールの送信先となる注文番号(Chargeオブジェクトのid)を設定してください。
subject
必須
string
メール件名
件名になる文字列(上限80文字)を設定してください。文字として機種依存文字は使えません。
body
必須
string
メール本文
本文になる文字列(上限4000文字)を設定してください。文字として機種依存文字は使えません。本文中に下記の文字列を挿入することで実際に送信されるお知らせメールの内容に特定の表現ができます。
\n 改行
改行に置き換えられます。
#CUSTOMER_NAME#  購入者様氏名
通知時に自動的に楽天会員情報に登録されている購入者様の氏名に置き換えられます。
例: 決済 太郎
実際に送信されるメールには、下記の文言がメールの文頭に自動で挿入されます。
------------------------------------------------------------------------------------------ - 本メールは楽天ペイがお預かりしたお客様の注文に関する大切なご連絡です。 このメールアドレスへご返信いただきましても、お返事出来ませんのでご注意ください。 ------------------------------------------------------------------------------------------ - 購入者様氏名 様
定義
Live:
    https://api.lite.checkout.rakuten.co.jp/v1/notifications/mail
Sandbox:
    https://api.lite.checkout.rakuten.co.jp/sandbox/v1/notifications/mail
$charge = \RpayLite\Charge::retrieve({CHARGE_ID});
$notification = \RpayLite\Notification::create({PARAMS});
Notification.send(Map<String, Object> params);
リクエスト例
curl "https://api.lite.checkout.rakuten.co.jp/sandbox/v1/notifications/mail" \
-u "sandbox_private_29b3c884c5b6475addf90f768de3ab7d0fa8e1bbd2a12a8cb7400ab0f74367eb1e4866489d555e9e8861935577029ccb": \
-d "charge=1250000255-20150623-0000168715" \
-d "subject=件名" \
-d "body=商品を発送しました。\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。" \
-X POST
\RpayLite\RpayLite::setApiKey('sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b');
$charge = \RpayLite\Charge::retrieve('1250000255-20150623-0000168715');
  
$notification = \RpayLite\Notification::create([
    'charge' => $charge->id,
    'subject' => '件名',
    'body' => '商品を発送しました。\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。',
    'type' => 'notification.mail'
]);
RpayLite.setApiKey("sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b");
Map<String, Object> params = new HashMap<String, Object>();
params.put("charge", "1250000255-12345678-0123456789");
params.put("subject", "件名");
params.put("body", "商品を発送しました。\\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。");
Notification n = Notification.send(params);
レスポンス例
{
    "object": "notification",
    "id": "ntfn_77cc7ad01dee4772a2f4ed4c9778da89",
    "charge": "1250000255-20150623-0000168715",
    "type": "notification.mail",
    "subject": "件名",
    "body": "商品を発送しました。\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。",
    "created": 1456126606
}
RpayLite\Notification JSON: {
    "object": "notification",
    "id": "ntfn_77cc7ad01dee4772a2f4ed4c9778da89",
    "charge": "1250000255-20150623-0000168715",
    "type": "notification.mail",
    "subject": "件名",
    "body": "商品を発送しました。\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。",
    "created": 1456126606
}
<jp.co.rakuten.checkout.lite.model.Notification@*** id=ntfn_77cc7ad01dee4772a2f4ed4c9778da89> JSON: {
    "object": "notification",
    "id": "ntfn_77cc7ad01dee4772a2f4ed4c9778da89",
    "charge": "1250000255-20150623-0000168715",
    "type": "notification.mail",
    "subject": "件名",
    "body": "商品を発送しました。\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。",
    "created": 1456126606
}
エラー例
{
    "errors": [
        {
            "type": "invalid_request_error",
            "code": "invalid_character",
            "message": "Request contains invalid characters."
        }
    ]
}

メール送信済リストの取得

過去に送信されたお知らせメールのNotification オブジェクトのリストを取得することが出来ます。 リストは最新のもの(Notification オブジェクトのcreatedが一番新しいもの)から順に取得されます。
ただし、365日経過したものは消去され取得できません。
検索条件として矛盾した値を指定した場合エラーにはならず、検索条件に何も当てはまらなかったとして0件として返されます。

charge
必須
string
注文番号
通知の送信先となる注文番号(Chargeオブジェクトのid)を設定してください。
id
任意
string
id
検索したい決済のNotification オブジェクトに含まれているidを指定できます。
デフォルト: null
定義
Live:
    https://api.lite.checkout.rakuten.co.jp/v1/notifications
Sandbox:
    https://api.lite.checkout.rakuten.co.jp/sandbox/v1/notifications
\RpayLite\Notification::all({PARAMS});
Notification.list(Map<String, Object> params);
リクエスト例
curl "https://api.lite.checkout.rakuten.co.jp/sandbox/v1/notifications?charge=1250000255-20150623-0000168715" \
-u "sandbox_private_29b3c884c5b6475addf90f768de3ab7d0fa8e1bbd2a12a8cb7400ab0f74367eb1e4866489d555e9e8861935577029ccb":
\RpayLite\RpayLite::setApiKey('sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b');
$notifications = \RpayLite\Notification::all(["charge" => '1250000255-20150623-0000168715']);
RpayLite.setApiKey("sandbox_private_8df4e30255c151fb4462ed6c03bc1b1ebc8b40c5e8da59d9b318ff70fd1c6ce60133c213ba6bb489b146b3f800ac375b");
Map<String, Object> params = new HashMap<String, Object>();
params.put("charge", "1250000255-20150623-0000168715");
NotificationCollection nc = Notification.list(params);
レスポンス例
{
    "object": "list",
    "url": "/v1/notifications",
    "total": 10,
    "data": [
        {
            "object": "notification",
            "charge": "1250000255-20150623-0000168715",
            "type": "notification.mail",
            "id": "ntfn_77cc7ad01dee4772a2f4ed4c9778da89",
            "subject": "件名",
            "body": "商品を発送しました。\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。",
            "created": 1456126606
    },
    {...},
    {...}
    ]
}
RpayLite\NotificationCollection JSON: {
    "object": "list",
    "url": "/v1/notifications",
    "total": 10,
    "data": [
        {
            "object": "notification",
            "charge": "1250000255-20150623-0000168715",
            "type": "notification.mail",
            "id": "ntfn_77cc7ad01dee4772a2f4ed4c9778da89",
            "subject": "件名",
            "body": "商品を発送しました。\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。",
            "created": 1456126606
    },
    {...},
    {...}
    ]
}
<jp.co.rakuten.checkout.lite.model.NotificationCollection@*** id=null> JSON: {
    "object": "list",
    "url": "/v1/notifications",
    "total": 10,
    "data": [
        {
            "object": "notification",
            "charge": "1250000255-20150623-0000168715",
            "type": "notification.mail",
            "id": "ntfn_77cc7ad01dee4772a2f4ed4c9778da89",
            "subject": "件名",
            "body": "商品を発送しました。\n#CUSTOMER_NAME# 様のまたのご利用をお待ちしております。",
            "created": 1456126606
    },
    {...},
    {...}
    ]
}
エラー例
{
    "errors": [
        {
            "type": "invalid_request_error",
            "code": "invalid_format",
            "message": "Request format is invalid."
        }
    ]
}

Event オブジェクト

Eventオブジェクトは、決済等でどのようなイベントが起こっているかを通知や取得する機能として提供されています。
何らかのイベントが発生した時に、楽天ペイ(オンライン決済 LITE版)は新規にEventオブジェクトを作成します。 楽天ペイ(オンライン決済 LITE版)では、イベント発生後に店舗様へ正常に通知が完了するまで複数回リトライを行う非同期型Webhook、およびイベント発生時にリアルタイム処理で1度だけ店舗様に通知する同期型 Webhookがあります。
Webhookについては、Webhookを参照してください。

object string
固定値 "event"
id string
このイベントのID
livemode boolean
true: Live環境本番の決済, false: Live環境テストまたはSandbox環境での決済
type string
イベントの種類
イベントの種類に一覧があります。
synchronous boolean
true: 同期型 false:非同期型
data hash
イベントに関連したデータを持つハッシュ。
object hash
イベントの内容についての概要。例えば、charge.checkイベントの場合は、課金(Charge)オブジェクトが入ります。
pending_webhooks integer
非同期型Webhookで、まだ送信できていない(2xxのレスポンスが得られていない)webhookの数
created timestamp
unixタイム(UTC+09:00 日本時間)でイベントが生成された日時を返します
例: 1433862000
APIエンドポイント
御社サイトのWebhook用エンドポイントURL
Eventオブジェクト例
{
	"object": "event",
	"id": "evt_ace3a9e65ad548a8b5c8de7965efa160",
	"livemode": false,
	"type": "charge.check",
	"synchronous": true,
	"data": {
		"object": {
			"object": "charge",
			"open_id": "https://myid.rakuten.co.jp/openid/user/h65MxxxxxxxQxn0wJENoHHsalseDD==", 
			"id": null,
			"cipher": null,
			"livemode": false,
			"currency": "jpy",
			"amount": 5000,
			"point": 1000,
			"cart_id": "cart_id1",
			"paid": false,
			"captured": false,
			"status": null,
			"refunded": false,
			"items": [
				{
					"id": "item_id1",
					"name": "商品名",
					"quantity": 10,
					"unit_price": 1000
				},
				{
					"id": "item_id2",
					"name": "商品名",
					"quantity": 20,
					"unit_price": 2000
				}
			],
			"address": null,
			"created": null,
			"updated": null
		}
	},
	"pending_webhooks": 0,
	"created": 1433862000
}

イベントの種類

楽天ペイ(オンライン決済 LITE版)にて作成されるイベントの種類一覧です。

イベント(非同期型)

charge.succeeded 決済完了(決済関連)
新規決済が行われて成功した際に発生します。
charge.captured 確定(課金関連)
ChargeAPIにて仮売上が実売上化された際に発生します。
charge.refunded 払い戻し(課金関連)
一部払い戻しも含めて、課金の払い戻し処理が行われた際に発生します。 仮売上が実売上化されることなく、失効した場合にも発生します。

イベント(同期型)

charge.check 決済可否確認(決済関連) このイベントを設定すると、新規に決済が行われる直前に指定のエンドポイントURLにリクエストが送信されます。 正常に2xxのステータスコードが返却されると、引き続き決済処理に進みます。 2xx以外のステータスコードまたはタイムアウト等で確認できなかった場合、決済処理は中断され、決済作成処理が決済画面で行われている場合にはユーザー様に決済が完了せずエラーとなった旨の表示がされます。
ping 関連なし
Webhookの設定画面からテストのイベントを発行したときに送信されます。または楽天が接続確認のために任意のタイミングで送信されます。

APIエラー

楽天ペイ(オンライン決済 LITE版)のAPIリクエストで成功した場合には必ず2xxのステータスコードを成功として返しますが、エラーが発生した場合、4xxまたは5xxのHTTPレスポンスのステータスコード、typeプロパティ、codeプロパティ、messageプロパティをJSON形式にて返します。
エラーの種類によっては同時に複数のエラーを返す場合があります。
HTTPレスポンスのステータスコードの種類により、typeプロパティ、codeプロパティ、messageプロパティのいずれか、または全てが空で返る場合があります。

HTTPステータスのステータスコード

400 Bad Request
不正なリクエストです。
401 Unauthorized
認証キーが間違っています。
402 Payment Request
決済エラーです。
405 Method Not Allowed
リクエストのメソッドが間違っています。
500 Internal Server Error
楽天ペイ(オンライン決済)または楽天ペイ(オンライン決済)が接続しているクレジットカード会社のシステムが原因によるエラーです。
503 Service Unavailable
システムメンテナンス、または短期間での高頻度のリクエストによる高負荷が発生しています。しばらく時間をおいてから再度リクエストをお願い致します。

typeプロパティ

maintenance 楽天のシステムメンテナンス中です。
invalid_request_error パラメータに不正があります。
unauthorized_error 認証キーが間違っています。
api_error 楽天ペイ(オンライン決済)または楽天ペイ(オンライン決済)が接続しているクレジットカード会社のシステムが原因によるエラーです。
payment_error クレジットカードまたは楽天スーパーポイントに関連するエラーです。

codeプロパティ

通常発生しうる一般的なエラーのみ掲載されています。 また、全てのエラーでcodeプロパティに値が入る訳ではありませんので、頻度の高いエラーの分岐としてご利用下さい。

invalid_format リクエストのフォーマットが誤っています。
invalid_key 正しい認証キーが設定されていません。
duplicate_parameter パラメータが重複しています。
invalid_item_info 商品情報のフォーマットが誤っています。
duplicate_item_id 商品ID(item_id)が重複しています。
temporarily_unavailable ただいまご利用になれません。しばらくたってからご利用ください。
invalid_payment_status 注文は確定またはキャンセルされています。
expired_order キャンセル・金額変更・確定処理の締日を過ぎています。
above_maximum_amount リクエストの総合計金額が9,999,999円を超過しています。
below_minimum_amount リクエストの総合計金額が100円未満です。
unchanged_amount 合計金額に変更がありません。
order_not_found 注文が存在しません。
credit_card_declined 使用できないクレジットカードです。
credit_card_limit_exceeded 限度額から超過しています。後日、再度お試しください。
below_minimum_points ポイント利用数が下限を下回っています。
above_maximum_points ポイント利用数が上限を上回っています。
insufficient_points ポイントが不足しています。
エラー例
{
	"errors": [
		{
			"type": "invalid_request_error",
			"code": "invalid_format",
			"message": "Request format is invalid"
		}
	]
}