Submit a charge

Submits a charge request

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

Environment	Endpoint Base URL
Sandbox	https://tc-api-card-sandbox.codapayments.com/v1/
Production	https://api-tc.codapayments.com/v1/

Endpoint

POST {Base URL}/direct/charges

Current Environment Availability

Environment	Is Available?
Sandbox	Yes
Production	Yes

Codapay's APIs support REST web services. By default, the endpoints displayed are RESTful.

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.
error_code	String	The error code of a failed charge. See full list of possible error codes here.
error_description	String	The error code description of a failed charge. See full list of possible error code description here.
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.
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<Object>	List of the inputs for the form

shopper_action -> form -> inputs item

Parameter Name	Data Type	Description
name	String	The value for HTML Form input name attribute
value	String	The value for HTML Form input value attribute
type	String	The value for HTML Form input type attribute