# Recharge Creation import ApiDoc from '../../../../../src/components/api-doc/ApiDoc'; ## Authenticity POST x signature Carat Portal has two methods of merchant authentication on the REST recharge interface: authenticity POST or signature. In the authenticity POST method, Carat Portal will send the data of the newly created recharge transaction to the registered authenticity URL of the merchant. In the signature method, the merchant must have a public RSA encryption key registered on Carat Portal and prepare a JWT signature (JSON Web Tokens) to be sent in the `Authorization` header. In this case, the recharge transaction information will be returned directly in the response. [Learn more.](autenticacao-assinatura.md) ## Call details - **Resource:** `/v3/recharge` - **HTTP Method:** `POST` - **Request format:** `JSON` - **Response format:** `JSON` - **Header parameters:** [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "h-3": "Mandatory", "0-0": "`Content-Type`", "0-1": "It must be sent with the value `application/json`.", "0-2": "= 15 AN", "0-3": "YES", "1-0": "`Authorization`", "1-1": "Merchant's signature in the `Bearer {signature}` format. Example: `Bearer JHVGytfdgauygdauiw78264284527852897hagdg`.", "1-2": "\\< 2000 AN", "1-3": "NO" }, "cols": 4, "rows": 2, "align": [ null, null, null, null ] } [/block] ## Examples Below are some examples of the recharge creation service call using the **cURL** tool. ### Creating a recharge transaction sending all parameters **Request:** To use this example, don't forget to define the variable `{{url}}` with the value
**** ```bash curl --request POST "https://{{url}}/e-sitef/v3/recharge" --header "Content-Type: application/json" --data-binary { "begin_recharge_request":{ "merchant_key":"XXXXXXXX", "merchant_usn":"2398", "order_id":"023748", "general_hash":"0000000000000000", "recharge_type":"normal" } } --verbose ``` **Response:** ``` { "begin_recharge_response":{ "esitef":{ "message":"OK. Transaction successful.", "code":"0" } } } ``` **Authenticity POST:** To use this example, don't forget to define the variable `{{url}}` with the value
**** ```bash curl -X POST \ https://dominiodaloja.com.br \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'cache-control: no-cache' \ -d 'merchantUSN=987654321&merchantId=LOJAFATURAT&orderId=123456789&nit=e009886843920c5173104557c9f6cd66b1481557fb3f4d88daca072eb8a50c97&generalHash=85E791AD85E791AD' ``` ### Creating a recharge transaction sending only the required parameters **Request:** To use this example, don't forget to define the variable `{{url}}` with the value
**** ```bash curl --request POST "https://{{url}}/e-sitef/v3/recharge" --header "Content-Type: application/json" --data-binary { "begin_recharge_request":{ "merchant_key":"XXXXXXXX" } } --verbose ``` **Response:** ``` { "begin_recharge_response":{ "esitef":{ "message":"OK. Transaction successful.", "code":"0" } } } ``` ### Creating a recharge transaction with signature **Request:** To use this example, don't forget to define the variable `{{url}}` with the value
**** ```bash curl --request POST "https://{{url}}/e-sitef/v3/recharge" --header "Content-Type: application/json" --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudF9pZCI6IkxPFGFURVNURSIsIm1lcmNoYW50X2tleSI6IkYxOURFMDAxNzdDMzAxREYyNEE4NjVGMTFBQTlCMjU2N0Y2MDQ4OTFGMEY0NEREQUVGRDY5RTMzOTlFMEI3RTEiLCJvcmRlcl9pZCI6IjEzMDE0ODU4NjYzIiwibWVyY2hhbnRfdXNuIjoiMTQ0NjY4MTAxNiIsInRpbWVzdGFtcCI6IjE2MDUzMDM1ODA5MzEifQ.JoYz8mQ8PZ8MCr5QXygbivAy2x9fvdUEGu_jSeOYF-BtSGm7ZSYWFVokyowabk1FM2NCklubb5eEB_-g9lCi1ntRQ9iqKhdldm-U8pl0V98u7Mv_hR-pcp6MHfqql0T-mhkOv1WkfYO1igck4N6EfsNu9iO126BwgvJQC456WjAUW5jgjRHboc6htvaak9NBs6yRVLNZY03cR9gKtQXMoHeXiCGeNU55_2W1SOeRJPk-OsyBzvVlZBX5RdfUjB2BOdRI7H2TDBBS-GZaMV3b2eS5_84JTySFnriCTXJ-Y1FzBnH60e4fTfAiYy1P_J-j9hyXjLYgtRu8jQd8ITfiFG3h4ZIysb4CA_lJNg_d4YuCqhBiZcpculcbfXlcrcfPV-CpDytfiLz34FDWH0Q7Vlna1YuSNOKPzDIUx1MOMZO9bpwaE6Q3kClkqri92-42yeLoUKH6PUrlMpE3JrfuBelALE4ce7QzCrNjcvoqR_KVmCm6ozBjPn9qY0s7x7qe6ZLur7hNUoX79JdWGZy1-bx8dSqqpLrU0SXbMBqtvch5FvdUkktbkJpZAr7q6e0nR13_mK3RTV7adOEw03E_ocUk__rEmjGDAHMSWGmiPowu14jD1-VZ2Yf8FeoKzHYcXmIbEReTVHshk9faBICMQzMS3SXaqow4WXqULZiLTwc" --data-binary { "begin_recharge_request":{ "merchant_key":"XXXXXXXX", "merchant_usn":"1446681016", "order_id":"13014858663", "general_hash":"0000000000000000" } } --verbose ``` **Response:** ``` { "begin_recharge_response":{ "esitef":{ "message":"OK. Transaction successful.", "code":"0" }, "nit": "jhadafsafhjhasdfghiyuw43u8785345jksjknsmnnsjkfkiu34u98ynksnn3535", "merchant_id": "XXXXXXXX", "order_id": "13014858663", "merchant_usn": "1446681016", "general_hash": "AF32810AAF32810A" } } ``` ## Request parameters The table below describes the request parameters of the recharge creation service: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "h-3": "Mandatory", "0-0": "`merchant_key`", "0-1": "Merchant key registered on Carat Portal", "0-2": "\\< 80 A", "0-3": "YES", "1-0": "`merchant_usn`", "1-1": "Unique sequential number generated by the merchant", "1-2": "\\< 12 N", "1-3": "NO", "2-0": "`order_id`", "2-1": "Order identification code generated by the merchant", "2-2": "\\< 20 AN", "2-3": "NO", "3-0": "`general_hash`", "3-1": "Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others).

If the store hadn't performed a recharge previously or hadn't saved a previously received value from Carat Portal, the value: `0000000000000000` can be passed to Carat Portal. If the `general_hash` is not sent, the store will be obliged to make all queries to obtain the data necessary for the next steps of the recharge.", "3-2": "= 16 A", "3-3": "NO", "4-0": "`recharge_type`", "4-1": "Type of the recharge to be performed.

Values:
  • `normal` – Cell phone top-up
  • `others` – Recharge for other types of products, such as games PIN, donations, iUSNrance or even cell phone recharge by other modalities.
  • `invoice` – Signature invoice payment
Default value: `normal`", "4-2": "= 6 A", "4-3": "NO" }, "cols": 4, "rows": 5, "align": [ null, null, "center", "center" ] } [/block] ## Response parameters In case of success, the HTTP response code will be `200`. Any other code must be interpreted as an error. The table below describes de response parameters of the recharge creation service: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "0-0": "`nit`", "0-1": "Identification of the recharge transaction on Carat Portal", "0-2": "= 64 AN", "1-0": "`merchant_id`", "1-1": "Merchant ID on Carat Portal", "1-2": "\\< 15 AN", "2-0": "`order_id`", "2-1": "Order code generated by the merchant", "2-2": "\\< 20 AN", "3-0": "`merchant_usn`", "3-1": "Unique sequential number generated by the merchant", "3-2": "\\< 12 N", "4-0": "`general_hash`", "4-1": "Identification code of the table with the data related to the recharges (carriers, subsidiaries, ranges of values, validity of credits, among others).", "4-2": "= 16 AN", "5-0": "**esitef** Element that describes Carat Portal's response.", "5-1": "", "5-2": "", "6-0": "`code`", "6-1": "Carat Portal response code. Any code different from `0`(zero) means failure. [Learn more.](codigos-da-api.md#response-codes)", "6-2": "\\< 4 N", "7-0": "`message`", "7-1": "Carat Portal response message.", "7-2": "\\< 500 AN" }, "cols": 3, "rows": 8, "align": [ null, null, "center" ] } [/block] ## Authenticity POST parameters The table below describes the parameters sent by Carat Portal on the authenticity POST: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "0-0": "`nit`", "0-1": "Identifier of the cancel transaction to be used in the next step of the flow.", "0-2": "= 64 AN", "1-0": "`merchantId`", "1-1": "Merchant code on Carat Portal.", "1-2": "\\< 15 AN", "2-0": "`orderId`", "2-1": "Order ID of the payment created by merchant", "2-2": "\\< 20 AN", "3-0": "`merchantUSN`", "3-1": "USN generated by the merchant for the payment", "3-2": "\\< 12 N", "4-0": "`generalHash`", "4-1": "Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others).", "4-2": "= 16 AN" }, "cols": 3, "rows": 5, "align": [ null, null, "center" ] } [/block] Carat Portal can also send new parameters without previous warning, which means that the merchant’s application must be prepared to receive extra fields and just ignore them. ## Parameters sent by Carat Portal on HTTPS POST > **Important:** > > Carat Portal uses the `x-www-form-urlencoded` media type to send the HTTPS POST. Therefore, the server must accept this type of media on the merchant's registered URL to receive POST HTTPS. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "h-2": "Format", "0-0": "`nit`", "0-1": "Identification of the recharge transaction on Carat Portal", "0-2": "= 64 AN", "1-0": "`merchantId`", "1-1": "Merchant ID on Carat Portal", "1-2": "\\< 15 AN", "2-0": "`orderId`", "2-1": "Order code generated by the merchant", "2-2": "\\< 20 AN", "3-0": "`merchantUSN`", "3-1": "Unique sequential number generated by the merchant", "3-2": "\\< 12 N", "4-0": "`generalHash`", "4-1": "Identification code of the table with the data related to the recharges (carriers, subsidiaries, ranges of values, validity of credits, among others).", "4-2": "= 16 AN" }, "cols": 3, "rows": 5, "align": [ null, null, "center" ] } [/block]