Schedule activation service
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. For schedules with immediate payment, use the payment effectuation service instead.
Call details#
- Resource:
/v1/schedules/{sid} - 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 |
Examples#
Below is an example of the schedule activation service call using the cURL tool.
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Response codes
See reference on API codes - response codes
Request parameters#
The table below describes the request parameters of the schedule activation service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
authorizer_id | Code of the authorizer on Carat Portal. Learn more. If this field wasn’t sent during the transaction creation phase, it will become mandatory when consuming the schedule activation service. | < 3 N | COND. |
| card Card data. | |||
number | Customer's card number (PAN). | < 19 N | YES |
expiry_date | Card expiry date in MMYY format. Its requirement depends on the selected acquirer. In most cases, this field is mandatory. | = 4 N | COND. |
holder | Card holder name. Only mandatory for payments with e-Rede, GetNet WS and VR (SmartNet). | < 30 AN | COND. |
token | HASH of a card stored on Carat Portal. It's not allowed to send an ‘open' card number (number field) and a stored card (token field) on the same request. | = 88 AN | NO |
wallet_transaction_id | Digital wallet transaction ID. Currently, this functionality is only available to the Visa Checkout authorizer. It isn't allowed to send an ‘open' card number ( number field), a stored card (token field) and a wallet_transaction_id on the same request. | < 25 AN | NO |
Response parameters#
If successful, the response code will be 201. Any other code must be interpreted as an error. The below describes the response parameters of the schedule activation service:
| Parameter | Description | Format |
|---|---|---|
code | Carat Portal response code. Any code different from 0(zero) means failure. Learn more. | < 4 N |
message | Carat Portal response message. | < 500 AN |
| schedule | ||
status | Status of the schedule on Carat Portal. Learn more. | = 3 AN |
sid | Schedule transaction identifier on Carat Portal. | = 64 AN |
schedule_usn | Unique sequential number of the schedule on Carat Portal. | = 15 N |
authorizer_id | Code of the authorizer to be used on the scheduled payments. | = 4 N |
amount | Amount of the scheduled payments specified by the merchant (in cents) on the creation of the transaction. | < 12 N |
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 |
initial_date | Execution date of the first scheduled payment in DD/MM/YYYY format. | = 10 D |
next_date | Execution date of the next scheduled payment in DD/MM/YYYY format. | = 10 D |
number_of_times | Total quantity of scheduled payments. | < 3 N |
installments | Number of installments to be used on the scheduled payments. | < 2 N |
installment_type | Financing type to be used on the scheduled payments. | < 2 N |
soft_descriptor | Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more | < 30 AN |
show_times_invoice | For finite time schedules, send this field with value true if you want to add at the end of the soft_descriptor field the current times/number of times (e.g. Subscription 3/12). | < 5 T/F |