---
page_title: API  Standards
product: Resources
page_source: https://docs.bpl.eu5.sandbox.juspay.io/resources/docs/resources/api-standards
llms_txt: https://docs.bpl.eu5.sandbox.juspay.io/llms.txt
product_llms_txt: https://docs.bpl.eu5.sandbox.juspay.io/resources/llms.txt
---


# API Standards     




## **Global Formats** 



* **Data Format** : All requests and responses use standard **JSON** . Do not use `url-form-encryption`  unless specifically stated as required for a particular API.
* **Character Encoding** : API payloads must use  **UTF-8**  encoding to avoid broken characters.
* **Date and Time** :   Datetimes are specified in UTC (Universal Time Coordinate). Follow the industry standard **[ISO 8601 standard](https://www.iso.org/iso-8601-date-and-time-format.html)** . Example: `YYYY-MM-DDTHH:mm:ssZ`.
* **Numbers and Currencies** : Money values are passed as  `amount` and `currency` pairs. Use decimal points to represent minor units. Currencies use the 3-letter [ISO4217 standard](https://www.iso.org/iso-4217-currency-codes.html). Example: `"amount": { "value": "49.99", "currency": "GBP" }`.
* **System generated identifiers** : These are always prefixed with the usage type. Example: `order_xxxxxxx`, `cust_xxxxxx`,**tx_xxxxxx** .
* **API Versioning**  : The _major version_  is listed in the URI (Uniform Resource Identifier) path. Example: `/v1/checkout-sessions`. The _minor version_  is included in the request header. Example: `-H “Version: 1-0-2”.`


## **Naming Conventions and Case Styles** 



* **Field Casing** : All API fields use s_nake_case_ . Example: `billing_address`
* **Headers** : HTTP headers must use standard _Kebab-Case_ . Example: `X-Idempotency-Key`.
* **URL Paths** : Use lowercase nouns and plural forms for collections . Example: `/v1/checkout-sessions`.


## **Object Design Principles** 



* **Null vs. Omitted** : You can omit non-mandatory fields. For example, when creating a session you can omit the non-mandatory `billing_address` fields. Mandatory fields that are missing will throw an error. When updating a resource, you can provide a `null` value to clear a field’s current value.
* **Polymorphism** :  The API is designed to allow a single API endpoint, request, or response property to accept or return different types of data  depending on the context. For example, when creating a session, different fields are required and returned depending on the type of mode:`"mode": "payment"` or `"mode": "setup"`.
* **Metadata Fields** : Currently not available. Future releases will support open text/key-value fields to enable you to store and retrieve custom information.


## **Errors and Validation Standards** 



* **Error Envelope** : an error response returns an `ApiError` envelope. For details see [Error Codes](/resources/docs/status-and-error-codes/error-codes#Error-Codes).
* **HTTP Status Codes** : The API adopts standard HTTP Status Codes. For details, including additional status codes returned in messages, see [Status Codes](/resources/docs/status-and-error-codes/status-codes#Status-Codes).


---


---

## See Also

- [API Reference](https://docs.bpl.eu5.sandbox.juspay.io/resources/docs/resources/api-reference)