> 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/codapay/direct-api-integration/direct-api-integration-for-cards/submit-a-charge.md).
# Submit a charge
### Pre-requisite
When integrating with Codapay's API, ensure you adhere to the following standards:
1. Use HTTPS protocol.
2. TLS 1.2 or higher
3. Include an Authorization header, API Key, and Partner ID
### Reference
#### Endpoint
**POST**** {Base URL}/direct/charges**
#### Current Environment Availability
Environment
Is Available?
Sandbox
Yes
Production
Yes
{% hint style="info" %}
Codapay's APIs support REST web services. By default, the endpoints displayed are RESTful.
{% endhint %}
### Request Parameters
| Parameter Name | Data Type | Description | Constraint | Is Required ? |
| --------------------- | ----------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| item\_code | String | Code of the item involved in the charge |
| No |
| item\_name | String | Name of the item involved in the charge |
| No |
| amount\_value | String | The amount value of the charge | Must be in the smallest currency unit (cents, unit, …). | Yes |
| amount\_currency | String | The currency of the charge | Must be a valid ISO-4217 currency code. We currently only support local currency (LCY) transactions for the corresponding local country. Cross-currency transactions (e.g. USD for non-US countries) are not supported at the moment. | Yes |
| partner\_reference | String | Unique identifier provided by the partner for the charge |
| Yes |
| shopper\_agent | JSON Object | A Shopper Agent client object that contains data related to the shopper environment | Must be a valid JSON format | Yes |
| setting | JSON Object | A JSON object that contains setting details like default language and webhook\_url | Must be a valid JSON format | Yes |
| payment\_method | JSON Object | A JSON Object of payment method | Must be in a valid JSON format | Yes |
| partner\_custom\_data | JSON Object | Custom data provided by the partner, stored and returned as part of the charge object | Must be in a valid JSON format | No |
| tax | JSON Object | A JSON Object that contains tax information for this payment request | Must be in a valid JSON format | Yes |
\
Please find more information about the JSON Objects below:
**shopper\_agent**
Parameter Name
Data Type
Description
Constraint
Is Required?
ip_address
String
The IP address of the shopper
Must be in IPV4 format
Yes
user_agent
String
The user-agent string of the browser
Must be in user agent format
Yes
timezone
String
Timezone offset in minutes
Must be a number
Yes
screen_height
Integer
The screen height of the shopper's device
Must be a number
Yes
screen_width
Integer
The screen width of the shopper's device
Must be a number
Yes
color_depth
Integer
The color depth of the shopper's device
Must be a number
Yes
accept_header
String
The accept header sent by the shopper
Must be a valid header format (text/html)
Yes
fraud_metadata
JSON Object
The fraud metadata generated by using Coda Fraud Javascript
Must be valid JSON format
No
**shopper\_agent -> fraud\_metadata**
| Parameter Name | Data Type | Description | Constraint | Is Required? |
| -------------- | --------- | -------------------------------------- | --------------------------- | ------------ |
| fraud\_token | String | fraud token generated by Coda Fraud JS | String with maxLength = 128 | No |
**setting**
| Parameter Name | Data Type | Description | Constraint | Is Required? |
| --------------------- | ----------- | -------------------------------------------------------------------------------------------- | ---------------------------- | ------------ |
| default\_language | String | The default language setting | Must be 2 character language | Yes |
| partner\_return\_url | String | The URL where users are redirected to after successful authentication (partner return page ) | Must be a valid URL | No |
| partner\_webhook\_url | String | URL for charge notifications (authorization and capture) | Must be a valid URL | Yes |
| card | JSON Object | A JSON object that contains card setting details (ie 3DS, capture ack) | Must be valid JSON format | Yes |
**setting -> card**
| Parameter Name | Data Type | Description | Constraint | Is Required? |
| ---------------------------- | --------- | ----------------------------------------------------------------------------------------- | ------------------------------------ | ------------ |
| pre\_capture\_ack\_url | String | The URL to acknowledge pre-capture | Must be a valid URL | No |
| capture\_grace\_period | Integer | The time period for sending the capture request in seconds. By default, this is to set 0. | Must be a number. | No |
| 3ds\_challenge\_window\_size | String | The window size for the 3DS challenge | Must be in the format "WIDTHxHEIGHT" | Yes |
\
**payment\_method**
| Parameter Name | Data Type | Description | Constraint | Is Required? |
| -------------- | ----------- | ------------------------------------------------------------ | ------------------------- | ------------ |
| type | String | Type of payment method | Must be card | Yes |
| card | JSON Object | The information on the card detail | Must be valid JSON format | Yes |
| shopper | JSON Object | A JSON Object that represents shopper’s personal information | Must be valid JSON format | Yes |
\
**payment\_method -> card**
| Parameter Name | Data Type | Description | Constraint | Is Required? |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------ |
| country\_code | String |
Country code Note: US, Canada, Taiwan, and India are not supported
| Must be a valid ISO 3166-1 alpha-2 country code | Yes |
| number | String | The card number | Length must be between 15-19 | Yes |
| holder\_name | String | The cardholder name | Must be a full name | Yes |
| expiration\_month | String | The card’s expiry month | Must be a number between 1-12 | Yes |
| expiration\_year | String | The card’s expiry year | Must be a number between 00-99 | Yes |
| security\_code | String | the card's CSC/CVV/CVC | Must be 3 or 4 digits | Yes |
**payment\_method -> shopper**
| Parameter Name | Data Type | Description | Constraint | Is Required? |
| ----------------------- | --------- | --------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------- |
| partner\_shopper\_id | String | The shopper id defined by the partner of the shopper | Must be a valid string | No |
| email | String | The email address of the shopper | Must be in a valid email format | Yes |
| zip\_code | String | The zip code of the shopper | Must be a valid zip code | Conditional - required when country\_code = US or CA |
| phone\_number | String | The phone number of the shopper | Must be a valid phone number format | No |
| billing\_first\_name | String | The first name of the shopper | Must be a valid name | No |
| billing\_last\_name | String | The last name of the shopper | Must be a valid name | No |
| billing\_document\_type | String | The document type of the shopper (Passport, CPF, CNPJ, …) | Must be in a valid document format | No |
| billing\_document\_id | String | The document ID of the shopper | Must be a valid document ID format | No |
| billing\_country | String | The billing country of the shopper | Must be a valid country format | No |
| billing\_address | String | The billing address of the shopper | Must be a valid address format | No |
| billing\_region | String | The billing region of the shopper | Must be a valid region format | No |
| billing\_city | String | The billing city of the shopper | Must be a valid city format | No |
**partner\_custom\_data**
| Parameter Name | Data Type | Description | Constraint | Is Required? |
| ------------------- | --------- | ---------------------------------------------------------------------------------------- | --------------------- | ------------ |
| dynamic\_descriptor | String |
The descriptor that should appear in the end customer’s card statement
| Maximum 22 characters | No |
**tax**
| Parameter Name | Data Type | Description | Constraint | Is Required? |
| -------------- | --------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------ |
| tax\_code | String |
The tax code of the product
|
Currently the supported tax codes are
CD010001 - Digital goods: Games-Streaming / electronic download
| Yes |
### Response Parameters
The returned object is the charge object that contains a comprehensive record of your charge request, and tracking details such as the charge status throughout the checkout experience.
| Parameter Name | Data Type | Description |
| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | String | Coda’s unique identifier for the charge |
| created\_at | String | Timestamp of when the charge was created |
| status\_code | String | Status code of charge. See full list of possible statuses [here](/codapay/references/direct-api-charge-statuses.md). |
| error\_code | String | The error code of a failed charge. See full list of possible error codes [here](/codapay/references/direct-api-charge-error-codes.md). |
| error\_description | String | The error code description of a failed charge. See full list of possible error code description [here](/codapay/references/direct-api-charge-error-codes.md). |
| item\_code | String | Code of the item involved in the charge |
| item\_name | String | Name of the item involved in the charge |
| amount\_value | String | The amount value of the charge |
| amount\_currency | String | The currency of the charge |
| partner\_reference | String | Unique identifier provided by the partner for the charge |
| partner\_custom\_data | Key-Value Pair | Custom data provided by the partner, stored and returned as part of the charge object |
| shopper\_agent | JSON Object | A JSON object that contains the shopper’s browser details |
| setting | JSON Object | A JSON object that contains setting details ( ie partner\_webhook\_url) |
| payment\_method | JSON Object | A JSON Object of a payment method |
| shopper\_action | JSON Object |
A JSON object that contains the next action for shopper.
- If this field exists in the response, additional actions are required from the shopper to complete the payment (usually 3DS).
- If this field does not exist in the response, no additional action is required from the shopper.
|
Please find more information about the JSON Objects below:
**shopper\_agent**
| Parameter Name | Data Type | Description |
| -------------- | --------- | ----------------------------------------- |
| ip\_address | String | The IP address of the shopper |
| user\_agent | String | The user-agent string of the browser |
| timezone | String | Timezone offset in minutes |
| screen\_height | Integer | The screen height of the shopper's device |
| screen\_width | Integer | The screen width of the shopper's device |
| color\_depth | Integer | The color depth of the shopper's device |
| accept\_header | String | The accept header sent by the shopper |
\
**setting**
| Parameter Name | Data Type | Description |
| --------------------- | ----------- | ---------------------------------------------------------------------------- |
| default\_language | String | The default language setting |
| partner\_return\_url | String | URL for user redirection to partner page after completing 3DS authentication |
| partner\_webhook\_url | String | URL for transaction notifications (authorization and capture) |
| card | JSON Object | A JSON object that contains card setting details (ie 3DS, capture ack) |
**setting -> card**
| Parameter Name | Data Type | Description |
| ---------------------------- | --------- | -------------------------------------------------------------------------------------- |
| pre\_capture\_ack\_url | String | The URL to acknowledge pre-capture |
| capture\_grace\_period | Integer | Time period for sending the capture request in seconds. By default this is to set 0. |
| 3ds\_challenge\_window\_size | String | The window size for 3DS challenge |
**payment\_method**
| Parameter Name | Data Type | Description |
| -------------- | ----------- | ------------------------------ |
| card | JSON Object | The information of card detail |
| shopper | JSON Object | A JSON Object of a shopper |
**payment\_method -> shopper**
| Parameter Name | Data Type | Description |
| -------------- | --------- | ----------------------------------------- |
| id | String | A unique id of shopper |
| created\_at | String | Timestamp of when the shopper was created |
| status\_code | String | A status of shopper |
| email | String | The email address of the shopper |
| zip\_code | String | The zip code of shopper |
**payment\_method -> card**
| Parameter Name | Data Type | Description |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| id | String | A unique ID card |
| created\_at | String | Timestamp of when card was created |
| country\_code | String |
Must be a valid ISO 3166-1 alpha-2 country code Note: US, Canada, Taiwan, and India are not supported
|
| holder\_name | String | Holdername of the card |
| last\_four | String | The last 4 digits of card number |
| expiration\_month | String | Expire month of card |
| expiration\_year | String | Expire year of card |
**shopper\_action**
| Parameter Name | Data Type | Description |
| -------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | String | Unique identifier for shopper action |
| type | String | This will always be set to "form". It indicates that the shopper is required to complete a 3DS form. For more details on handling 3DS forms, refer to [this section](/codapay/direct-api-integration/direct-api-integration-for-cards/handling-3ds.md). |
| form | JSON Object | An object containing form details. This object contains raw materials in order to build HTML form |
**shopper\_action -> form**
| Parameter Name | Data Type | Description |
| -------------- | ------------- | ------------------------------------------------------------------------------------------------ |
| id | String | Unique identifier for form |
| method | String | HTTP method for the form that is required to submit |
| action | String | URL to indicate where the shopper should be redirected to after completing the charge operations |
| inputs | List\