> For the complete documentation index, see [llms.txt](https://docs.coda.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coda.co/coda-webstore/coda-webstore-appendix/web-store-integration-faqs.md).

# Web Store Integration FAQs

## <mark style="color:purple;">**Abbreviations**</mark>

* <mark style="color:purple;">SKUs</mark>: Stock-keeping unit, or also identified as the unique item/ product ID sent in the API request.
* <mark style="color:purple;">Product Name</mark>: Name of product that will be displayed to end-user on your web store
* <mark style="color:purple;">FX</mark>: Foreign Exchange
* <mark style="color:purple;">TxnID</mark>: Transaction ID

## <mark style="color:purple;">**General Questions**</mark>

### <mark style="color:purple;">**1.1 How long is the integration process for my web store?**</mark>

The integration process is highly dependent on the date Coda receives the Partner API urls (Validate and Top-up urls), Assets, SKUs and pricing details. After receiving the submissions from the [Coda Portal,](https://bit.ly/4aNqHRf) it takes Coda few days for the review and testing of product pages. For customized integrations, this could take longer, depending on the complexity of the API. You can refer to our Custom Commerce integration Guide for the detailed steps.

### <mark style="color:purple;">**1.2 What are some best practices to ensure good performance on the web store?**</mark>

Performance on your web store can vary greatly, however, some of these best practices include:

1. Price advantage when compared to traditional app stores
2. Additional bonuses on purchases
3. Marketing support from your end
4. Special SKUs such as :\
   Battle Passes\
   Weekly Passes\
   Monthly Passes\
   Special Bundles (limited purchases)\
   For these SKUs, implementation on the web store is straight-forward. The logic check will happen on your side (Coda does not have access to game data). You will need to send us an error message during validation if the userID is not eligible for such purchases, and we will display the respective error messages to end-users.

## <mark style="color:purple;">**Custom Commerce Functionalities**</mark>

### <mark style="color:purple;">**2.1 How do we run promotions on my web store? Who do I reach out to and how will it work?**</mark>

For promotions, please connect with Coda’s BD or marketing team for in-depth details.\
For pricing-related promotion: Please provide Coda with the updated set of pricing (SKUs if there are any changes), along with the promotion period. Coda will help to configure the promotion pricing for the specific period.\
\
For bonus item issuance promotion: Please provide Coda a description that we could include on the left side of the product page. Do provide us with the content a week or so before so we can get the necessary translations done.

### <mark style="color:purple;">**2.2**</mark> <mark style="color:purple;"></mark><mark style="color:purple;">Can the webstore be hosted on our own custom domain name (e.g., <https://www.google.com/search?q=shop.mygame.com>)?</mark>

Yes. A key feature of the Custom Commerce service is the ability to use your own domain or subdomain. This reinforces your brand and creates a seamless experience for your players. You will need to configure the necessary DNS records (e.g., CNAME) to point your domain to the Coda-hosted webstore.

## <mark style="color:purple;">**Custom Commerce Integration Template & Price Table**</mark>

### <mark style="color:purple;">**3.1 What do we need to fill in the price table? What part should we pay attention to?**</mark>

Here's how you can Bulk upload the SKUs and Prices - [Bulk Upload Products](/codashop-and-distribution/bulk-upload-inventory-skus.md)

For the price table, here are the things that need to be filled up:\
Product Name, Product/SKU id, Prices (Default USD Price. You can also submit local country prices). Check out this section for more details > [Coda's Pricing Template](/coda-portal/coda-portal-appendix/codas-pricing-template.md)

{% hint style="info" %}
Take note that some countries will use USD instead of local currency. i.e. Cambodia
{% endhint %}

{% hint style="info" %}
Take note that local currency prices are not dynamic, if there are any changes required due to FX fluctuations, please Update the FX or edit Prices on the [Coda Portal](https://bit.ly/4aNqHRf) accordingly.
{% endhint %}

If your title/app is already live on Google Play, you can easily integrate Coda with your Google account in just 5 minutes. To assist you in this process, we have provided a detailed step-by-step guide [Google Play Integration](/codashop-and-distribution/bulk-import-inventory-skus-from-google-play/1.-google-play-integration.md). By following these instructions, you can effortlessly share SKU data directly from your Google Play account to Coda.

### <mark style="color:purple;">**3.2 Can Coda help us convert USD prices to prices in local currency? What exchange rate will be applied if it’s possible?**</mark>

Yes. If you provide just the Default USD price, Coda will convert the USD price to local currencies for each country. You will be able to see and edit all the local prices on the [Coda Portal](https://bit.ly/4aNqHRf) before Publishing them on your web store.

### <mark style="color:purple;">**3.3 How would users know that your web store prices are better compared to traditional app stores?**</mark>

Coda can make use of Strikethrough pricing to let users know about the lower prices. We will show the original price with a strikethrough and show the value proposition to the end-user.

### <mark style="color:purple;">**3.4 How does Google Play Integration work?**</mark>

Google Play integration helps to fetch the Price and SKU data directly from the Google Play console.\
If you are a new Publisher signing up with Coda for the first time, this integration allows you to go live with all your listings across 60+ countries in less than < 5 minutes.\
\
Please refer to the complete guide here >> [Google Play Integration](/codashop-and-distribution/bulk-import-inventory-skus-from-google-play/1.-google-play-integration.md)

## <mark style="color:purple;">**Custom Commerce Third Party Fulfilment API**</mark>

### <mark style="color:purple;">**4.1**</mark> <mark style="color:purple;"></mark><mark style="color:purple;">What is the specific purpose of the Validate API call versus the Top-up API call?</mark>

They serve two distinct and critical functions in the transaction flow:

1. **Validate API**: This is called before the user pays. Its purpose is to confirm that the Player ID is valid and eligible to receive the item. This prevents users from paying for a purchase that cannot be delivered.
2. **Top-up API**: This is called after the user has successfully paid. Its purpose is to trigger the actual crediting of the purchased item to the player's account.

### <mark style="color:purple;">**4.2 Who should provide the secretkey?**</mark>

You will need to provide the secretkey to Coda. It is recommended that the length of the secretkey not exceed 64 characters.

### <mark style="color:purple;">**4.3 What is the value of a service provider, and what are some use cases?**</mark>

Service providers can be used in cases where there are different apps using the same API. If not used, the default value used should be “Coda”

### <mark style="color:purple;">**4.4 What is Coda’s transaction TPS cap?**</mark>

There is no transaction cap, Coda will scale our system based on different needs.

### <mark style="color:purple;">**4.5 When the Coda website is in a maintenance period or the server is down or has any code error while the website is running, do we have any website live monitoring dashboard?**</mark>

No. Coda has a set of monitoring systems that are used internally, by our technical support team.

### <mark style="color:purple;">**4.6 Are the values of TxnID (payment transaction ID) and OrderID (Coda order ID different in the Validate and Top-up request?**</mark>

Yes, we will send different values during the [Validation](/codashop-and-distribution/integration-guides/validation-api-request.md) and [Top Up](/codashop-and-distribution/integration-guides/top-up-api-request.md) request call. If you require to associate both calls, please use the optional merchantTransactionId.

### <mark style="color:purple;">**4.7 What are the differences between Transaction ID and Order ID?**</mark>

Transaction ID is the payment transaction ID, while Order ID is the Coda order ID. Usually, we recommend using/ saving transaction ID as a point of reference in your system.

### <mark style="color:purple;">**4.8 There are two top up calls to \[First Time Top Up] and \[Second Time Top Up] in the test log.**</mark> <mark style="color:purple;">**Please help explain the process and callback mechanism of reprocessing the recharge request call (recallback).**</mark>

This is part of a negative case testing done by Coda, to verify that the top up interface is idempotent. This is to ensure that when calling the top up request using the same TxnID, you should not issue items more than once. You should not issue items for the subsequent top up calls.

### <mark style="color:purple;">**4.9 How does Coda do geo-fencing?**</mark>

For geo-fencing, there is an additional parameter in the API field, “accountRegion”. You can return the user’s country information in this parameter and Coda will allow/prevent the user from recharging if the user’s country information does not match the country of the product page.\
The country/region code should be a two-character code that conforms to the ISO3166 standard (<https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes>)

For example:

```
{
"jsonrpc": "2.0",
"id": "6496922564067972630",
"result": {
"username": "Barbara",
"accountRegion": "ID"
}
}
```

If you wish to validate the country on your end, we will send the product page country as “purchaseOrigin” in the validation request.

### <mark style="color:purple;">**4.10 What will be displayed to the end-user when an error code is sent in the API?**</mark>

When an error code is sent in an API, the corresponding error message will be shown to end-users. You can refer to the error codes displayed in our API documentation.\
\*Displayed error messages will be updated overtime, however, the meaning of them will not change.

### <mark style="color:purple;">**4.11 Does Coda support sending USD prices in the API requests?**</mark>

No, we will include the currency based on the currency on the product page.

### <mark style="color:purple;">**4.12 Why are the values of TxnID and OrderID different in validate and top-up calls?**</mark>

When Validate and Top Up are called, TxnID and OrderID will be different. If you wish to associate the validate and top-up call together, you can make use of the optional field “merchantTransactionId”.

### <mark style="color:purple;">**4.13**</mark> <mark style="color:purple;"></mark><mark style="color:purple;">What specific HTTP Status Codes should my Validate/Top-up APIs return?</mark>

Your API should use standard HTTP status codes to communicate outcomes.

* **`200 OK`**: For any successful response where you are returning a valid JSON body (including validation successes, validation failures with a specific error message, or successful top-ups).
* **`4xx` (e.g., 400 Bad Request)**: For malformed requests from Coda (e.g., missing parameters).
* **`5xx` (e.g., 500 Internal Server Error)**: For unexpected errors on your server that prevent you from processing the request. This will signal to Coda that there is a problem.

### <mark style="color:purple;">**4.14**</mark> <mark style="color:purple;"></mark><mark style="color:purple;">What is the best practice for handling API timeouts or latency?</mark>

Your API endpoints should be designed to respond quickly (ideally under 2 seconds). If Coda's call to your server times out, the transaction will fail. You should configure monitoring and alerts for your API's performance. If your server experiences intermittent timeouts when calling Coda, you should implement a safe retry mechanism with exponential backoff for network-related errors.

### <mark style="color:purple;">**4.15**</mark> <mark style="color:purple;"></mark><mark style="color:purple;">How do I secure my Validate and Top-up APIs? (Checksum/Signature Verification)</mark>

To ensure that all requests to your server are authentic and from Coda, you must validate the `checksum` (a SHA256 signature) sent in the header of every Validate and Top-up API call. You generate your own signature using the request body and your shared `secretkey` and compare it to the signature Coda sends. **If the checksums do not match, you must reject the request** to prevent fraudulent transactions.

## <mark style="color:purple;">**Custom Commerce QA & Launching**</mark>

### <mark style="color:purple;">**5.1 Can we launch all the available countries globally at the same time?**</mark>

For a global launch, we will launch them at the same time globally. However, do also inform us of the prioritization so we can launch in batches if necessary.

### <mark style="color:purple;">**5.2 Is it possible for Coda to support testing all denominations listed on my web store? Are there any payment credentials that can be shared with us for testing?**</mark>

Coda will only test the lowest denomination on your web store. For the other denominations, Coda QA will try to initiate a validate call to ensure that there is no issue. This is because we are trying to verify the integration with your web store and not the integration with the Payment Channels. These payment channels are active on your web store and will always work.

*Payment credentials are not able to be shared with you as these are all production accounts owned by Coda.*

### <mark style="color:purple;">**5.3 Will the money used for pre-launch testing by Coda be taken into account in our settlement?**</mark>

Yes, these funds will be counted in your settlement because we use actual money for conducting tests on production.

## <mark style="color:purple;">**Custom Commerce Operations**</mark>

### <mark style="color:purple;">**6.1 If we want to make some changes to the current SKUs (ex: SKU price change or adding new SKUs etc.), how many days should we notify you in advance?**</mark>

If you have already uploaded the Prices and SKU data on the [Coda Portal](https://portal.codapayments.com/signup), you can edit the prices on the Portal. Once you submit the Prices, the status will change to In-Review and our internal pricing team will review the new prices, and need to reconcile with you in case the new prices are not in line with our price regulation. Besides that, we will also have our QA team to review and sometimes conduct testing on it if needed before launching new prices/SKUs on my web store. The lead time for this is around 1-2 days.\
\
If necessary, Coda will reach out to discuss these changes if it's not in line with our pricing practices. As we want to make sure our operation team has sufficient time to prepare for the required changes, please note that usually, we may need you to make the Price edits on Portal or inform us at least 3 days in advance.

### <mark style="color:purple;">**6.2 What’s the refund policy for my web store? What should we provide to Coda if we get a user’s refund request?**</mark>

Generally, Coda does not provide refunds to users, subject to different countries' regulations. This is also mentioned in our Terms and Conditions to users.\
\
However, Coda might process a refund to the user on a case-by-case basis. Below are some examples:

1. The user made payment but did not receive the item purchase. Upon checking with you, they are unable to issue the item purchased to the user. Coda will process the refund for the user.
2. The user made the payment, but there is an issue with Coda’s system. Coda will process the refund for the user.

### <mark style="color:purple;">**6.3**</mark> <mark style="color:purple;"></mark><mark style="color:purple;">How are customer payment disputes and chargebacks handled?</mark>

When a user disputes a charge with their payment provider (a chargeback), Coda’s finance and risk teams manage the dispute process. Liability for the chargeback cost is determined by the commercial agreement between you and Coda. Typically, Coda absorbs fraud-related chargebacks due to its robust risk engine, but this can vary.

### <mark style="color:purple;">**6.4 What should I do if there is maintenance for the app?**</mark>

This depends on the logic of your system. During maintenance, if users are still allowed to recharge and will receive their items as normal, there is no need to deactivate the pages during maintenance.

\
However, if users would not be able to receive their purchased items during maintenance. Please inform Coda 3 days ahead of any scheduled maintenance so we can arrange for the page to be disabled during the maintenance.

## <mark style="color:purple;">**Financial Operations & Analytics**</mark>

### <mark style="color:purple;">**7.1**</mark> <mark style="color:purple;"></mark><mark style="color:purple;">How do we perform financial reconciliation and when do we get paid?</mark>

Coda provides detailed financial reports through the Coda Portal. These reports break down sales, revenue, taxes, and fees by country, payment channel, and day. You can use these to reconcile with your own sales data. Payouts (settlements) are sent to you on a regular, pre-agreed schedule (e.g., bi-weekly or monthly).

### <mark style="color:purple;">**7.2**</mark> <mark style="color:purple;"></mark><mark style="color:purple;">What kind of reporting and analytics can I access for my webstore's performance?</mark>

The Coda Portal includes a dashboard with analytics on your webstore's performance. You can typically view key metrics such as:

* Total revenue and transaction volume.
* Sales broken down by country.
* Top-selling SKUs.
* Conversion funnel

You can check out the Insights features to see the different dashboard [Data Insights](/coda-portal/key-features/data-insights.md)

## <mark style="color:purple;">**Financial Operations & Analytics**</mark>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coda.co/coda-webstore/coda-webstore-appendix/web-store-integration-faqs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.