Schedule

Suggest Edits

Schedule and Schedule Edit

Brazil

Schedule Quick Start

This guide show the process of scheduling recurrent payments, using Carat Portal's REST web service interface.

What you'll need

Active account on Carat Portal's homologation environment (obtained with our support team)
A tool capable of performing HTTP calls, such as Postman, REST Client or cURL

Creating the transaction

HTTP method: POST

URL: https://<host>/e-sitef/api/v1/transactions

Headers:

Content-Type: application/json
merchant_id: {your merchant id}
merchant_key: {your merchant key}

Request:

To use this example, don't forget to define the variable {{url}} to the value of your environment host.

{
  "merchant_usn": "12055523043",
  "order_id": "12055523043",
  "authorizer_id": "2",
  "schedule": {
    "amount": "1",
    "do_payment_now": "false",
    "initial_date": "03/08/2025",
    "number_of_times": "3",
    "interval": "1",
    "soft_descriptor": "Assinatura",
    "show_times_invoice": "false"
  },
  "additional_data": {
    "payer": {
      "store_identification": "98253053045"
    }
  }
}

curl
--request POST "https://{{url}}/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"12055523043",
   "order_id":"12055523043",
   "authorizer_id":"2",
   "schedule":{
      "amount":"1",
      "do_payment_now":"false",
      "initial_date":"03/08/2025",
      "number_of_times":"3",
      "interval":"1",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   },
   "additional_data":{
      "payer":{
         "store_identification":"98253053045"
      }
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "schedule": {
    "status": "NOV",
    "sid": "<sid>",
    "amount": "1",
    "order_id": "12055523043",
    "merchant_usn": "12055523043"
  }
}

Activating the schedule

HTTP method: POST

URL: https://<host>/e-sitef/api/v1/schedules/<sid>

Replace the field in the URL above with the SID obtained in the transaction creation step.

Headers:

Content-Type: application/json
merchant_id: {your merchant id}
merchant_key: {your merchant key}

Request:

{
  "card": {
    "number": "5555555555555555",
    "expiry_date": "1222"
  }
}

curl
--request POST "https://{{url}}/e-sitef/api/v1/schedules/<sid>"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--header "Content-Type: application/json"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222"
   }
}
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "schedule": {
    "status": "ATV",
    "sid": "<sid>",
    "schedule_usn": "170713000000040",
    "amount": "1",
    "initial_date": "03/08/2025",
    "next_date": "03/08/2025",
    "number_of_times": "3",
    "soft_descriptor": "Assinatura",
    "show_times_invoice": "false"
  }
}

Checking the schedule status

HTTP method: GET

URL: https://<host>/e-sitef/api/v1/schedules/<sid>

curl
--request GET "https://{{url}}/e-sitef/api/v1/schedules/<sid>"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "schedule": {
    "status": "ATV",
    "sid": "<sid>",
    "schedule_usn": "170713000000050",
    "authorizerId": "2",
    "amount": "1",
    "initial_date": "03/08/2025",
    "next_date": "03/08/2025",
    "number_of_times": "3",
    "current_times": "0",
    "soft_descriptor": "Assinatura",
    "show_times_invoice": "false"
  }
}

Begin - Creating a Schedule Transaction

Brazil

To create a schedule transaction, the same service used to create payments must be called. Consuming this method is mandatory in the schedule flow.

Resource: /v1/transactions
HTTP Method: POST
Request format: JSON
Response format: JSON

Do Schedule - Activating a Schedule

Brazil

After creating a schedule without immediate payment and obtaining a SID, it's possible to proceed to the next step of the flow: calling the schedule activation service.

Resource: /v1/schedules/{sid}
HTTP Method: POST
Request format: JSON
Response format: JSON

Request parameters

Parameter	Description	Format	Mandatory
`authorizer_id`	Authorizer code. If not sent in transaction creation, becomes mandatory in activation.	< 3 N	COND.
`card.number`	Customer card number (PAN).	< 19 N	YES
`card.expiry_date`	Card expiry date (`MMYY`).	= 4 N	COND.
`card.holder`	Card holder name.	< 30 AN	COND.
`card.token`	HASH of stored card. Do not send with open card number.	= 88 AN	NO
`wallet_transaction_id`	Digital wallet transaction ID.	< 25 AN	NO

Response parameters

Parameter	Description	Format
`code`	Carat Portal response code. Any non-`0` means failure.	< 4 N
`message`	Carat Portal response message.	< 500 AN
`schedule.status`	Schedule status on Carat Portal.	= 3 AN
`schedule.sid`	Schedule transaction identifier.	= 64 AN
`schedule.schedule_usn`	Unique sequential number of the schedule.	= 15 N
`schedule.amount`	Amount in cents.	< 12 N
`schedule.initial_date`	First execution date (`DD/MM/YYYY`).	= 10 D
`schedule.next_date`	Next execution date (`DD/MM/YYYY`).	= 10 D
`schedule.number_of_times`	Total quantity of scheduled payments.	< 3 N
`schedule.soft_descriptor`	Additional text in card invoice.	< 30 AN
`schedule.show_times_invoice`	Adds current/total suffix when `true`.	< 5 T/F

Execution - Schedule Processing

Brazil

Daily, Carat Portal processes scheduled payments and updates execution data. Schedules that reach the configured number of executions are moved to FIN (finished).

For each recurrent payment, Carat Portal sends a POST to the merchant status URL.

Status notification of recurrent payments

curl  -X POST \
  https://dominiocadastrado.com.br \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -d 'rede=Cielo&tipoFinanciamento=4&binCartao=455182&nsuesitef=191107123456780&tid=authorizerTransactionId12345678901234567&parcelas=2&nsu=merchantNsu&autorizadora=1&nit=nitWith64charsLike1234567890123456789012345678901234567890123457&pedido=orderId1234&tipoPagamento=C&finalCartao=2345&status=NEG'

Parameter	Description	Format
`nit`	Identifier of the transaction.	= 64 A
`pedido`	Order code.	< 20 A
`nsu`	Merchant unique sequential number.	< 12 N
`status`	Transaction status.	= 3 A
`autorizadora`	Authorizer code on Carat Portal.	< 10 A
`tipoPagamento`	`C` credit, `D` debit, `B` boleto.	= 1 A
`parcelas`	Number of installments.	< 2 N
`rede`	Acquirer name.	< 500 A
`tid`	External acquirer transaction ID.	= 40 A
`binCartao`	First 6 digits of card.	= 6 N
`finalCartao`	Last 4 digits of card.	= 4 N

Important: Carat Portal can return extra parameters without previous warning. Unknown fields should be ignored.

Schedule restrictions

Sending SiTef prefixes
Payments with authentication
Payments with fraud analysis
IATA transactions
Using cards with SiTef encryption
Sending the card security code on scheduled payments

Schedule Edit Quick Start

This guide shows the process of editing a schedule, using Carat Portal's REST web service interface.

What you'll need

SID from a schedule with status ATV or INA on Carat Portal
A tool capable of performing HTTP calls, such as Postman, REST Client or cURL
An application capable of receiving POST HTTPS calls

Creating a schedule edit

HTTP method: POST

URL: https://<host>/e-sitef/api/v1/schedules/edits

Request:

{
  "sid": "<sid>",
  "merchant_data": "14114532781"
}

curl
--request POST "https://{{url}}/e-sitef/api/v1/schedules/edits"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "sid":"<sid>",
   "merchant_data":"14114532781"
}
--verbose

Receiving the authenticity POST:

@RestController
public class MyAuthenticityController {
    @PostMapping(value = "/myauthenticity", consumes = "application/x-www-form-urlencoded; charset=utf-8")
    public ResponseEntity<String> myAuthenticity(@RequestParam Map<String, String> request) {
        Log.info("seid = " + request.get("seid"));
        return new ResponseEntity<>("OK", HttpStatus.OK);
    }
}

Response:

{
  "code": "0",
  "message": "OK. Transaction successful."
}

Altering the schedule

HTTP method: PUT

URL: https://<host>/e-sitef/api/v1/schedules/edits/<seid>

{
  "status": "INA"
}

curl
--request PUT "https://{{url}}/e-sitef/api/v1/schedules/edits/<seid>"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "status":"INA"
}
--verbose

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "schedule": {
    "status": "INA",
    "amount": "1",
    "next_date": "03/08/2025",
    "number_of_times": "3",
    "current_times": "0",
    "soft_descriptor": "Assinatura",
    "show_times_invoice": "false"
  },
  "schedule_edit": {
    "status": "CON"
  }
}

Begin Edit - Creating a Schedule Edit

Brazil

Consuming this service is mandatory in the schedule editing flow. As a result, the merchant obtains a SEID for the next step.

Resource: /v1/schedules/edits
HTTP Method: POST
Request format: JSON
Response format: JSON

Request parameters

Parameter	Description	Format	Mandatory
`sid`	Identifier of the schedule to be edited.	= 64 AN	YES
`merchant_data`	Merchant data echoed in authenticity POST.	< 20 AN	NO

Authenticity POST parameters

Parameter	Description	Format
`seid`	Identifier used in edit confirmation step.	= 64 AN
`sid`	Identifier of schedule to be altered.	= 64 AN
`merchant_data`	Merchant correlation data.	< 20 AN

Response parameters

Parameter	Description	Format
`code`	Carat Portal response code. `0` means success.	< 4 N
`message`	Carat Portal response message.	< 500 AN

Edit Schedule - Altering a Schedule

Brazil

After obtaining a SEID, the merchant can edit schedule attributes.

Resource: /v1/schedules/edits/{seid}
HTTP Method: PUT
Request format: JSON
Response format: JSON

Example - editing multiple attributes

curl
--request PUT "https://{{url}}/e-sitef/api/v1/schedules/edits/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm02"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "status":"INA",
   "amount":"5555",
   "next_date":"15/07/2017",
   "installments":"2",
   "installment_type":"3",
   "soft_descriptor":"Assinatura",
   "show_times_invoice":"false",
   "card":{
      "expiry_date":"1222",
      "number":"5555555555555555"
   }
}
--verbose

Request parameters

Parameter	Description	Format	Mandatory
`status`	`ATV` to activate inactive schedule, `INA` to inactivate schedule.	= 3 AN	NO
`amount`	Amount in cents.	< 12 N	NO
`next_date`	Next execution date in `DD/MM/YYYY` (future date, day 1..28).	= 10 D	NO
`installments`	Number of installments per scheduled payment.	< 2 N	NO
`installment_type`	`3` with interest, `4` without interest / spot sale.	< 2 N	NO
`soft_descriptor`	Additional statement text.	< 30 AN	NO
`show_times_invoice`	Adds current/total suffix when `true`.	< 5 T/F	NO
`card.number`	Customer card number (PAN).	< 19 N	NO
`card.expiry_date`	Card expiry date in `MMYY`; requires card number.	= 4 N	NO

Response parameters

Parameter	Description	Format
`code`	Carat Portal response code. `0` means success.	< 4 N
`message`	Carat Portal response message.	< 500 AN
`schedule.status`	Schedule status on Carat Portal.	= 3 AN
`schedule.amount`	Scheduled payment amount.	< 12 N
`schedule.next_date`	Next execution date.	= 10 D
`schedule.number_of_times`	Total scheduled payments.	< 3 N
`schedule.current_times`	Executed scheduled payments count.	< 3 N
`schedule.installments`	Installment count.	< 2 N
`schedule.installment_type`	Financing type.	< 2 N
`schedule.soft_descriptor`	Statement descriptor.	< 30 AN
`schedule.show_times_invoice`	Current/total suffix indicator.	< 5 T/F
`schedule_edit.status`	`NOV`, `EXP`, `CON`, `INV`.	= 3 AN

Updated 6 days ago

Did this page help you?