Multiple transaction payment service
The Multiple Transaction Payment is a feature aimed at merchants selling a third party product/service. Allowing, through a single request, the separation of the main value and the product / service, so that the amount is directly allocated to the establishments involved.
The total value of any sale is divided into N parts and sent (via POST/HTML) to N distinct companies (N distinct merchantId's) defined by the web application and duly registered with Carat Portal.
Example: Taking as an example a sale of $ 100 we can make a single request to send the amount of $60 to the manufacturer of the main product, $ 20 to the manufacturer of an accessory and $20 to the service provider.
Carat Portal Interfaces Supported for Multiple Transaction Payment Integration#
The interface used is POST HTML with JSON.
You can use the following interfaces for integration with Multiple transaction payment:
- HTML 2.0 Payment Interface (document “HTML Payment”)
- WS Interface Cancellation 2 (document “REST Cancellation”).
Note: If the store is starting the first integration with Carat Portal, integration via HTML Payment is recommended as it offers a better user experience and an interface more modern for integration with the store system.
Carat Portal Features NOT Allowed for Multiple Transaction Payment Integration#
Carat Portal does not allow integration (in the same transaction) between a Multiple transaction payment and the following Carat Portal features:
- Manual risk analysis transaction (where HTML payment is pending verification
by the store while doing the separate risk analysis of Carat Portal);
- Prepaid Mobile Credit Recharge Transaction associated with the payment;
- Card storage during payment.
Required Settings in Carat Portal#
The merchant who wants to make Multiple transaction payments must ask the registration team to enable permission for this payment type.
Parameters Used to Make a Multiple Transaction Payment#
In making Multiple transaction payments, the POST parameters below have the following concepts:
| Parameter | Description | Size | Mandatory |
|---|---|---|---|
amount * | The total payment amount must be sent, ie the amount of the main transaction plus the others. | <= 1024 N | YES |
installments ** | Will be used for all secondary transactions. The main transaction will always be in sight. | <= 1024 N | YES |
(*) Carat Portal will validate the values with the total sent (amount). Should any difference occur, the transaction will be invalidated.
(**) In case of payment in installments, the main transaction will always be cash and the secondary transactions will be split, with the same number of installments between them.
Secondary transactions are all transactions linked to the primary transaction. For requisition, it is possible to have a maximum of 16 (sixteen) secondary transactions. The greater the number of transactions sent, the longer the response delay due to the increased processing of multiple transactions.
If a problem occurs during the complete Multiple Transaction Payment flow, Carat Portal will undo all approved transactions from that Payment Flow. Ex .: The application performed a payment flow containing 3 merchantId's, the 1st merchantId transaction was approved, but the 2nd merchantId transaction was denied. Since in the payment flow an error occurred in the second transaction (status = NEG), Carat Portal will undo the first (status = PPN) and negate the flow completely, returning NEG also for the third transaction, even if no payment attempt has been made. In cases where Carat Portal denies one of the transactions, in addition to the behavior described above (deny all transactions), the message “Denied Split” in the “Message” field appears in the transaction report (Merchant Portal).
The JSON parameters below have the following concepts:
ADDITIONAL_DATA (additional_data)#
| Parameter | Description | Size | Mandatory |
|---|---|---|---|
| method | Used to perform a differentiated transaction. If you want to make a SPLIT transaction, this field should be spelled SPLIT. | <= 1024 A | YES |
| extra_amount | Will be used to receive principal transaction amount | <= 1024 N | YES |
INNER_TRANSACTIONS (inner_transactions)#
| Parameter | Description | Size | Mandatory |
|---|---|---|---|
| merchant_id | Store code in Carat Portal to be used for each secondary transaction. | <= 1024 A | YES |
| amount | The total payment amount of each secondary transaction must be sent, always respecting the limit of the total payment amount. | <= 1024 N | YES |
| order_id | Store order code to be used for each secondary transaction. | <= 1024 A | NO |
| merchant_usn | Store sequential number to use for each secondary transaction. | <= 1024 A | NO |
IMPORTANT 1: Authorizers configured from a secondary store must be the same as those configured at the store submitted in the primary transaction. However, there are no impediments to routing being different between stores. Example: Store 1 set up with Visa and acquiring network Cielo, Store 2 set up with Visa and acquiring rede, Rede is a valid scenario.
IMPORTANT 2: If any of the transactions are denied for any reason (communication failure, insufficient balance, etc.), the default behavior is to undo/deny all transactions involved. The functionality was developed with the premise of committing all or denying all transactions.
Status Notification#
The status notification sent by Carat Portal to the store status notification URL has an additional field for Split transactions.
| Parameter | Description | Size |
|---|---|---|
| NITTransacaoSecundaria | Field composed of merchantIds and NITs of secondary transactions, in the format (merchantId1:nit1|merchantId2:nit2) | <= 1296 A |
The field NITTransacaoSecundaria is sent in the main transaction status notification, indicating the NIT's of the secondary transactions and thus allowing the status of all of them to be queried.
NITTransacaoSecundaria field example for 2 secondary transactions:
NITTransacaoSecundaria=LOJATESTE:95f386518449f6be6b4d25449989b5cee7736eb93ce96901ea2338a76fd01ad8|LOJATESTE2:95f386518449f6bea6fed3e03f7326fbe7736eb93ce96901dc1d6fba16d8f011
Calling Examples#
Example call with Carat Portal transaction parameters + Multiple Transaction payment data in JSON format for HTML Payment: