Payment

Overview

The Payment API is used to begin transactions for purchasing items with MobaCoins.

Payment Object Fields

The Payment object represents a transaction for purchasing an item.

Value	Description	Type	Namespace	Remark
id	The id of the Payment object	xs:string	http://ns.dena.jp/mbga/gameapi/v1	UUID format
appId	The id of the application that will perform this settlement transaction	xs:int	http://ns.dena.jp/mbga/gameapi/v1	–
userId	The guid of the user who will perform this settlement transaction	xs:string	http://ns.dena.jp/mbga/gameapi/v1	–
status	The status of this settlement transaction	xs:int	http://ns.dena.jp/mbga/gameapi/v1	–
entry	A collection of PaymentEntry objects	mbga:PaymentEntry (unbounded)	http://ns.dena.jp/mbga/gameapi/v1	–
callbackUrl	The URL of the settlement completion notification on the partner server	xs:string	http://ns.dena.jp/mbga/gameapi/v1	–
finishUrl	The URL of the screen denoting the end of settlement on the partner server	xs:string	http://ns.dena.jp/mbga/gameapi/v1	–
endpointUrl	The URL of the Mobage server where this settlement transaction is executed	xs:string	http://ns.dena.jp/mbga/gameapi/v1	–
published	Generation date and time	xs:dateTime	http://ns.dena.jp/mbga/gameapi/v1	GMT
updated	Update date and time	xs:dateTime	http://ns.dena.jp/mbga/gameapi/v1	GMT

There is no timezone specifier in the xsd:dateTime type in the response from the API. Therefore, it is represented in GMT (Greenwich Mean Time).

status Column Value

Value	Description
0	Indicates the start of settlement
1	Error
10	Indicates successful completion

PaymentEntry Object Fields

The PaymentEntry object represents information about each item that is contained in an item purchase transaction.

Value	Description	Type	Namespace	Remark
paymentId	id of Payment object	xs:string	http://ns.dena.jp/mbga/gameapi/v1	UUID format
itemId	The ID used by the partner for discriminating items.	xs:int	http://ns.dena.jp/mbga/gameapi/v1	–
name	The name of the item	xs:string	http://ns.dena.jp/mbga/gameapi/v1	Maximum 64 bytes
unitPrice	The unit price of the item (coins)	xs:int	http://ns.dena.jp/mbga/gameapi/v1	–
amount	The number of items purchased	xs:int	http://ns.dena.jp/mbga/gameapi/v1	255 is the upper limit
imageUrl	The URL of the item's image	xs:string	http://ns.dena.jp/mbga/gameapi/v1	gif image only
description	The description of the item	xs:string	http://ns.dena.jp/mbga/gameapi/v1	Maximum 255 bytes

API Request

HTTP Methods

Proxy model

GET
- Gets a Payment entry
POST
- Creates a Payment entry

Trusted model

GET
- Gets a Payment entry

Endpoint URL

Sandbox environment

http://sb.sp.app.mbga.jp/api/restful/v1/payment/{guid}/{selector}/{appid}{-prefix|/|paymentId}

Production environment

http://sp.app.mbga.jp/api/restful/v1/payment/{guid}/{selector}/{appid}{-prefix|/|paymentId}

URI Template Parameters

guid

Specify one of the following values for the guid parameter.

Value	Description	Remark
@me	Represents the guid of the viewer	Required (when POST is used)
{guid}	guid of the user who performed the settlement	Optional (when GET is used)

selector

Specify the following value for the selector parameter.

Value	Description	Remark
@self	Represents the entire Payment collection resource of the viewer	Required

appid

Specify the following value for the appid parameter.

Value	Description	Remark
@app	application id of the application currently being executed	Required

paymentId

Specify the following value for the paymentId parameter.

Value	Description	Remark
{paymentId}	uuid-formatted string	Optional

Query Parameters

The following query parameter can be specified.

format

The response format is as shown below.

Value	Description	Remark
json	"application/json; charset=utf8"	Optional, default value

API Response

Response Codes

The following is a list of the API response codes.

Request HTTP method	Response code	Response message	Description
GET	200	OK	The entry was acquired successfully
GET	400	Bad Request	Invalid request data
GET	404	Not Found	The entry does not exist
GET	500	Internal Server Error	Failed because of an API problem
POST	201	Created	Data was created successfully
POST	400	Bad Request	Invalid request data
POST	401	Unauthorized	OAuth authorization failed
POST	403	Forbidden	Access failed for some reason other than an authentication error
POST	500	Internal Server Error	Failed because of an API problem
–	405	Method Not Allowed	Method is not allowed

Notes

The settlement id is in uuid format.
When getting a Payment entry, access can be performed using the Trusted Model (Consumer Request). Before issuing the request, set the guid parameter to the user's guid instead of '@me'.
If the total amount of the settlement entry (unitPrice X amount) exceeds 100,000 MobaCoins, an error will occur at the endpointUrl (i.e. settlement page).
If a user sends a POST request using the Trusted model to create a Payment entry but has not installed the corresponding application, a 403 will be returned for the response code.
If a non-existent paymentId is specified with the GET request when getting a Payment entry, a 404 will be returned for the response code.

Examples

Adding a Payment

This example shows how to add a Payment entry for the purpose of starting a new settlement transaction.

Request Format

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": "Burst Mo",
      "unitPrice": 100,
      "amount": 3,
      "description": "This is an enhanced version of Burst Doku",
      "imageUrl": "http://example.com/img/item/12.gif"
    }
  ]
}

Response Format

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" : "Burst Mo",
            "unitPrice" : 100,
            "description" : "This is an enhanced version of Burst Doku",
         }
      ],
      "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
}

Get a Payment Entry

Get a Payment entry that already exists.

Request Format

GET http://sb.sp.app.mbga.jp/api/restful/v1/payment/@me/@self/@app/3E37C512-6891-35C1-84FE-B081B5443997?format=json

Response Format

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" : "Vault",
            "unitPrice" : 1000,
            "description" : "This is a traditional item that cannot be purchased now"
         }
      ],
      "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
}

Reference Material

XML Schema Part 2: Datatypes Second Edition
URI Template draft-gregorio-uritemplate-03

Revision History

03/01/2013
- Initial release

Payment

Overview

Payment Object Fields

status Column Value

PaymentEntry Object Fields

API Request

HTTP Methods

Endpoint URL

URI Template Parameters

guid

selector

appid

paymentId

Query Parameters

format

API Response

Response Codes

Notes

Examples

Adding a Payment

Request Format

Response Format

Get a Payment Entry

Request Format

Response Format

Reference Material

Revision History