Payment
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 |
Examples#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Sitef Payment - Token#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Payment with later capture#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Confirmation Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Confirmation Response:
Payment without order_id#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Account validation payment - Zero Auth Dollar#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Payment - 3DS#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Payment - Network Token#
Some card brands have a tokenization solution that offers the storage of cards in safes at the brand itself, in an encrypted form. This brand tokenization is intended to improve the security and quality of the transmitted card information, which leads to possible increases in the conversion of approval by issuing banks.
| Parameter | Description | Format | Required |
|---|---|---|---|
card | |||
number | Token generated by the brand (DPAN) | ≤ 19 N | Yes |
cryptogram | Cryptogram generated by the brand | = 28 A | Yes for network token payments |
wallet_type | Field that specifies whether the transaction is processed with PAN or DPAN. You must send the value “network_token” for tokenized transactions. | AN | Yes for network token payments |
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response parameters
| Parameter | Description | Format |
|---|---|---|
card | ||
par | EMVCo introduced PAR (Payment Account Reference) to provide an industry-aligned approach designed to help link all token-based transactions associated with a specific account. | < 32 |
suffix | Last four digits of the PAN, returned by Visa and Mastercard in transactions carried out with DPAN (Network Token). | = 4 |
Response:
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:
| 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 |
Examples#
Below is an example of the payment confirmation service call using the cURL tool.
Full payment confirmation#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Payment confirmation with partial amount#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response:
Request parameters#
The table below describes the request parameters of the transaction creation service:
| Parameter | Description | Format | Mandatory | |||
|---|---|---|---|---|---|---|
merchant_usn | Unique sequential number for each order, created by the merchant. The USN will be used during the whole communication with the merchant to help identifying the order. As it is a possible access key on the merchant's side, even though it's optional to Carat Portal, it's strongly recommended that the field is formatted and sent by the merchant's application. | < 12 N | NO | |||
order_id | Order code defined by the merchant. It's advised that it is different for each order so that it becomes easier to track it. For transactions routed through the acquirer Bin, there's a 20 characters limit. | < 40 AN | YES | |||
installments | Number of installments. Send 1 for spot sales. | < 2 N | YES | |||
installment_type | Installment financing type: Value 3 = installments with interest. Value 4 = installments without interest (use this value also on spot sales). Value 6 = installments with interest (IATA). Value 7 = installments without interest (IATA). The IATA financing types are only used by companies that work with air transportation. | < 2 N | YES | |||
authorizer_id | Code of the authorizer on Carat Portal. Learn more. | < 3 N | NO | |||
amount | Total price of the purchase (in cents). Example: 1,00 = 100 or 1.100,00 = 110000 – send the value without the comma and the dots. | < 12 N | YES | |||
soft_descriptor | Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more | < 25 AN | NO | |||
| card | Card data. | |||||
number | Customer's card number (PAN). Brand generated token (DPAN) for network token payment. Learn more | < 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. | |||
security_code | Card security code. This field may not be mandatory if the company has an agreement in the contract established with the acquirers, only for payments of certain areas. However, it is possible to configure the mandatory field in the merchant settings, consult Carat support for more information. Important: a payment with schedule implies on storing the customer's card data on Carat Portal's environment. However, for security reasons, the security code cannot be stored. Therefore, the scheduled payments will always be executed without the security code. | < 5 N | COND. | |||
holder | Card holder name. | < 30 AN | NO | |||
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 | |||
cryptogram | Field that specifies whether the transaction is processed with PAN or DPAN. If “type” is empty, the default value is PAN (non-tokenized card number). If there is a tokenized transaction, you must send the value “network_token”. | AN | NO | |||
wallet_type | Field that specifies whether the transaction is processed with PAN or DPAN. If “type” is empty, the default value is PAN (non-tokenized card number). If there is a tokenized transaction, you must send the value “network_token”. | AN | NO | |||
| external_authentication | This element receives MPI authentication result fields. | |||||
eci | Eletronic Commerce Indicator – Card holder authentication security level indicator. | < 3 N | NO | |||
xid | External card holder authentication transaction id. | < 40 N | NO | |||
cavv | Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data. | < 40 N | NO | |||
| iata | This element contains specific fields for IATA transactions. | |||||
departure_tax | Departure tax in cents. | < 12 N | YES only for installment_type = 6 or 7 | |||
| acquirer | Data required only to specific acquirers / routings. | |||||
financing_plan | Financing Plan code used for Via Certa Financiadora routed payments, only in case of installments plan with interest. | < 4 N | NO | |||
special_code | Conductor/Renner SiTef routings general use code. | < 6 N | NO | |||
mid | Acquirer merchant code - For BIN routings, the MID to be used by the merchant is unique. This field must be used if it is necessary to select a MID other than the default one. | < 15 AN | COND | |||
recurrency | Flag that defines whether or not the payment is recurring. Accepted all routings via SiTef | < 5 T/F | NO | |||
recurrency_tid | First transaction's TID. This field tells the first and the subsequent transactions apart. Use only if it is a recurrent payment. | < 16 AN | NO | |||
recurrency_original_amount | Original value of the transaction that started the recurrency. This value must be informed in all subsequent recurrences. Used only for recurrence. Field used only in BIN routing, mandatory when recurrence | < 18 AN | NO | |||
product_code | Product code. It is mandatory in routing via Marisa. | < 6 N | COND. | |||
terminal | Sitef terminal code. In absence Carat Portal will generate a random terminal code. | = 14 N | No | |||
company_code | Sitef company code. In absence Carat Portal will use company code from merchant configuration. | = 8 N | No | |||
authorization_number | Authorization number. Mandatory for Bradescard Voucher authorizer. | < 6 AN | COND. | |||
| acquirer.vouchers_filter[] | Choice of vouchers that will not be accepted. Options of "Vouchers": 01 - Food, 02 - Meal, 03 - Culture, 04 - Fuel, 05 - Benefit. Example: You do not want to accept Vouchers: Culture, Fuel, Benefit. You must send: "vouchers_filter": ["03", "04", "05"] | |||||
| acquirer.prefixes | Element for sending SiTef prefixes, like CICLOS, CPLANO and VLRADD. If the prefix that was sent is not supported by card, Carat Portal will invalidate the transaction, preventing that a false impression of the use of a functionality is given. Example: { "key" : "value" } -> { "CICLO" : "01" } | |||||
key | Prefix name. | < 1024 AN | NO | |||
value | Prefix value. | < 1024 AN | NO | |||
| acquirer.submerchant_split[] | It consists of an array for split payments, unique to BIN and Sipag routing, both via SiTef. It allows the division of parts of the total amount of the payment among other merchants. The maximum number of items allowed in this array is 5 items. | |||||
submerchant_code | BIN/Sipag merchant code | < 51 AN | NO | |||
submerchant_amount | Transaction amount related to the merchant | < 12 N | NO | |||
| acquirer.card_on_file | It is intended for sending specific information such as card storage authorization, confirming that the cardholder has authorized the storage of the card. Learn more. | |||||
usage | Identifies the usage. For instance, in case of storage authorization: authorized | < 11 AN | NO | |||
reason | Itentifies the reason. For instance, in case of storage authorization: card | < 11 AN | NO | |||
| WARNING: The | ||||||
| additional_data | Element for sending additional data. | |||||
postpone_confirmation | This field must be sent with value true if a payment with late confirmation is desired. | < 5 T/F | NO | |||
visitor_id | Visitor identifier obtained using Konduto's JavaScript | < 40 AN | NO | |||
description | Product description | < 100 AN | NO | |||
discount_amount | Discount amount of the product in cents | < 10 N | NO | |||
discount_info | Discount information. | < 500 AN | NO | |||
sku | Item product code | < 100 AN | NO | |||
creation_date | Indicates the date of publication of the product on the merchant's site (Format: DD/MM/YYYY) | = 10 AN | NO | |||
| additional_data.payer | Element for sending data related to the payer. | |||||
name | Customer name | < 100 AN | YES | |||
surname | Customer surname | < 100 AN | YES | |||
email | Customer e-mail | < 100 AN | YES | |||
born_date | Customer birth date (format : YYYY-MM-DDTHH:MM:SS) | = 19 AN | NO | |||
identification_number | Customer document number | < 100 AN | NO | |||
creation_date | Account creation date on the site (format: DD/MM/YYYY ) | = 10 AN | NO | |||
is_new_client | Boolean that indicates if the customer is using a recently created account in this purchase | < 5 T/F | NO | |||
is_vip_client | Boolean that indicates if the customer is VIP or a frequent buyer | < 5 T/F | NO | |||
| additional_data.merchant | Element for sending data related to the merchant. | |||||
email | Merchant's e-mail address. | < 1024 AN | NO | |||
additional_data.passengers[] | Passengers information | |||||
name | Passenger first name | < 100 AN | YES | |||
last_name | Passenger last name | < 100 AN | YES | |||
legal_document | Passenger document | < 100 AN | YES | |||
legal_document_type | Passenger document type (5 = passport, any other number = id) | < 8 AN | YES | |||
birth_date | Passenger birth date (format: YYYY-MM-DDTHH:MM:SS) | < 17 AN | NO | |||
nationality | Passenger nationality, following ISO 3166-1 alfa-3 | = 3 AN | NO | |||
is_frequent_traveler | Frequent traveler boolean | < 5 T/F | NO | |||
is_with_special_needs | Boolean which indicates if it's a passenger with special needs | < 5 T/F | NO | |||
frequent_flyer_card | Loyalty program type | < 255 AN | NO | |||
customer_class | Loyalty program category | < 255 AN | NO | |||
additional_data.hotel_reservations[] | Hotel reservation information | |||||
hotel | Hotel name | < 100 AN | YES | |||
category | Hotel category | < 100 AN | NO | |||
additional_data.hotel_reservations[].address | Hotel address information | |||||
street_name | Hotel street name | < 255 AN | NO | |||
street_number | Hotel street number | < 255 AN | NO | |||
complement | Hotel address complement | < 100 AN | NO | |||
city | Hotel city | < 100 AN | NO | |||
state | Hotel state | < 100 AN | NO | |||
zip_code | Hotel zip code | < 100 AN | NO | |||
country | Hotel country code, following ISO 3166-1 alfa-3 | = 3 AN | NO | |||
additional_data.hotel_reservations[].rooms[] | Hotel rooms information | |||||
number | Room number | < 100 AN | NO | |||
code | Room code | < 100 AN | NO | |||
type | Room type | < 100 AN | NO | |||
check_in_date | Check-in date and time (format: YYYY-MM-DDTHH:MM:SS) | < 17 AN | YES | |||
check_out_date | Check-out date and time (format: YYYY-MM-DDTHH:MM:SS) | < 17 AN | NO | |||
number_of_guests | Number of guests | < 9999 N | NO | |||
board_basis | Feeding regime | < 100 AN | NO | |||
additional_data.hotel_reservations[].rooms[].guests[] | Hotel room guests information | |||||
name | Guest name | < 100 AN | YES | |||
document | Guest document | < 8 AN | NO | |||
document_type | Guest document type:
| < 8 AN | NO | |||
birth_date | Guest birth date (format: YYYY-MM-DDTHH:MM:SS) | < 17 AN | NO | |||
nationality | Guest nationality, following ISO 3166-1 alfa-3 | = 3 AN | ||||
additional_data.events[] | Event information | |||||
name | Event name | < 255 AN | YES | |||
date | Event date and time (format YYYY-MM-DDTHH:MM:SS) | < 17 AN | YES | |||
type | Event type:
| < 9 AN | YES | |||
subtype | Event type details | < 255 AN | NO | |||
additional_data.events[].venue | Event venue information | |||||
name | Venue name | < 255 AN | NO | |||
street_name | Venue street name | < 255 AN | NO | |||
street_number | Venue street number | < 255 AN | NO | |||
city | Venue city | < 255 AN | NO | |||
state | Venue state | < 255 AN | NO | |||
country | Venue country code, following ISO 3166-1 alfa-3 | = 3 AN | NO | |||
capacity | Venue capacity | < 255 AN | NO | |||
additional_data.events[].tickets[] | Event tickets information | |||||
id | Unique ticket identifier | < 255 AN | NO | |||
category | Ticket category:
| < 10 AN | YES | |||
section | Ticket section | < 255 AN | NO | |||
premium | Premium ticket indicator | < 5 T/F | NO | |||
additional_data.events[].tickets[].attendee | Event attendee information | |||||
name | Attendee name | < 255 AN | NO | |||
document | Attendee document | < 100 AN | YES | |||
document_type | Attendee document type:
| < 100 AN | NO | |||
birth_date | Attendee birth date (format: YYYY-MM-DDTHH:MM:SS) | < 17 AN | NO | |||
| additional_data.shipment.receiver_address | ||||||
street_name | Shipment address street name. | < 255 AN | NO | |||
street_number | Shipment address street number. | < 15 AN | NO | |||
complement | Shipment address complement. | < 50 AN | NO | |||
zip_code | Shipment zip code. E.G.: 21241-140. | < 9 AN | NO | |||
city | Shipment city. | < 50 AN | NO | |||
state | Shipment state. | = 2 AN | NO | |||
country | Shipment country, following ISO 3166-1. E.G.: BRA | = 3 AN | NO | |||
| additional_data.browser | ||||||
email | Email registered in the customer's browser. | < 100 AN | NO | |||
host_name | Host name where the customer was before entering the store's website. | < 60 AN | NO | |||
| additional_data.items[] | ||||||
title | Product name. | < 255 AN | NO | |||
quantity | Quantity of the product to be acquired. | < 15 N | NO | |||
id | Product identifier. | < 255 AN | NO | |||
unit_price | Unit price of the product. | < 15 N | NO | |||
| additional_data.items[].passenger | ||||||
email | Passenger email. | < 255 AN | NO | |||
legal_document | Id of the passenger to whom the ticket was issued. | < 32 AN | NO | |||
name | Passenger name. | < 120 AN | NO | |||
customer_class | Classification of the Airline. Values such as Gold or Platinum can be used. | < 32 AN | NO | |||
| additional_data.items[].passenger.phone | ||||||
ddi | Passenger phone IDD. | < 3 N | NO | |||
ddd | Passenger phone DDD. | < 3 N | NO | |||
number | Passenger phone number. | < 9 N | NO | |||
| additional_data.shipment | ||||||
name | Delivery recipient name. | < 255 AN | NO | |||
method | Type of product delivery service. Allowed values:SAME_DAY – Delivery on the same day.ONE_DAY – Delivery overnight or on the next day.TWO_DAY – Delivery in two days.THREE_DAY – Delivery in three days.LOW_COST – Low cost delivery service.PICKUP – Product to be picked up in the store.OTHER – Other method.NONE – No delivery service, as it is a service or subscription. | < 9 AN | NO | |||
| additional_data.shipment.phones[] | ||||||
ddi | Addressee phone IDD. | < 3 N | NO | |||
ddd | Addressee phone DDD. | < 3 N | NO | |||
number | Addressee phone number. | < 9 N | NO | |||
additional_data.connections[] | Travel connections information | |||||
journey_type |
| < 7 AN | YES | |||
origin_city | Origin city | < 100 AN | YES, if transport_type=bus | |||
destination_city | Destination city | < 100 AN | YES, se transport_type=bus | |||
from | IATA airport code of the origin airport | = 3 AN | ||||
to | IATA airport code of the destination airport | = 3 AN | YES, if transport_type=flight | |||
departure_date | Departure date and time (format: YYYY-MM-DDTHH:MM:SS) | < 17 AN | YES | |||
class | Seat class name (Ex: economy, business or first) | < 8 AN | NO | |||
class_code | Seat class code | < 20 AN | NO | |||
company | Airline name | < 20 AN | NO | |||
additional_data.billing_data.address | Billing address information | |||||
street_name | Billing street name | < 255 AN | NO | |||
street_number | Billing street number | < 255 AN | NO | |||
complement | Billing address complement | < 100 AN | NO | |||
city | Billing city | < 100 AN | NO | |||
state | Billing state | < 100 AN | NO | |||
zip_code | Billing zip code | < 100 AN | NO | |||
country | Billing country code, following ISO 3166-1 alfa-3 | = 3 AN | NO | |||
additional_data.travel | Travel information | |||||
transport_type | Travel transport type (flight or bus) | < 6 AN | YES | |||
expiration_date | Expiration date (format: DD/MM/YYYY ) | = 10 AN | NO | |||
The table below describes the additional parameters that must be sent on a payment with fraud analysis :
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
| additional_data | |||
anti_fraud_institution | Institution that will carry out the fraud analysis to the merchant. It must be send with the value AUTHORIZER. | = 10 AN | YES para análise de fraude |
anti_fraud | Enables the fraud analysis service. Allowed values:enabled_before_auth – fraud analysis will be done BEFORE the payment authorization. If the analysis is rejected, the payment won't be initiated.enabled_after_auth – fraud analysis will be done AFTER the payment authorization. If the analysis is rejected, the payment will be cancelled. | < 19 AN | YES para análise de fraude |
journey_type | Type of the trip. Allowed values:ROUND_TRIP – round trip.OUTWARD – outward.RETURN – return. | < 10 AN | NO |
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. | < 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 |
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 |
| 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 |
Card-On-File Parameters#
Card on File refers to transactions that involve storing credit card information for future use. These transactions indicate that a card has been securely stored in a system, allowing it to be used later without having to re-enter card details. The option to store the card offers users convenience by allowing them to quickly and easily make payments on future transactions. Furthermore, storing card information can also be used by card issuers for risk analysis and fraud prevention, improving transaction security and increasing the conversion rate.
For Card on File operations, the following parameters must be sent:
| acquirer.card_on_file | ||
|---|---|---|
usage | Identifies the use | - authorized - first - subsequent |
reason | Identify the reason | - card - recurring - cardholder - unscheduled |
Note:
usageandreasonare complementary information and therefore it is possible to consult all valid combinations with usage details below.
Definitions#
The following values are accepted for parameters usagee reason, inside of acquirer.card_on_file:
usage | Definition |
|---|---|
first | Indicate the first ocurrency |
subsequent | Indicates that the payment will be made with a previously stored card |
authorized | To be used together reason=card parameter indicating that the card holder has authorized the card storage |
reason | Definition |
|---|---|
cardholder | Subsequent purchases triggered by the cardholder |
unscheduled | Subsequent purchases without scheduling |
recurring | Scheduled recurrent purchases |
installment | Instalment thru recurrency |
card | To be used together usage=authorized parameter indicating that the card holder has authorized the card storage |
MIT e CIT#
There are two types of card-on-file transactions: CIT (Cardholder Initiated Transaction) and MIT (Merchant Initiated Transaction)
| Sigla | Definition |
|---|---|
| CIT | is any transaction where the cardholder is actively participating in the transaction, either at a terminal in-store or through a checkout experience online. |
| MIT | is a subsequent transaction with already-stored credentials, for which a cardholder has given prior consent to the merchant to store payment credentials for future use, without his or her active engagement. Such would be the case in the automatic billing for subscription services, to name one example. |
Valid combinations#
usage | reason | Definition | MIT/CIT? |
|---|---|---|---|
authorized | card | Indicates that the user has authorized the storage of the card when making a payment or zero dollar validation. | CIT |
first | unscheduled | Indicates a single payment | MIT |
first | recurring | Indicates the first the first occurrence of a recurrence | MIT |
subsequent | recurring | Indicates subsequent occurrences of a recurrence | MIT |
subsequent | cardholder | Indicates a payment made by the user with the card already stored | CIT |
subsequent | unscheduled | Indicates a subsequent unscheduled occurrence initiated by the merchant | MIT |
subsequent | installment | Indicates installment by recurrence | MIT |
Recurrency#
Recurring payments are credit card transactions that occur periodically, repeating after a certain period of time. A common example is found in subscriptions, where the buyer wants to be charged automatically, without having to re-enter credit card details for each transaction. In this type of payment, the customer previously authorizes periodic charges, establishing the conditions and the time interval between transactions. This provides convenience for both the buyer, who doesn't have to worry about making repeated payments manually, and the seller, who maintains a constant source of income.
For recurrency operations, the following parameters must be sent:
Acquirer | ||
recurrency | Indicates that this payment is part of a recurrence | - true - false |
recurrency_tid | TID of the first transaction that caused the recurrence. | |
recurrency_original_amount | Original value of the transaction that originated the recurrence. This value must be informed in all subsequent recurrences. Required only for ELO | |
Acquirer.card_on_file | ||
usage | Identifies the usage | - first - subsequent |
reason | Identifies the reason | - recurring |
Wallet ID | DPAN/Digital Wallet |
Example#
Original request
To use this example and the others, don't forget to set the variable {{url}} to the value
sandbox.ecomm-bin.fiserv.com.br
Request:
Response:
The recurency_tid parameter from the previous request is used in all subsequent request. Also note the parameters of the card_on_file structure that change on the first request of the recurrency and on subsequent requests (second and subsequents).
First recurring payment
Request:
Response:
Recurrency subsequents request
Request:
Response:
Dynamic MCC Fields#
Can be used for both payment and REST pre-authorization transactions#
Request Parameters#
Additionally to the fields of the Payment, the fields below are used specifically in dynamic MCC transactions integrated to the bin routing:
| Parameter | Description | Format | Mandatory | |||
|---|---|---|---|---|---|---|
soft_descriptor | Personalized phrase that will be printed on the bearer's invoice. For information regarding the dynamic MCC, it is equivalent to the name of the submerchant. | < 25 AN | YES | |||
| additional_data | Element for sending additional data. | |||||
mcc | Submerchant's MCC. | = 4 N | YES | |||
subacquirer_merchant_id | Submerchant's code. Deprecated field!!! Use additional_data.subacquirer_merchant.id instead. | < 15 N | NO | |||
| additional_data.subacquirer_merchant | Element for sending data related to a subacquirer's merchant. | |||||
id | Submerchant's code. | < 15 N | YES | |||
phone_number | Submerchant's phone number. | < 14 AN | NO | |||
address | Submerchant's address. | < 48 AN | NO | |||
city | Submerchant's city. | < 13 AN | NO | |||
state | Submerchant's state, in two-digit acronym format (e.g.: SP). | = 2 A | YES | |||
country | Submerchant's country. Follow the standard ISO 3166-1 alpha-2 (e.g.: BR). | = 2 A | YES | |||
zip_code | Submerchant's zip code. | < 9 AN | YES | |||
identification_number | Submerchant's CNPJ. | < 18 N | YES | |||
payment_facilitator_id | Facilitator's code. | < 11 N | YES | |||
Example#
Request:
To use this example, don't forget to define the variable {{url}} with the value
sandbox.ecomm-bin.fiserv.com.br
Response: