1. Codashop Fullfillment API
1.1 Introduction
This document is intended for merchants for which top-ups or recharges will be sold on the Codashop website. This document describes the API which Codashop uses to validate game account details, and submit top-up requests.
Publishers must provide an API which will be called by Codashop to both validate and execute a top up request. It is highly recommended for publishers to build this API using the standard Codashop Fulfillment API specification as described in this document in order to make the integration with Codashop seamless with minimal integration effort.
1.2 Support and Feedback
For implementation support and any feedback, please reach out to your Coda Payments contact person.
2. Transaction Process Flow
When the customer initiates the purchase, Codashop will first confirm with the merchant that the user account and top up details are valid (Validation Request). If the details are confirmed by the merchant (Validation Request Rresponse), Codashop lets the customer proceed to payment. When payment has been successfully completed, Codashop sends a top up request (Top Up Request) to the merchant endpoint. This should result in the purchased item being added to the customer’s account.
3. Validation Request
3.1 Codashop Transaction Validation Request
A message containing the order details for the merchant to validate. This message is sent before payment is collected, to confirm that a top up can be successfully made after payment is successfully completed. If a top up call with the parameters used in the validate call would result in an error, the error should be returned as a response to the validate request.The expected response time for a top up request is 5 seconds.
Example
Format: JSON-RPC
JSON
{
"id": "6164699909785264260",
"jsonrpc": "2.0",
"method": "validate",
"params": [
{
"isForTest": 1,
"price": {
"amount": "50000",
"Currency": "IDR"
},
"serviceProvider": "Coda",
"quantity": "1",
"paymentChannelId": "227",
"sku": "Diamonds_10",
"purchaseOrigin": "TH",
"user": {
"userId": "111111",
"zoneId": "101"
},
"signature": "4646fbd3363ab452f40187f8744cd321f71968ed01cdc19c416203832cddd76e",
"txnId": "6164695159717629913",
"orderId": "6164695159719894644"
}
]
}
3.2 Codashop Transaction Validation Response
3.2.1 Valid transaction response
Example 1
Format: JSON-RPC
JSON
{
"id": "6164695159717629913",
"jsonrpc": "2.0",
"result": {
"roleList": [
{
"roleName": "roleA",
"roleId": "111"
},
{
"roleName": "roleB",
"roleId": "222"
},
{
"roleName": "roleC",
"roleId": "333"
}
],
"merchantTransactionId": "816176257914769"
"accountRegionCode": "SG"
}
}
Example 2
If there are multiple roles or sub-accounts under each account, and the user needs to choose which one to top up, the option should be shared as a roleList. Only roles that can be topped up should be included. Coda will present these options to the user before proceeding to payment.
JSON
{
"id": "6164695159717629913",
"jsonrpc": "2.0",
"result": {
"roleList": [
{
"roleName": "roleA",
"roleId": "111"
},
{
"roleName": "roleB",
"roleId": "222"
},
{
"roleName": "roleC",
"roleId": "333"
}
],
"merchantTransactionId": "816176257914769"
"accountRegionCode": "SG"
}
}
3.2.2 Invalid transaction response
Example
Format: JSON-RPC
JSON
{
"id": "6164695159717629913",
"jsonrpc": "2.0",
"error": {
"code": -100,
"message": "Invalid user ID"
}
}
4. Top up Request
4.1 Codashop top up request
A message containing the details of a successful purchase, from Codashop to the merchant. This should lead to the customer’s game account being topped up with the item specified in the call. Codashop expects a response within 5 seconds. Procedure should be idempotent, responses to two identical calls should be identical, and not lead to top-ups being processed multiple times.Note that ID, txnId, and orderId used in top up requests may be different from what is used in the validate request for the corresponding purchase. Fulfilments of top ups should be done based on SKU only.
Example
JSON
{
"id": "6164699909785264260",
"jsonrpc": "2.0",
"method": "topup",
"params": [
{
"isForTest": 1,
"price": {
"amount": "50000",
"currency": "IDR"
},
"serviceProvider": "Coda",
"quantity": 1,
"paymentChannelId": 227,
"sku": "Diamonds_10",
"purchaseOrigin": "TH",
"user": {
"userId": "111111",
"zoneId": "101",
"roleId": "111"
},
"signature":
"73d173363f6706d59c35bcea785f543488389b68d582a9b2339e9450db177695",
"txnId": "6164699909785264260",
"orderId": "6164699909782101750",
"merchantTransactionId": "816176257914769"
}
]
}
4.2 Codashop top up response
4.2.1 Valid transaction response
Message returned when top-up has been completed successfully.
Example
Format: JSON-RPC
JSON
{
"id": "6164699909785264260",
"jsonrpc": "2.0",
"error": {
"code": -103,
"message": "Server is under maintenance"
}
}
4.2.2 Invalid transaction response
Response returned when a top-up fails. While failures in the validate process are expected, a failure in this method is an unexpected event, as all parameters of the topup should already have been validated.
Example
Format: JSON-RPC
JSON
{
"id": "6164699909785264260",
"jsonrpc": "2.0",
"error": {
"code": -103,
"message": "Server is under maintenance"
}
}
5. Fetch Server List Request
5.1 Codashop Fetch Server List Request
Optional. A url which allows coda to fetch server list by get method.
5.1 Codashop Fetch Server List Request
The response of the fetch server list request from the merchant. It should include serverName, serverId and isForTest.
Example
Format: JSON
Format for one-level server list
JSON
{
"serverList": {
"Area 1": [
{
"serverName": "Server 1",
"serverId": "1000001",
"isForTest": 0
},
{
"serverName": "Server 2",
"serverId": "1000002",
"isForTest": 0
}
],
"Area 2": [
{
"serverName": "Server 3",
"serverId": "1000003",
"isForTest": 0
},
{
"serverName": "Server 4",
"serverId": "1000004",
"isForTest": 0
}
]
}
}
Format for two-level server list:
JSON
{
"serverList": {
"Area 1": [
{
"serverName": "Server 1",
"serverId": "1000001",
"isForTest": 0
},
{
"serverName": "Server 2",
"serverId": "1000002",
"isForTest": 0
}
],
"Area 2": [
{
"serverName": "Server 3",
"serverId": "1000003",
"isForTest": 0
},
{
"serverName": "Server 4",
"serverId": "1000004",
"isForTest": 0
}
]
}
}
6. Authorization
6.1 Signature Calculation
The signature must be included in all requests. The signature for a request is a hash of the following fields, in correct sequence: id + jsonrpc + method + serviceProvider + txnId + orderId + userId + zoneId + currency + amount + sku + quantity + paymentChannelId + isForTest (+ roleId)
Example
id = “4123456789012345678”
jsonrpc = "2.0"
method = "topup"
serviceProvider = "Coda"
txnId = “4123456789012345678"
orderId = "4876543210987654321"
userId "1002356"
zoneId": "101"
currency = "IDR"
amount = "200000.0"
sku = "diamonds_1"
quantity = 1
paymentChannelId = 0
isForTest = 0
roleId="111"
secretKey = 1234567890ABCDE
1. If roleId is not required:
The Hmac value should be calculated as:
hmac.encode ("secretKey",
"41234567890123456782.0topupCoda412345678901234567848765432109876543
211002356101IDR200000.0diamonds_1100", ‘SHA256’)
The resulting signature value equals: 2244c750825a1098abf5175fd1dbd7041fabbb2d6eb5178ee20cd16d28455035
2. If roleId is required:The Hmac value should be calculated as:hmac.encode("secretKey", "41234567890123456782.
0topupCoda412345678901234567848765432109876543
211002356101IDR200000.0diamonds_1100111",
‘SHA256’)
The resulting signature value equals:
2c72d71189de832a61c45c6e217766a8d0f882e4c27e72e4662096a7ef352b0f
Sample bash script using python to generate the signature:
#-------------------------------------------------------------
echo -e "import hashlib,hmac\nprint hmac.new('secretKey',
'41234567890123456782.0topupCoda4123456789012345678487654321098765432
11002356101IDR200000.0diamonds_112270', hashlib.sha256).hexdigest()" | python
#-------------------------------------------------------------
Sample code for signature generation.
*secretKey: The merchant defines this value and shares it with Coda.