Payment with two cards service
After consuming the transaction creation service and obtaining a NIT, it's possible to proceed to the next step of the flow: calling the payment effectuation service.
This can be done by either using a single payment method (read the document "Payment effectuation service") or 2 (two) cards.
In this chapter we will write about paymets done by using 2 (two) payment methods, which we call Two cards payment.
Please contact our support team in order enable this operation in your store.
Flow#
The two card payment flow has important differences when compared to the traditional payment.
The first difference is that there will be two transactions related to a single operation and each one of them is used to effectuate the payment of one of the chosen payment methods. The first transaction is created in the Online Payment transaction initialization call and the second is created indirectly during the two card payment call.
The second difference is that some data of the first transaction is modified during the payment effectuation call. Initially the first transaction has its own amount, installments and financing type. When the two card call is done, this transaction amount is changed to the first payment method amount and the same will occur to the installments and financing type if their value is informed in the request. The second transaction will also be created with the amount, intallments and financing type informed by the second payment method in the request, but if the intallments and financing type are not present, they will inherit the values passed in the original first transaction. The sum of the first and second payment amounts must be equal to the amount in the Carat Portal intialization transaction call.
The third difference is that two card payment response is composed by each transaction response. It means that each of the transactions' responses can affect the results of the other one.
We will cover the Carat Portal predicted scenarios below.
Automatic confirmation flow#
The automatic confirmation flow for two card payment has 3 (three) stages: transactions update/initialization; payments effectuation; confirmations.
If any transaction fails, Carat Portal will not proceed to the next stage and will handle the failure as explained in the cases presented below.
Sucessful payment#
First payment fails#
When the first payment fails, the second transaction will be promptly canceled and its payment call will not be triggered to the acquirer. An issue will be registered and the merchant may contact Carat Portal's support team if they find it necessary.
Response example#
Second payment fails#
When the second payment fails, the first transaction will be undone. An issue will be registered and the merchant may contact Carat Portal's support team if they find it necessary.
Response example#
First confirmation fails#
When the first confirmation fails, the second transaction will be undone. An issue will be registered and the merchant may contact Carat Portal's support team if they find it necessary.
Response example#
Second confirmation fails#
When the second confirmation fails, the first transaction will be already confirmed. Therefore, it must be manually cancelled if the merchant finds it necessary by using either the REST cancellation call or the Merchant Web Page. An issue will be registered and the merchant may contact Carat Portal's support team if they find it necessary.
Response example#
Payment with late confirmation flow#
The payment with late confirmation flow has 2 (two) stages: transactions update/initialization; payments effectuation.
If any transaction fails, Carat Portal will not proceed to the next stage and will handle the failure as explained in the cases presented below.
Succesful payment#
First payment fails#
When the first payment fails, the second transaction will be promptly canceled and its payment call will not be triggered to the acquirer.
Response example#
Second payment fails#
When the second payment fails, the first transaction will be undone.
Response example#
Call details#
- Resource:
/v1/payments/multiple/{nit} - 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 are some examples of the payment effectuation service call using the cURL tool.
Payment#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Payment with stored card#
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 payment with multiple payment methods effectuation service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
| multiple_payment_methods[] Array of payment methods. Exactly 2 (two) payment methods must be sent. Each payment method is composed by the fields described below. | |||
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 payment effectuation service. | < 3 N | YES |
installments | Number of installments. If this field is not sent, the value informed in the Carat Portal initialization transaction request will be used. | < 2 N | NO |
installment_type | Financing type. If this field is not sent, the value informed in the Carat Portal initialization transaction request will be used. | < 2 N | NO |
amount | Amount of the purchase assigned to this payment method (in cents). | < 12 N | YES |
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. |
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 |
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. |
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 | Two card operation Carat Portal response code. Any code different from 0 means failure. Learn more. | < 4 N |
message | Two card operation Carat Portal response message. | < 500 AN |
| payments[] | Two card operation payments responses array. Each item corresponds to the response for one of the chosen payment methods. Its fields are described below. | |
code | Carat Portal response code for this payment method. Any code different from 0 means failure. Learn more.. | < 4 N |
message | Carat Portal response message for this payment method. | < 500 AN |
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 Portal. | = 64 AN |
order_id | Order code sent by the merchant on the creation of the transaction. | < 20 AN |
merchant_usn | Unique sequential number sent by the merchant on the creation of the transaction. | < 12 N |
amount | Amount of the purchase assigned to this payment method (in cents). | < 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 (security level indicator of the payment transaction via e-Commerce). | < 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 |
authentication_url | Authentication URL returned on payment with authentication flows. | < 56 AN |
balance | Current balance after payments with Gift cards. | < 12 N |
| payment.analysis | ||
code | Response code of the fraud analysis operation. | < 4 N |
message | Response message of the fraud analysis operation. | < 200 AN |
status | Status of the fraud analysis transaction on Carat Portal. This field can assume the following value:NOV – New.EXP – Expired.ACC – AcceptedREJ – RejectedREV – In reviewINV – Invalid | = 3 AN |