### User Account Format for Topup Requests (JSON Examples)

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/direct-topup-purchase

Provides JSON examples for the 'userAccount' field in topup requests, varying based on product subtype and whether a role ID is included. These examples illustrate the expected structure for different user account configurations.

```json
"userAccount": "4294967319"
```

```json
"userAccount": {
     "userId": "4294967319",
     "roleId": "1234"
     }
```

```json
"userAccount": {
      "userId": "4294967319",
      "server": {
        "id": "90001",
        "name": "Eternal Love"
      }
    }
```

```json
"userAccount": {
     "userId": "4294967319",
     "server": {
        "id": "90001",
        "name": "Eternal Love"
      },
      "roleId": "1234"
    }
```

```json
"userAccount": {
      "userId": "4294967319",
      "zoneId":"771"
    }
```

```json
"userAccount": {
      "userId": "4294967319",
      "zoneId":"771"
```

--------------------------------

### Get Current Prepayment Balance (OpenAPI)

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-prepayment-balance

This OpenAPI 3.0.3 specification defines the endpoint for retrieving the current prepayment balance. It outlines the request method (GET), the path (/balance), and the structure of the successful response, which includes a list of balances per country and currency.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "xShop API",
    "version": "2.0.0"
  },
  "tags": [
    {
      "name": "balance",
      "description": "Get prepayment balance"
    }
  ],
  "servers": [
    {
      "url": "https://xshop.codashop.com/v2",
      "description": "Production server"
    },
    {
      "url": "https://xshop-sandbox.codashop.com/v2",
      "description": "Sandbox server"
    }
  ],
  "paths": {
    "/balance": {
      "get": {
        "tags": [
          "balance"
        ],
        "summary": "Get current prepayment balance",
        "description": "List all prepayment balance partner have",
        "operationId": "getBalance",
        "responses": {
          "200": {
            "description": "successful requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/prepaymentBalance"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "prepaymentBalance": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "description": "Constant jsonrpc version 2.0"
          },
          "id": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "properties": {
              "balanceList": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "country": {
                      "type": "string",
                      "description": "Prepayment balance country"
                    },
                    "currency": {
                      "type": "string",
                      "description": "Prepayment balance currency"
                    },
                    "balance": {
                      "type": "number",
                      "description": "Prepayment balance remaining"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### POST /{product-name} - Get Order Details

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-order-details

Retrieve order details by providing a RequestId. This endpoint allows partners to fetch the status and details of an order previously submitted.

```APIDOC
## POST /{product-name}

### Description
Get order detail by request Id. Partners can retrieve order details by passing the RequestId that was submitted during the validate or placeOrder API call.

### Method
POST

### Endpoint
`https://xshop.codashop.com/v2/{product-name}`

### Parameters
#### Path Parameters
- **product-name** (string) - Required - Name of the product to purchase

#### Request Body
- **jsonrpc** (string) - Required - Constant jsonrpc version 2.0
- **id** (string) - Required - Request ID generated by client
- **method** (string) - Required - The method to call, expected to be 'getOrder'
- **params** (object) - Required - Parameters for the getOrder method
  - **requestId** (string) - Required - Unique ID from the client that is submitted on placeOrder or topup API.
  - **iat** (integer) - Required - The "iat" (issued at) field indicates the token's issuance time, which must be a UNIX EPOCH timestamp in UTC and within 5 minutes of the request time.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "request-id-from-client",
  "method": "getOrder",
  "params": {
    "requestId": "unique-request-id",
    "iat": 1678886400
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant jsonrpc version 2.0
- **id** (string) - Unique request ID from the client
- **result** (object) - The result of the getOrder operation
  - **status** (string) - Enum: "FULFILLED", "FAILED" - The status of the order.
  - **orderId** (string) - The Coda Order ID.
  - **items** (array) - Only for voucher orders. Contains details about the items in the order.
    - **sku** (string) - SKU ID from list SKU
    - **codes** (string) - Voucher code

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "request-id-from-client",
  "result": {
    "status": "FULFILLED",
    "orderId": "coda-order-id-12345",
    "items": [
      {
        "sku": "sku-abc",
        "codes": "voucher-code-xyz"
      }
    ]
  }
}
```
```

--------------------------------

### Get SKU Detail - OpenAPI Specification

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-product-and-sku-catalogue

This OpenAPI 3.0.3 specification defines the 'getSku' endpoint for retrieving SKU details. It includes request parameters, response schemas, and server configurations for both production and sandbox environments. The API returns detailed information about a SKU, including its ID, description, country, pricing, and more.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "xShop API",
    "version": "2.0.0"
  },
  "tags": [
    {
      "name": "sku",
      "description": "Get sku details"
    }
  ],
  "servers": [
    {
      "url": "https://xshop.codashop.com/v2",
      "description": "Production server"
    },
    {
      "url": "https://xshop-sandbox.codashop.com/v2",
      "description": "Sandbox server"
    }
  ],
  "paths": {
    "/sku/{skuId}": {
      "get": {
        "tags": [
          "sku"
        ],
        "summary": "Detail of the SKU",
        "description": "This API will return the detail of SKU. If SKU is inactive (due to out-of-stock or disabled), it will throw an error message with 200 response code",
        "operationId": "getSku",
        "parameters": [
          {
            "name": "skuId",
            "in": "path",
            "description": "SKU ID of the product returned from listSku API",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/getSkuResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "getSkuResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "description": "Constant jsonrpc version 2.0"
          },
          "id": {
            "type": "string",
            "description": "Request ID generated by our system."
          },
          "result": {
            "type": "object",
            "description": "Contains the response payload for a particular request.",
            "properties": {
              "resourcePath": {
                "type": "string",
                "description": "Endpoint of the product used to listSku, placeOrder, validate, or topup"
              },
              "sku": {
                "type": "object",
                "description": "Object of the SKU detail",
                "properties": {
                  "sku": {
                    "type": "string",
                    "description": "Unique SKU ID of the item. Need to be passed to the placeOrder or validate and topup API."
                  },
                  "description": {
                    "type": "string",
                    "description": "Description of the SKU"
                  },
                  "countryCode": {
                    "type": "string",
                    "description": "Country of the SKU (Alpha2 format for country)"
                  },
                  "origin": {
                    "type": "string",
                    "description": "Origin of the SKU (Alpha2 format for country)"
                  },
                  "price": {
                    "type": "object",
                    "description": "price of the item charged to the client account. Need to be passed to the placeOrder or validate and topup API for price validation.",
                    "properties": {
                      "amount": {
                        "type": "number",
                        "format": "float",
                        "description": "amount to be charged to the account"
                      },
                      "currency": {
                        "type": "string",
                        "description": "currency of the amount to be charged to the account"
                      }
                    }
                  },
                  "originalPrice": {
                    "type": "object",
                    "description": "original price of the item charged to the client account before currency conversion.",
                    "properties": {
                      "amount": {
                        "type": "number",
                        "format": "float",
                        "description": "the amount of original price"
                      },
                      "currency": {
                        "type": "string",
                        "description": "the currency of original price"
                      }
                    }
                  },
                  "retailPrice": {
                    "type": "object",
                    "description": "recommended standard retail price to the end user",
                    "properties": {
                      "amount": {
                        "type": "number",
                        "format": "float",
                        "description": "amount of standard retail price of the SKU"
                      },
                      "currency": {
                        "type": "string",
                        "description": "currency of standard retail price of the SKU"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Get Prepayment Balance

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-prepayment-balance

Retrieves the current prepayment balance for a partner. This endpoint allows you to list all prepayment balances a partner holds across different countries and currencies.

```APIDOC
## GET /balance

### Description
Retrieves the current prepayment balance for a partner. This endpoint allows you to list all prepayment balances a partner holds across different countries and currencies.

### Method
GET

### Endpoint
/balance

### Query Parameters
None

### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant jsonrpc version 2.0
- **id** (string) - The request ID.
- **result** (object) - Contains the balance information.
  - **balanceList** (array) - A list of prepayment balances.
    - **country** (string) - Prepayment balance country
    - **currency** (string) - Prepayment balance currency
    - **balance** (number) - Prepayment balance remaining

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "some-id",
  "result": {
    "balanceList": [
      {
        "country": "SG",
        "currency": "SGD",
        "balance": 1000.50
      },
      {
        "country": "MY",
        "currency": "MYR",
        "balance": 500.75
      }
    ]
  }
}
```
```

--------------------------------

### POST /{product-name}

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-order-details

Retrieves the details of an order by its unique order ID using the product-specific endpoint.

```APIDOC
## POST /{product-name}

### Description
Get order detail by order Id for a specific product.

### Method
POST

### Endpoint
/{product-name}

### Parameters
#### Path Parameters
- **product-name** (string) - Required - Name of the product to purchase

#### Request Body
- **jsonrpc** (string) - Required - Constant jsonrpc version 2.0
- **id** (string) - Required - Request ID generated by client
- **method** (string) - Required - The method name
- **params** (object) - Required - Request parameters
  - **orderId** (string) - Required - The orderid returned from placeOrder. OrderID that belongs to Coda system
  - **iat** (integer) - Required - The "iat" (issued at) field indicates the token's issuance time, which must be a UNIX EPOCH timestamp in UTC and within 5 minutes of the request time.

### Request Example
{
  "jsonrpc": "2.0",
  "id": "12345",
  "method": "getOrder",
  "params": {
    "orderId": "CODA123456789",
    "iat": 1672531200
  }
}

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant jsonrpc version 2.0
- **id** (string) - Unique request ID from the client
- **result** (object) - The order result details

#### Response Example
{
  "jsonrpc": "2.0",
  "id": "12345",
  "result": {
    "status": "FULFILLED",
    "orderId": "CODA123456789",
    "items": []
  }
}
```

--------------------------------

### POST /{product-name} (listServer)

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/direct-topup-purchase

Retrieves the list of available servers for products with subtype 2. This is a required step for titles that require server selection before validation and top-up.

```APIDOC
## POST /{product-name}

### Description
Retrieves the list of servers for a specific product. This is mandatory for products where subtype = 2 to ensure the user selects the correct server before proceeding with validation and top-up.

### Method
POST

### Endpoint
/{product-name}

### Parameters
#### Path Parameters
- **product-name** (string) - Required - The name of the product to purchase.

#### Request Body
- **jsonrpc** (string) - Required - Must be set to "2.0".
- **id** (string) - Required - Unique ID generated by the client.
- **method** (string) - Required - Must be set to "listServer".
- **params** (object) - Required - Contains the request parameters.
  - **iat** (integer) - Required - UNIX EPOCH timestamp in UTC (must be within 5 minutes of request time).

### Request Example
{
  "jsonrpc": "2.0",
  "id": "12345",
  "method": "listServer",
  "params": {
    "iat": 1672531200
  }
}

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant "2.0".
- **id** (string) - Matching request ID.
- **servers** (array) - List of available servers.
  - **id** (string) - Server ID.
  - **name** (string) - Server display name.
  - **area** (string) - Optional area identifier.
  - **platform** (string) - Optional platform identifier.

#### Response Example
{
  "jsonrpc": "2.0",
  "id": "12345",
  "servers": [
    {
      "id": "srv_001",
      "name": "Server Alpha"
    }
  ]
}
```

--------------------------------

### Topup API - Final Step to Place Order (OpenAPI Specification)

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/direct-topup-purchase

This OpenAPI 3.0.3 specification defines the Topup API endpoint. It includes details on the request payload, parameters, and expected responses for topping up a user's account. The 'method' must be set to 'topup'.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "xShop API",
    "version": "2.0.0"
  },
  "tags": [
    {
      "name": "topup",
      "description": "All endpoint available for product with type = topup"
    }
  ],
  "servers": [
    {
      "url": "https://xshop.codashop.com/v2",
      "description": "Production server"
    },
    {
      "url": "https://xshop-sandbox.codashop.com/v2",
      "description": "Sandbox server"
    }
  ],
  "paths": {
    "/{product-name}": {
      "post": {
        "tags": [
          "topup"
        ],
        "summary": "Topup - Final step to place order for a topup product",
        "description": "Topup the userid based on successful validate orderid. Must submit method=\"topup\" in the payload",
        "operationId": "topUp",
        "parameters": [
          {
            "name": "product-name",
            "in": "path",
            "description": "Name of the product to purchase",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/topup"
        },
        "responses": {
          "200": {
            "description": "successful requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/topupResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "requestBodies": {
      "topup": {
        "description": "topup",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/topupBody"
            }
          }
        }
      }
    },
    "schemas": {
      "topupBody": {
        "allOf": [
          {
            "$ref": "#/components/schemas/interface"
          },
          {
            "type": "object",
            "required": [
              "method",
              "params"
            ],
            "properties": {
              "method": {
                "type": "string",
                "description": "must be 'topup'."
              },
              "usingValidateIdForTopup": {
                "type": "boolean",
                "description": "if using the same Id when submitting validate and topup request, this will speed up the response time"
              },
              "params": {
                "type": "object",
                "required": [
                  "iat",
                  "orderId",
                  "customerId",
                  "userAccount",
                  "items"
                ],
                "properties": {
                  "iat": {
                    "type": "integer",
                    "description": "The \"iat\" (issued at) field indicates the token's issuance time, which must be a UNIX EPOCH timestamp in UTC and within 5 minutes of the request time..",
                    "format": "int64"
                  },
                  "orderId": {
                    "type": "string",
                    "description": "OrderID that is generated from success validate step."
                  },
                  "customerId": {
                    "type": "string",
                    "description": "Unique customer account identifier in client’s system. They can send customer email or their internal customer unique identifier in their system."
                  },
                  "items": {
                    "type": "array",
                    "description": "Currently only support one array of item.",
                    "items": {
                      "type": "object",
                      "required": [
                        "sku",
                        "quantity",
                        "price"
                      ],
                      "properties": {
                        "sku": {
                          "type": "string",
                          "description": "SKU ID from list SKU"
                        },
                        "quantity": {
                          "type": "integer",
                          "description": "Currently only support one quantity"
                        },
                        "price": {
                          "type": "object",
                          "description": "Must match the price returned from listSKU. Will be used to do price validation, will return invalid SKU if price does not match.",
                          "required": [
                            "currency",
                            "amount"
                          ],
                          "properties": {
                            "currency": {
                              "type": "string",
                              "description": "Currency from listSKU. This will be what is charged to your account"
                            },
                            "amount": {
                              "type": "number",
                              "description": "Amount from listSKU. This will be what is charged to your account"
                            }
                          }
                        }
                      }
                    }
                  },
                  "userAccount": {
                    "oneOf": [
                      {
                        "$ref": "#/components/schemas/accountSubtypeOne"
                      },
                      {
                        "$ref": "#/components/schemas/accountSubtypeTwo"
                      },
                      {
                        "$ref": "#/components/schemas/accountSubtypeThree"
                      }
                    ]
                  }
                }
              }
            ]
          }
        ]
      },
      "interface": {
        "type": "object",
        "required": [
          "jsonrpc",
          "id"
        ],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "description": "Constant jsonrpc version 2.0"
          },
          "id": {
            "type": "string",
            "description": "Unique request ID generated by the partner. Same ID should be used in previous API method=validate call"
          }
        }
      },
      "accountSubtypeOne": {
        "type": "string"
      },
      "accountSubtypeTwo": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string"
          },
          "server": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            }
          }
        }
      },
      "accountSubtypeThree": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string"
          },
          "zoneId": {
            "type": "string"
          }
        }
      },
      "topupResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": {
            "type": "string",
            "description": "Constant jsonrpc version 2.0"
          },
          "id": {
            "type": "string",
            "description": "Unique request ID from the client"
          },
          "result": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "FULFILLED",
                  "FAILED"
                ]
              },
              "orderId": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### POST /{product-name} - List SKUs of the product

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-product-and-sku-catalogue

Retrieves a list of all SKUs for a given product, including their descriptions, prices, and retail prices. This endpoint requires a 'listSku' method in the request body.

```APIDOC
## POST /{product-name}

### Description
List all SKUs of the product with its description, price and retail price. Method must be 'listSku'.

### Method
POST

### Endpoint
`/{product-name}`

### Parameters
#### Path Parameters
- **product-name** (string) - Required - Name of the product from /products endpoint

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - Must be 'listSku'
- **params** (object) - Required
  - **iat** (integer) - Required - The "iat" (issued at) identifies the time at which the token was issued. Its value MUST be a number containing a UNIX EPOCH timestamp expressed in Coordinated Universal Time (UTC).
  - **countryCode** (string) - Optional - When present, the result will only show the SKUs belonging to the specified country code.
  - **variableRetailRate** (string) - Optional - When present, we will return additional parameters for variableRetailPrice in the specified currency. Only accepts “USD”.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "your-unique-request-id",
  "method": "listSku",
  "params": {
    "iat": 1678886400,
    "countryCode": "US",
    "variableRetailRate": "USD"
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant jsonrpc version 2.0
- **id** (string) - Request ID generated by the client
- **result** (object) - Contains the response payload
  - **skuList** (array) - List of all products available
    - **sku** (string) - Unique SKU ID
    - **description** (string) - Description of the SKU
    - **countryCode** (integer) - Country of the SKU
    - **origin** (string) - Origin of the SKU (Alpha2 format for country)
    - **price** (object)
      - **amount** (number) - Amount to be charged
      - **currency** (string) - Currency of the amount
    - **originalPrice** (object)
      - **amount** (number) - Original price amount
      - **currency** (string) - Original price currency
    - **retailPrice** (object)
      - **amount** (number) - Standard selling price amount
      - **currency** (string) - Standard selling price currency
    - **variableRetailPrice** (object) - Only returned when variableRetailRate is used
      - **amount** (number) - Converted value of the retail price
      - **currency** (string) - The variable currency used

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "your-unique-request-id",
  "result": {
    "skuList": [
      {
        "sku": "example_sku_1",
        "description": "Example Product 1",
        "countryCode": 1,
        "origin": "US",
        "price": {
          "amount": 10.00,
          "currency": "USD"
        },
        "originalPrice": {
          "amount": 10.00,
          "currency": "USD"
        },
        "retailPrice": {
          "amount": 12.00,
          "currency": "USD"
        },
        "variableRetailPrice": {
          "amount": 11.50,
          "currency": "USD"
        }
      }
    ]
  }
}
```
```

--------------------------------

### Get Order Details OpenAPI Specification

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-order-details

An OpenAPI 3.0.3 specification defining the POST /{product-name} endpoint. It details the request body structure, including the required requestId and iat fields, and the expected response schema for order status.

```json
{"openapi":"3.0.3","info":{"title":"xShop API","version":"2.0.0"},"tags":[{"name":"voucher","description":"All endpoint available for product with type = voucher / 3rd-party-voucher / coda-voucher"},{"name":"topup","description":"All endpoint available for product with type = topup"}],"servers":[{"url":"https://xshop.codashop.com/v2","description":"Production server"},{"url":"https://xshop-sandbox.codashop.com/v2","description":"Sandbox server"}],"paths":{"/{product-name}":{"post":{"tags":["voucher","topup"],"summary":"Get order detail by request Id","operationId":"getOrder","parameters":[{"name":"product-name","in":"path","description":"Name of the product to purchase","required":true,"schema":{"type":"string"}}],"requestBody":{"$ref":"#/components/requestBodies/getOrder"},"responses":{"200":{"description":"successful requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/placeOrderResponse"}}}}}}}},"components":{"requestBodies":{"getOrder":{"description":"getOrder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/getOrder"}}}}},"schemas":{"getOrder":{"allOf":[{"$ref":"#/components/schemas/interface"},{"type":"object","required":["method","params"],"properties":{"method":{"type":"string"},"params":{"required":["requestId","iat"],"properties":{"requestId":{"type":"string","description":"Unique ID from the client that is submitted on placeOrder or topup API."},"iat":{"type":"integer","description":"The \"iat\" (issued at) field indicates the token's issuance time, which must be a UNIX EPOCH timestamp in UTC and within 5 minutes of the request time.","format":"int64"}}}}}]},"interface":{"type":"object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"type":"string","description":"Constant jsonrpc version 2.0"},"id":{"type":"string","description":"Request ID generated by client"}}},"placeOrderResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","description":"Constant jsonrpc version 2.0"},"id":{"type":"string","description":"Unique request ID from the client"},"result":{"type":"object","properties":{"status":{"type":"string","enum":["FULFILLED","FAILED"]},"orderId":{"type":"string"},"items":{"description":"Only for voucher orders.","type":"array","items":{"type":"object","properties":{"sku":{"type":"string","description":"SKU ID from list SKU"},"codes":{"type":"string","description":"Voucher code"}}}}}}}}}}}
```

--------------------------------

### POST /topup

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/direct-topup-purchase

Initiates the final step of placing an order for a top-up product. This endpoint requires a 'topup' method in the payload and uses a validated order ID.

```APIDOC
## POST /{product-name}

### Description
Topup the userid based on successful validate orderid. Must submit method="topup" in the payload.

### Method
POST

### Endpoint
`/{product-name}`

### Parameters
#### Path Parameters
- **product-name** (string) - Required - Name of the product to purchase

#### Request Body
- **method** (string) - Required - Must be 'topup'.
- **usingValidateIdForTopup** (boolean) - Optional - If using the same Id when submitting validate and topup request, this will speed up the response time.
- **params** (object) - Required - Contains details for the top-up.
  - **iat** (integer) - Required - The "iat" (issued at) field indicates the token's issuance time, which must be a UNIX EPOCH timestamp in UTC and within 5 minutes of the request time.
  - **orderId** (string) - Required - OrderID that is generated from success validate step.
  - **customerId** (string) - Required - Unique customer account identifier in client’s system. They can send customer email or their internal customer unique identifier in their system.
  - **items** (array) - Required - Currently only support one array of item.
    - **sku** (string) - Required - SKU ID from list SKU.
    - **quantity** (integer) - Required - Currently only support one quantity.
    - **price** (object) - Required - Must match the price returned from listSKU. Will be used to do price validation, will return invalid SKU if price does not match.
      - **currency** (string) - Required - Currency from listSKU. This will be what is charged to your account.
      - **amount** (number) - Required - Amount from listSKU. This will be what is charged to your account.
  - **userAccount** (object | string) - Required - User account details, format depends on product subtype.

### Request Example
```json
{
  "jsonrpc": "2.0",
  "id": "request-id-123",
  "method": "topup",
  "params": {
    "usingValidateIdForTopup": false,
    "params": {
      "iat": 1678886400,
      "orderId": "ORDER-12345",
      "customerId": "cust-abc",
      "items": [
        {
          "sku": "SKU-XYZ",
          "quantity": 1,
          "price": {
            "currency": "USD",
            "amount": 10.50
          }
        }
      ],
      "userAccount": "4294967319" 
    }
  }
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant jsonrpc version 2.0
- **id** (string) - Unique request ID from the client
- **result** (object)
  - **status** (string) - Enum: FULFILLED, FAILED. Indicates the status of the top-up operation.
  - **orderId** (string) - The order ID for the top-up.

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "request-id-123",
  "result": {
    "status": "FULFILLED",
    "orderId": "ORDER-12345"
  }
}
```
```

--------------------------------

### POST /{product-name}

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/direct-topup-purchase

Validates the user ID and eligibility to purchase a specific SKU. This is a mandatory step before initiating a topup request.

```APIDOC
## POST /{product-name}

### Description
Validate the userid and eligibility to buy the skuid, required step before placing "topup" request. Must submit method="validate" in the payload.

### Method
POST

### Endpoint
/{product-name}

### Parameters
#### Path Parameters
- **product-name** (string) - Required - Name of the product to purchase

#### Request Body
- **jsonrpc** (string) - Required - Constant jsonrpc version 2.0
- **id** (string) - Required - Unique request ID generated by the partner
- **method** (string) - Required - Must be 'validate'
- **params** (object) - Required - Contains iat, customerId, userAccount, and items

### Request Example
{
  "jsonrpc": "2.0",
  "id": "12345",
  "method": "validate",
  "params": {
    "iat": 1672531200,
    "customerId": "cust_001",
    "userAccount": "user_id_123",
    "items": [
      {
        "sku": "sku_abc",
        "quantity": 1,
        "price": { "currency": "USD", "amount": 10.00 }
      }
    ]
  }
}

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant jsonrpc version 2.0
- **id** (string) - Unique request ID from the partner
- **result** (object) - Contains orderId, message, and SKU details

#### Response Example
{
  "jsonrpc": "2.0",
  "id": "12345",
  "result": {
    "orderId": "ord_98765",
    "message": {
      "username": "PlayerOne"
    }
  }
}
```

--------------------------------

### Free Fire Top-up API

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/integration-guides/sandbox-environment

Endpoint for testing Free Fire top-up flows in the sandbox environment.

```APIDOC
## POST /v2/free-fire

### Description
This endpoint facilitates testing of Free Fire top-up transactions in the Coda Payments sandbox. It requires a user account identifier to process the top-up.

### Method
POST

### Endpoint
https://xshop-sandbox.codashop.com/v2/free-fire

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **userAccount** (string) - Required - The user's account ID for Free Fire.

### Request Example
```json
{
  "userAccount": "1029384"
}
```

### Response
#### Success Response (200)
Details of the completed Free Fire top-up transaction.

#### Response Example
```json
{
  "example": "Free Fire top-up transaction details"
}
```
```

--------------------------------

### GET /sku/{skuId}

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-product-and-sku-catalogue

Retrieves the details of a specific SKU. If the SKU is inactive, the API returns an error message within a 200 response code.

```APIDOC
## GET /sku/{skuId}

### Description
This API returns the detail of a specific SKU. If the SKU is inactive (due to out-of-stock or disabled status), it will return an error message with a 200 response code.

### Method
GET

### Endpoint
https://xshop.codashop.com/v2/sku/{skuId}

### Parameters
#### Path Parameters
- **skuId** (string) - Required - SKU ID of the product returned from the listSku API.

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant jsonrpc version 2.0
- **id** (string) - Request ID generated by the system
- **result** (object) - Contains the response payload
  - **resourcePath** (string) - Endpoint of the product
  - **sku** (object) - SKU detail object containing sku, description, countryCode, origin, price, originalPrice, and retailPrice

#### Response Example
{
  "jsonrpc": "2.0",
  "id": "req-123",
  "result": {
    "resourcePath": "/sku/example-sku",
    "sku": {
      "sku": "example-sku",
      "description": "Product Description",
      "countryCode": "US",
      "origin": "US",
      "price": { "amount": 10.00, "currency": "USD" },
      "originalPrice": { "amount": 10.00, "currency": "USD" },
      "retailPrice": { "amount": 12.00, "currency": "USD" }
    }
  }
}
```

--------------------------------

### Coda API JWT Payload Sample (JSON)

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/request-header-and-authentication

Example JSON structure for the payload of a JSON Web Token (JWT) used in Coda API authentication. Contains method-specific parameters for the API call.

```json
{
  "jsonrpc": "2.0",
  "id": "12345",
  "method": "placeOrder",
  "params": {
    "items": [
      {
        "sku": "SAMPLE-SKU-0U36C",
        "quantity": 1
      }
    ],
    "customerId": "customersIdHere",
    "iat": 1524535871
  }
}
```

--------------------------------

### List all active products

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-product-and-sku-catalogue

This API will return all active Product in your account. This includes information about product type (voucher or topup), subtype, and haveRole that should be used to determine the integration flow.

```APIDOC
## GET /products

### Description
Retrieves a list of all active products available in the user's account, including details like product type, subtype, and role requirements.

### Method
GET

### Endpoint
/products

#### Query Parameters
- **countryCode** (integer) - Optional - To get a list of products originating from the ISO country code.

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **jsonrpc** (string) - Constant jsonrpc version 2.0
- **id** (string) - Unique ID generated by our system
- **result** (object) - Contains the response payload for a particular request.
  - **productList** (array) - List of all products available in xshop
    - **name** (string) - Name of the product
    - **type** (string) - Type of product (Voucher or topup) (enum: `topup`, `voucher`, `3rd-party-voucher`, `coda-voucher`)
    - **subtype** (integer) - Different subtypes require different game account information in the validate and topup response. For voucher products, this field will not be returned (enum: `null`, `1`, `2`, `3`)
    - **haveRole** (boolean) - If True, RoleId that is returned from the validate request must be selected and submitted to its topup request
    - **haveVerify** (boolean) - If True, the product has a verify method to verify the validity of game account information
    - **apiPath** (string) - The product name to be used as the endpoint. The format will be `xshop.codashop.com/v2/{apiPath}`
    - **supportedCountries** (array) - List of countries in ISO country code where the product is available
      - (integer)
    - **metadata** (object)

#### Response Example
```json
{
  "jsonrpc": "2.0",
  "id": "some-unique-id",
  "result": {
    "productList": [
      {
        "name": "MLBB Topup",
        "type": "topup",
        "subtype": 1,
        "haveRole": true,
        "haveVerify": true,
        "apiPath": "mlbb/id",
        "supportedCountries": [2011, 2024],
        "metadata": {}
      },
      {
        "name": "Steam Wallet Code",
        "type": "voucher",
        "subtype": null,
        "haveRole": false,
        "haveVerify": false,
        "apiPath": "steam/wallet",
        "supportedCountries": [2011, 2024],
        "metadata": {}
      }
    ]
  }
}
```
```

--------------------------------

### Coda API JWT Header Sample (JSON)

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/request-header-and-authentication

Example JSON structure for the header part of a JSON Web Token (JWT) used in Coda API authentication. Specifies algorithm, type, and API credentials.

```json
{
  "alg": "HS256",
  "typ": "JWT",
  "x-api-key": "{your-api-key}",
  "x-api-version": "2.0",
  "x-client-id": "{your-client-id}"
}
```

--------------------------------

### Era of Celestials Top-up API

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/integration-guides/sandbox-environment

Endpoint for testing Era of Celestials top-up flows in the sandbox environment.

```APIDOC
## POST /v2/era-of-celestials

### Description
This endpoint is designed for testing Era of Celestials top-up transactions in the Coda Payments sandbox. It requires user ID and server details, and supports role checking.

### Method
POST

### Endpoint
https://xshop-sandbox.codashop.com/v2/era-of-celestials

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **userAccount** (object) - Required - Contains user identification details.
  - **userId** (string) - Required - The user's unique ID.
  - **server** (object) - Required - Server details.
    - **id** (string) - Required - The server ID.
    - **name** (string) - Required - The server name.

### Request Example
```json
{
  "userAccount": {
    "userId": "1029384",
    "server": {
      "id": "s1",
      "name": "Server 1"
    }
  }
}
```

### Response
#### Success Response (200)
Details of the completed Era of Celestials top-up transaction.

#### Response Example
```json
{
  "example": "Era of Celestials top-up transaction details"
}
```
```

--------------------------------

### Sample User Account Structures for Coda Payments Sandbox

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/integration-guides/sandbox-environment

Provides sample JSON structures for user account identification in the Coda Payments sandbox environment. These structures vary based on the game and product type, with specific fields like 'userId', 'server', and 'zoneId' required for different top-up flows.

```json
{
    "userAccount": "1029384"
}
```

```json
{
    "userAccount": {
        "userId": "1029384",
        "server": {
            "id": "s1",
            "name": "Server 1"
        }
    }
}
```

```json
{
    "userAccount": {
        "userId": "1029384",
        "zoneId": "111"
    }
}
```

--------------------------------

### Retrieve Order Detail via OpenAPI Specification

Source: https://coda-payments.gitbook.io/coda-distribution-technical-documentation/api-references/get-order-details

This JSON snippet defines the OpenAPI 3.0.3 schema for the getOrder operation. It specifies the required parameters, including product-name in the path, and the JSON-RPC request body containing the orderId and iat timestamp.

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "xShop API",
    "version": "2.0.0"
  },
  "paths": {
    "/{product-name}": {
      "post": {
        "summary": "Get order detail by order Id",
        "operationId": "getOrder",
        "parameters": [
          {
            "name": "product-name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/getOrder" }
            }
          }
        }
      }
    }
  }
}
```