Game Payment Handler Server

The following information applies to ALL game types.

On Nutaku, information about valid in-game items is not managed on the platform itself. Instead, the Nutaku platform relies on a Game Payment Handler Server (GPHS) hosted by each game for securely validating accuracy and for notifying the game server when a payment is completed.

The GPHS URL for the game must be set by the game developer in the CMS in the appropriate field.

Sandbox tip: if you are very early into integrating the game and you don’t have a GPHS in place, but you want to test the rest of the in-app payment flows, you can set the URL in the CMS to “https://skip.payment.handler“ which will cause Nutaku to automatically skip calls to GPHS and consider them approved by default. This only works on sandbox. You will need to implement a real GPHS before you can consider your game integration completed on sandbox, because you need to test the error scenarios too.

Requests sent to GPHS will also include a NutakuS2sKey header with the value you have set in the CMS in the respective field.

There are 2 phases in every payment flow when Nutaku Server calls the GPHS: Creation and Completion/Finalization.

Payment Creation

When the game browser/client wants to initiate the sale of an in-game item, the game code sends the payment creation details to Nutaku (via mechanisms specific to each game type).

In order for Nutaku to validate the accuracy and validity of such a sale, Nutaku Server will perform the following HTTP POST request to your GPHS URL.

Your GPHS must first validate that the NutakuS2sKey header is valid. If not, you MUST return an error of your choosing (anything that is not a success response detailed below).

If the s2s key was valid, then you can look at the url and the body of the request:

• in the URL you will find the following parameters:

  • titleId: this can help you distinguish which game the request is for, if you use the same GPHS for more than one title

  • gameType: pc, sp, android_app or dl. If you need to know in which type of your game was it issued from

  • userId: the Nutaku User ID that initiated the payment

  • paymentId: the unique identifier for this payment

• In the body of the request, you will find a JSON with the following fields:

  • paymentId: same as the paymentId from the url

  • skuId: from your item creation info

  • name: from your item creation info

  • price: from your item creation info

  • imgUrl: from your item creation info

  • description: from your item creation info

  • message: from your item creation info (if you used it)

  • test: if the value of this is 1, it means this is for an internal/staff/test user, so the gold involved in this transaction will not count towards revenue

If the above information is considered valid by the GPHS, then it should respond with HTTP 200 (201 is also equally accepted for this POST case) AND with the following JSON body: {“response_code”:”ok”} (where “ok” is case insensitive).

But, if any of the information is incorrect (wrong price for the skuId, wrong name, user already has the item, s2s key incorrect, etc.) then the GPHS must reject the request by responding with anything else that doesn’t match the above mentioned success format. HTTP 400 or 401 would be a great choice.

Remember to store the above payment info on your server, because you will need it in the next step, if the user reaches payment finalization.

Payment Completion

After payment creation, if the user proceeds to finalize his payment, Nutaku will first subtract the gold from the user balance, and AFTER that will notify your game server about the completion by sending an HTTP PUT request to your GPHS URL.

Note: this behavior is different than the one used by Legacy(OSAPI) system. In OSAPI, the notification was sent before the gold was spent. With GI2, this notification is sent AFTER the gold is spent.

The information the GPHS receives in this PUT request is identical with the one from Payment Creation (POST), except that there is no body included.

The GPHS must validate the NutakuS2sKey header, and if valid, it must proceed with awarding the associated item to the user’s account. Never award items if the key is not valid!

Once the user’s item is properly awarded by your server, the GPHS should respond back to this PUT request with the same success response as in the POST step (except that in this case HTTP 201 is not accepted as success).

Similar to payment creation, any response from your server that is not the accepted success response will be interpreted as an error.

If Nutaku does not receive the correct success response and payload, the spent gold will be reimbursed to the user and your game client will receive it as a slightly special kind of error, so that you can easily tell when the fault was on your game server as opposed to Nutaku server.

Note: Because of the mission-critical nature of this API call, Nutaku allows 30 seconds for a payment completion response, as opposed to 5 seconds for all other requests.

IMPORTANT TO REMEMBER: When you receive payment completion in your game code, do not treat it as a reliable status. Your game must ask your server about it and it should rely entirely on the server having awarded the item already. Do not try to trigger/declare any item awarding within the game’s client side code. Basically payment completions from the game client side should be nothing more than glorified triggers to ask the server for a refreshed inventory state.

Checking payment status (redundant)

This section should be of no interest anymore, because completed payment IDs can be seen in the CMS for any user (unless the payments are more than 3 months old or the user has too many recent payments).

And for the payment flow at runtime, checking the payment status is also redundant with GI2 by design.

But, in the rare case that you have a payment ID that you want to check the status, you can call this API from your server:

If the above responds with 200, and in the JSON body you receive “status”==”purchase”, it confirms that the payment is indeed completed on Nutaku Platform side.