Payment
概要
アイテム購入トランザクションを開始する API です。
Payment オブジェクトフィールド
アイテム購入トランザクションを表現するオブジェクトです。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| id | Payment オブジェクトの id 値です | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | UUID 形式 |
| appId | この決済トランザクションを行うアプリケーションの id です | xs:int | http://ns.dena.jp/mbga/gameapi/v1 | – |
| userId | この決済トランザクションを行うユーザーの guid です | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | – |
| status | この決済トランザクションのステータス値です | xs:int | http://ns.dena.jp/mbga/gameapi/v1 | – |
| entry | PaymentEntry オブジェクトです(entryの複数指定は非対応です) | mbga:PaymentEntry (unbounded) | http://ns.dena.jp/mbga/gameapi/v1 | – |
| callbackUrl | パートナー様側の決済完了通知用の URL | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | – |
| finishUrl | パートナー様側の決済終了画面用の URL | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | – |
| endpointUrl | この決済トランザクションを実行する決済画面の URL | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | – |
| published | 生成日時 | xs:dateTime | http://ns.dena.jp/mbga/gameapi/v1 | GMT |
| updated | 更新日時 | xs:dateTime | http://ns.dena.jp/mbga/gameapi/v1 | GMT |
API からのレスポンスに含まれる xsd:dateTime 型の形式にはタイムゾーン指定子は含まれていません。従って GMT (グリニッジ標準時)での表記となっております。
status カラム値
| 値 | 説明 |
|---|---|
| 0 | 決済開始時 |
| 1 | エラー |
| 10 | 成功 |
PaymentEntry オブジェクトフィールド
アイテム購入トランザクションに含まれる各アイテムの情報を表すオブジェクトです。
| 値 | 説明 | 型 | 名前空間 | 補足 |
|---|---|---|---|---|
| paymentId | Payment オブジェクトの id | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | UUID 形式 |
| itemId | パートナー様がアイテムを区別する為の識別子です。 | xs:int | http://ns.dena.jp/mbga/gameapi/v1 | – |
| name | アイテムの名称です | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | 64byte まで |
| unitPrice | アイテムの単価です | xs:int | http://ns.dena.jp/mbga/gameapi/v1 | – |
| amount | アイテムの購入個数です | xs:int | http://ns.dena.jp/mbga/gameapi/v1 | 255 が上限 |
| imageUrl | アイテム画像のある URL です | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | gif 画像のみ |
| description | アイテムの説明文です | xs:string | http://ns.dena.jp/mbga/gameapi/v1 | 255byte まで |
API リクエスト
HTTP メソッド
Proxy モデル
- GET
- Payment エントリの取得
- POST
- Payment エントリの作成
Trusted モデル
- GET
- Payment エントリの取得
エンドポイント URL
-
Sandbox 環境
http://sb.sp.app.mbga.jp/api/restful/v1/payment/{guid}/{selector}/{appid}{-prefix|/|paymentId} -
本番環境
http://sp.app.mbga.jp/api/restful/v1/payment/{guid}/{selector}/{appid}{-prefix|/|paymentId}
URI Template パラメータ
guid
guid パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @me | viewer の guid を表します | 必須 (POST時) |
| {guid} | 決済を行ったユーザーの guid 値 | 任意 (GET 時) |
selector
selector パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @self | viewer の Payment コレクションリソース全体を表します | 必須 |
appid
appid パラメータは下記のいずれかの値を指定します。
| 値 | 説明 | 備考 |
|---|---|---|
| @app | 現在実行中の application id | 必須 |
paymentId
paymentId パラメータは下記のいずれかの値を指定します
| 値 | 説明 | 備考 |
|---|---|---|
| {paymentId} | uuid 形式の文字列です | 任意 |
クエリパラメータ
下記のクエリパラメータを指定する事が出来ます。
format
レスポンス形式を指定する事が出来ます。
| 値 | 説明 | 備考 |
|---|---|---|
| json | "application/json; charset=utf8" | 任意、デフォルト値 |
API レスポンス
レスポンスコード
API のレスポンスコードは以下のいずれかになります。
| リクエスト HTTP メソッド | レスポンスコード | レスポンスメッセージ | 説明 |
|---|---|---|---|
| GET | 200 | OK | 正常にエントリの取得が完了しました |
| GET | 400 | Bad Request | リクエストデータが不正です |
| GET | 404 | Not Found | 存在しないエントリです |
| GET | 500 | Internal Server Error | API 側の問題による失敗です |
| POST | 201 | Created | 正常にデータ生成が完了しました |
| POST | 400 | Bad Request | リクエストデータが不正です |
| POST | 401 | Unauthorized | OAuth による認可が失敗しています |
| POST | 403 | Forbidden | 認証エラー以外の理由でアクセス出来ない場合です |
| POST | 500 | Internal Server Error | API 側の問題による失敗です |
| – | 405 | Method Not Allowed | メソッドが許可されていません |
注意事項
-
決済 id は uuid 形式となっております。
-
Payment エントリの取得時に Trusted Model (Consumer Request) でのアクセスが可能です。その際は guid パラメータに '@me' ではなく、ユーザーの guid 値を設定して下さい。
-
決済エントリの総額 (unitPrice×amount) が10万を超えた場合には、endpointUrl (=決済ページ) でエラーとなります。
-
Payment エントリの作成 (POST) 時にユーザーがそのアプリケーションをインストールしていない場合やTrustedモデルでリクエストされた場合に、レスポンスコードは 403 が返ります。
-
Payment エントリの作成 (POST) 時にamountの購入上限個数の255以上が値に設定された場合、レスポンスコードは 400 が返ります。
-
Payment エントリの取得 (GET) 時に存在しない paymentId を指定しリクエストされた場合、レスポンスコードは 404 が返ります。
-
Payment エントリの取得 (GET) 時にユーザーがそのアプリケーションをインストールしていない場合に、レスポンスコードは 403 が返ります。
サンプル
Payment の追加
新しい決済トランザクションを開始する為の Payment エントリを追加する例です。
备注
PaymentEntryオブジェクトは複数指定に対応しておりません。 :::
リクエスト形式
POST /api/restful/v1/payment/@me/@self/@app
Content-Type: application/json; charset=utf8
{
"callbackUrl": "http://example.com/callback",
"finishUrl": "http://exaple.com/finish",
"entry": [
{
"itemId": 12,
"name": "バースト猛",
"unitPrice": 100,
"amount": 3,
"description": "バースト毒の強化版です",
"imageUrl": "http://example.com/img/item/12.gif"
}
]
}
レスポンス形式
201 Created
Content-Type: application/json; charset=utf-8
Location: http://sb.sp.app.mbga.jp/api/restful/v1/payment/@me/@self/@app/1807AD76-C302-3DF6-BC91-1709EC8F8FB5
{
"startIndex" : 1,
"payment" : {
"finishUrl" : "http://example.com/finish",
"entry" : [
{
"itemId" : 12,
"amount" : 3,
"imageUrl" : "http://example.com/img/item/12.gif",
"paymentId" : "1807AD76-C302-3DF6-BC91-1709EC8F8FB5",
"name" : "バースト猛",
"unitPrice" : 100,
"description" : "バースト毒の強化版です"
}
],
"status" : 0,
"userId" : " sb.sp.app.mbga.jp:100000",
"published" : "2009-12-04T08:03:32",
"endpointUrl" : " http://sb.sp.app.mbga.jp/_pf_pay_confirm?p=1807AD76-C302-3DF6-BC91-1709EC8F8FB5&app_id=12000001",
"appId" : 12000001,
"callbackUrl" : "http://example.com/callback",
"id" : "1807AD76-C302-3DF6-BC91-1709EC8F8FB5",
"updated" : "2009-12-04T08:03:32"
},
"itemsPerPage" : 1,
"totalResults" : 1
}
Payment エントリの取得
既に存在する Payment エントリを取得します。
リクエスト形式
GET http://sb.sp.app.mbga.jp/api/restful/v1/payment/@me/@self/@app/3E37C512-6891-35C1-84FE-B081B5443997?format=json
レスポンス形式
200 OK
Content-Type: application/json
Client-Date: Tue, 16 Feb 2010 06:11:35 GMT
Client-Peer: 202.213.218.55:80
Client-Response-Num: 1
{
"startIndex" : 1,
"payment" : {
"finishUrl" : "http://example.com/finish",
"entry" : [
{
"itemId" : 1,
"amount" : 5,
"imageUrl" : "http://example.com/img/example.gif",
"paymentId" : "3E37C512-6891-35C1-84FE-B081B5443997",
"name" : "金庫",
"unitPrice" : 1000,
"description" : "今は購入出来ない伝説のアイテムです"
}
],
"status" : 0,
"userId" : "sb.sp.app.mbga.jp:10045",
"published" : "2010-02-15T11:21:58",
"endpointUrl" : "http://sb.sp.app.mbga.jp/_pf_pay_confirm?p=3E37C512-6891-35C1-84FE-B081B5443997&app_id=12000125",
"appId" : 12000125,
"callbackUrl" : "http://example.com/callback",
"id" : "3E37C512-6891-35C1-84FE-B081B5443997",
"updated" : "2010-02-15T11:21:58"
},
"itemsPerPage" : 1,
"totalResults" : 1
}
関連項目
参考資料
XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03
更新履歴
- 2013/10/31
- Payment エントリPOSTの購入個数制限による400エラーに関する記述を追加
- 2013/2/22
- Payment エントリGETの403エラーに関する記述を追加
- 2012/06/28
- ニュース掲載 API 改修 の対応に関する記述を追加
- 2011/08/29
- 注意事項に決済額の上限について加筆
- 2010/12/09
- status カラム値 から "キャンセル" を削除