Payment

Brazil

API interface that allows the online store to process sales requisitions.

Call Details

Resource: /v2/payments
HTTP Method: POST
Request format: JSON
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`merchant_id`	Merchant code on Carat Portal. The production and certification codes will be different.	< 15 AN	YES
`merchant_key`	Merchant authentication key on Carat Portal. The production and certification keys will be different.	< 80 AN	YES
`Content-Type`	It must be sent with the value `application/json`.	= 15 AN	YES
`idempotency_key`	It's like a random code (identifier), with up to 80 characters, created by the integrator that will use the Carat API.	< 80 N	YES

Examples

Request:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: ************' \
--header 'merchant_key: ************' \
--header 'idempotency_key: ************' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "121314",
    "installments": "10",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "10000",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555"
    }
}'
--verbose

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payment": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "CON",
        "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "order_id": "121314",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "14/07/2022T11:54",
        "authorization_number": "145778",
        "merchant_usn": "12050620649",
        "esitef_usn": "220714103502410",
        "sitef_usn": "145778",
        "host_usn": "999145778   ",
        "amount": "10000",
        "payment_type": "C",
        "issuer": "2",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000032",
        "payment_date": "14/07/2022T11:54",
        "standin_details": "000001",
        "cvv_result_code": "M"
    }
}

Payment using the same idempotency_key with different order_id

Request:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--header 'idempotency_key: ************' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "1657833175201",
    "installments": "10",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "10000",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555"
    }
}'

Resposta:

{
  "code": "1270",
  "message": "Idempotent transaction body does not match the original",
  "payment": {
    "status": "INV",
    "nit": "6ffad47ea1446d76160f1241f0fdca39342521df4f3f577920d9c855047fb9a2",
    "order_id": "1657833175201",
    "merchant_usn": "12050620649",
    "esitef_usn": "230912025329730",
    "amount": "10000"
  }
}

Performing pre-authorization if the idempotency key is the same as that of a payment transaction

Request:

curl --location --request POST 'https://{{url}}/e-sitef/api/v2/preauthorizations/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: **********' \
--header 'merchant_key: **********' \
--header 'idempotency_key: ************' \
--data-raw '{
    "merchant_usn": "12050620649",
    "order_id": "1657833175201",
    "installments": "10",
    "installment_type": "4",
    "authorizer_id": "2",
    "amount": "11000",
    "card": {
        "expiry_date": "1222",
        "security_code": "123",
        "number": "5555555555555555"
    }
}'

Response :

{
  "code": "1272",
  "message": "Idempotent transaction is not of the same type",
  "payment": {
    "status": "INV",
    "nit": "d081e89daa1a0e446b92ead4ed2325f860d4e1280aa4b407f32957ce17f62ee3",
    "order_id": "1657833175201",
    "merchant_usn": "12050620649",
    "esitef_usn": "230912025329774",
    "amount": "2220"
  }
}

Request parameters

The table below describes the request parameters of the transaction creation service:

Response parameters

If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the payment effectuation service:

Parameter	Description	Format
`code`	Carat Portal response code. Any code different from `0` means failure. Learn more.	< 4 N
`message`	Carat Portal response message.	< 500 AN
payment
`authorizer_code`	Authorizer response code.	< 10 AN
`authorizer_message`	Authorizer response message.	< 500 AN
`status`	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
`nit`	Identifier of the payment transaction on Carat.	= 64 AN
`order_id`	Order code sent by the merchant on the creation of the transaction.	< 40 AN
`merchant_usn`	Unique sequential number sent by the merchant on the creation of the transaction.	< 12 N
`amount`	Total price of the purchase specified by the merchant (in cents) on the creation of the transaction.	< 12 N
`sitef_usn`	Unique sequential number of the payment transaction on SiTef.	= 6 N
`esitef_usn`	Unique sequential number of the payment transaction on Carat Portal.	= 15 N
`customer_receipt`	Customer's receipt.	< 4000 AN
`merchant_receipt`	Merchant's receipt.	< 4000 AN
`authorizer_id`	Code of the authorizer used on the transaction.	< 4 N
`acquirer_id`	Code of the acquirer used on the transaction.	< 4 N
`acquirer_name`	Name of the acquirer used on the transaction.	< 100 AN
`authorizer_date`	Payment authorization date returned by the authorizer in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`authorization_number`	Authorization number.	< 6 AN
`host_usn`	Host USN.	< 15 AN
`tid`	ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef.	< 40 AN
`eci`	Eletronic Commerce Indicator (security level indicator of the payment transaction).	< 3 AN
`payment_date`	Payment authorization date on Carat Portal in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`issuer`	Issuer code returned by the authorizer.	< 5 AN
`authorizer_merchant_id`	Affiliation code of the merchant on the authorizer.	< 100 AN
`xid`	XID field returned on 3DS authentications or certain acquirers.	< 40 AN
`cavv`	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N	NO
`recurrency_tid`	First transaction's id (TID) on the card brand. Returned only if it is a recurrent payment.	< 16 AN
`terminal_id`	Terminal code used in the transaction	< 8 AN
`payment_type`	Payment type from the selected authorizer: `B` = boleto, `C` = credit, `D` = debit, `P` = Private Label credit card, `T` = bank transfer, `G` = gift card, `O` = other payment methods, `W` = Boleto NR via Web Service	= 1 AN
`standin_details`	This field provides additional information to identify whether a transaction was performed by the Stand-in on behalf of the issuer. Learn more.	< 6 AN
`cvv_result_code`	CVV result code (present only in Mastercard and Visa transactions). Values: M = Valid (match) N = Invalid (not matching) P = Not processed (issuer temporarily unavailable) U = not verified S = CVV2 must be on card	= 1 N
payment.analysis
`status`	Status of the payment transaction on Carat Portal. Learn more.	= 3 AN
`code`	Carat Portal response code. Any code different from `0` means failure. Learn more.	< 4 N
`message`	Carat Portal response message.	< 500 AN

Updated 6 days ago

Did this page help you?