Payment Flow (APK)

The Payment Service allows games to offer users the ability to buy in-game content or items in exchange for Nutaku Gold.

To show an icon for the Nutaku Gold currency cost in-game, you may generate your own image asset based on the following png logo: https://www.nutaku.net/images/nutaku-gold-coin.png.

Whenever the Nutaku server calls your game server's API endpoints, the requests will contain an Authorization header. Before performing any logic specific to your endpoint, you must always first verify the Authorization header to ensure it is a genuine request from Nutaku and not a malicious request. Follow the procedure from the OAuth Signature Validation page to perform this verification.

When integrating a nutaku SDK, certain steps become automated and other steps become easier to perform, depending on the chosen SDK.

1. Flow of Payment Service

1. The APK sends payment creation information to the API server using Payment API (with POST method) based on items selected by the user to buy.
2. The API server sends a payment creation confirmation request (POST) to the callbackUrl (specified in the request from the previous step). The body of this request contains all the payment information that needs to be verified. Don't forget to validate that the price is correct too!
3. The payment confirmation is confirmed by the callbackUrl sending HTTP code 200 with response_code:OK in JSON format to the payment confirmation request from the previous step.
4. The API server creates the Payment ID and the transaction URL for the payment confirmation page, and returns them to the APK (as the response for step 1). This is when all the information about the payment should be stored in the partner database.
5. The APK requests transactionUrl content (payment confirmation page).
6. The APK shows the received payment confirmation page to the user.
7. The user presses/taps the purchase confirm button which sends a request to Nutaku for gold payment confirmation.
8. Nutaku sends a Payment Confirmation Request (GET) to the callbackUrl to confirm that the purchase information is still valid.
9. The purchase is confirmed by the partner by sending a response with HTTP code 200 and response_code:OK in JSON format to the payment completion request from the previous step.
10. Nutaku subtracts the gold from the user's account and returns the response to the request initiated in step 7.
11. The APK makes a request for payment information (GET) to the payment API. If the status is 2 (which means payment completed) the partner server awards the user with the purchased items/content.
12. The APK receives the payment information response. If the status is 2 (which means payment completed) the game awards the user with the purchased items/content. Since the partner server is not aware of the successful completion, we recommend you also communicate with your server to let it know about it.
    IMPORTANT: steps 11 and 12 are drawn and written as being centered on the APK, but that is not a secure approach. Users can and will mod your APK and skip those validations. Your item validation logic should be server-side, and you should never award users with items without performing a Server-to-Server request to Nutaku Payment API GET to confirm that the payment is real and status is indeed equal to 2.

2. Payment Creation

It is required to send proper payment information when using Payment API.

Check out everything you need to know about using the API on the Payment API documentation page.

During payment creation, your callbackUrl will receive a payment confirmation request using POST with the details of the purchase, including the items that you will need to confirm. Don't forget to validate that the price is correct too! Hackers often change prices to be much lower than the real value.

3. Payment Completion Confirmation Requests

Payment completion confirmation requests from Nutaku to the partner server's callbackUrl (the one from Step 8 in the flow) are a bit different than the payment creation confirmation requests (the one from step 2).

They are done using GET, not POST.

They do not contain details of the items that are part of the transaction. It is up to the partner server to have the item information stored along with the purchase_id from the time the payment creation request was completed. If you know that you will never have time-limited discounts, you could send a payment information request to the Payment API to retrieve full item information. You could also not verify item accuracy at this point in time and only implement the OAuth validation, but if you do this you won't have data available on the long run other than the reports issues by the developer portal.

The response to the Payment Completion Confirmation Requests technically only require a 200 HTTP code response from your endpoint, but it can be easier to just include the {"response_code":"OK"} json object in the response body so you can share the same logic for all your payment handling endpoints.

Receiving a status of 2 in the Payment Completion Confirmation Request does NOT at all mean the status of the payment is 2 (completed). It only means that the user pressed the purchase button, nothing more. Do NOT award items at this point, even if you are going to return a 200 response.

The following query parameters are added to the sale confirmation URL:

As always, please ensure to check the validity of the OAuth signature before performing any other logic!

4. Expected Response from partner server for payment creation and completion confirmation requests

When receiving payment confirmation requests, after successfully validating the OAuth signature and the validity of items inside the payment or the payment id, the partner server should return a 200 result with a JSON object {"response_code":"OK"}.

If any other response is received by Nutaku, the payment will be considered invalid and the flow is aborted.

Example:

HTTP/1.1 200 OK
 
{"response_code":"OK"} //the json is optional in the particular case of Payment Completion Confirmation requests, but it's best to just keep it there