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