Payment confirmation service

After creating and authorizing a payment pending confirmation, the merchant must call the confirmation service to confirm or undo the payment using the same NIT obtained on the first step of the flow.

Call details#

  • Resource: /v1/payments/{nit}
  • HTTP Method: PUT
  • Request format: query string
  • Response format: JSON
  • Header parameters:
merchant_idMerchant code on Carat Portal. The production and certification codes will be different.< 15 ANYES
merchant_keyMerchant authentication key on Carat Portal. The production and certification keys will be different.< 80 ANYES


Below is an example of the payment confirmation service call using the cURL tool.


To use this example, don't forget to define the variable {{url}} with the value

--request PUT "https://{{url}}/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr?confirm=true"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"


"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"status": "CON"

Response codes

See reference on API codes - response codes

Request parameters#

The table below describes the request parameters of the payment confirmation service:

confirmThis field must be sent with the value true if you want to confirm the transaction, or false, if you want to undo it.< 5 T/FYES
amountAmount to be captured. It must be less than or equal to the authorized amount. Partial confirmations are only supported by non-SiTef routings. If this field is not sent, the total transaction amount is used.< 12 NNO

Response parameters#

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

codeCarat Portal response code. Any code different from 0 means failure. Learn more.< 4 N
messageCarat Portal response message.< 500 AN
statusStatus of the payment transaction on Carat Portal. Learn more.= 3 AN
host_usnHost USN.< 15 AN
payment_datePayment authorization date on Carat Portal in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03= 16 D