e-SiTef

Payment with multiple payment methods 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) payment methods.

In this chapter we will write about paymets done by using 2 (two) payment methods, which we call Multiple payment methods payment.

Please contact our support team in order enable this operation in your store.

Flow

The multiple payment methods 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 e-SiTef transaction initialization call and the second is created indirectly during the multiple payment methods 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 multiple payment methods 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 e-SiTef intialization transaction call.

The third difference is that multiple payment methods 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 e-SiTef predicted scenarios below.

Automatic confirmation flow

The automatic confirmation flow for multiple payment methods payment has 3 (three) stages: transactions update/initialization; payments effectuation; confirmations.

If any transaction fails, e-SiTef 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 e-SiTef's support team if they find it necessary.

Response example

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "19",
            "authorizer_message": "19 Refaca Trans.",
            "status": "NEG",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25052428543",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "25/03/2020T17:24",
            "authorization_number": "080384",
            "merchant_usn": "25052428543",
            "esitef_usn": "200325048537090",
            "sitef_usn": "606060",
            "host_usn": "707070",
            "amount": "1254784",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "00000005"
        },
        {
            "status": "CAN"
        }
    ]
}

Second payment fails

When the second payment fails, the first transaction will be undone. An issue will be registered and the merchant may contact e-SiTef's support team if they find it necessary.

Response example

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25053142469",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "25/03/2020T17:31",
            "authorization_number": "252490",
            "merchant_usn": "25053142469",
            "esitef_usn": "200325048537130",
            "sitef_usn": "252490",
            "host_usn": "999252490   ",
            "amount": "100",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "25/03/2020T17:31"
        },
        {
            "authorizer_code": "255",
            "authorizer_message": "(2)Cartao invalido",
            "status": "NEG",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25053142469",
            "authorizer_id": "2",
            "acquirer_name": "REDE",
            "merchant_usn": "25053142469",
            "esitef_usn": "200325048537140"
        }
    ]
}

First confirmation fails

When the first confirmation fails, the second transaction will be undone. An issue will be registered and the merchant may contact e-SiTef's support team if they find it necessary.

Response example

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "200",
            "authorizer_message": "Function performed error-free [Cód.: 00]",
            "status": "PEN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20031345238",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "414",
            "acquirer_name": "IPG",
            "authorizer_date": "25/03/2020T17:44",
            "authorization_number": "526985",
            "merchant_usn": "20031345238",
            "esitef_usn": "200325048537170",
            "host_usn": "350815827",
            "tid": "YES80192700",
            "amount": "103",
            "payment_type": "C",
            "payment_date": "25/03/2020T17:44"
        },
        {
            "authorizer_code": "200",
            "authorizer_message": "Function performed error-free [Cód.: 00]",
            "status": "PPN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20031345238",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "414",
            "acquirer_name": "IPG",
            "authorizer_date": "25/03/2020T17:44",
            "authorization_number": "308718",
            "merchant_usn": "20031345238",
            "esitef_usn": "200325048537180",
            "host_usn": "916699212",
            "tid": "YES47652463",
            "amount": "102",
            "payment_type": "C",
            "payment_date": "25/03/2020T17:44"
        }
    ]
}

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 e-SiTef's support team if they find it necessary.

Response example

{
    "code": "255",
    "message": "Transaction Denied",
    "payments": [
        {
            "authorizer_code": "200",
            "authorizer_message": "Function performed error-free [Cód.: 00]",
            "status": "CON",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20030404545",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "414",
            "acquirer_name": "IPG",
            "authorizer_date": "25/03/2020T17:48",
            "authorization_number": "488040",
            "merchant_usn": "20030404545",
            "esitef_usn": "200325048537190",
            "host_usn": "572994560",
            "tid": "YES64194442",
            "amount": "102",
            "payment_type": "C",
            "payment_date": "25/03/2020T17:48"
        },
        {
            "authorizer_code": "200",
            "authorizer_message": "Function performed error-free [Cód.: 00]",
            "status": "PEN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20030404545",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "414",
            "acquirer_name": "IPG",
            "authorizer_date": "25/03/2020T17:48",
            "authorization_number": "454463",
            "merchant_usn": "20030404545",
            "esitef_usn": "200325048537200",
            "host_usn": "108829897",
            "tid": "YES45823552",
            "amount": "103",
            "payment_type": "C",
            "payment_date": "25/03/2020T17:48"
        }
    ]
}

Payment with late confirmation flow

The payment with late confirmation flow has 2 (two) stages: transactions update/initialization; payments effectuation.

If any transaction fails, e-SiTef 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

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "19",
            "authorizer_message": "19 Refaca Trans.",
            "status": "NEG",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25052428543",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "25/03/2020T17:24",
            "authorization_number": "080384",
            "merchant_usn": "25052428543",
            "esitef_usn": "200325048537090",
            "sitef_usn": "606060",
            "host_usn": "707070",
            "amount": "1254784",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "00000005"
        },
        {
            "status": "CAN"
        }
    ]
}

Second payment fails

When the second payment fails, the first transaction will be undone.

Response example

{
    "code": "1013",
    "message": "Error processing multiple payment methods",
    "payments": [
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPN",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25053142469",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "25/03/2020T17:31",
            "authorization_number": "252490",
            "merchant_usn": "25053142469",
            "esitef_usn": "200325048537130",
            "sitef_usn": "252490",
            "host_usn": "999252490   ",
            "amount": "100",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "25/03/2020T17:31"
        },
        {
            "authorizer_code": "255",
            "authorizer_message": "(2)Cartao invalido",
            "status": "NEG",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "25053142469",
            "authorizer_id": "2",
            "acquirer_name": "REDE",
            "merchant_usn": "25053142469",
            "esitef_usn": "200325048537140"
        }
    ]
}

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 e-SiTef. The production and certification codes will be different.	< 15 AN	YES
`merchant_key`	Merchant authentication key on e-SiTef. 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:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/multiple/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "multiple_payment_methods": [
        {
            "number": "45518201234512345",
            "expiry_date": "1222",
            "security_code": "123",
            "authorizer_id": "218",
            "installments": "1",
            "installment_type": "4",
            "amount": "512"
        },
        {
            "number": "45518201234512345",
            "expiry_date": "1222",
            "security_code": "123",
            "authorizer_id": "218",
            "installments": "1",
            "installment_type": "4",
            "amount": "510"
        }
    ]
}
--verbose

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payments": [
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPC",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20125445982",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "20/03/2020T14:32",
            "authorization_number": "202650",
            "merchant_usn": "16013439434",
            "esitef_usn": "200320048363850",
            "sitef_usn": "202650",
            "host_usn": "999202650   ",
            "amount": "512",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "20/03/2020T14:32"
        },
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPC",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20125445982",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "20/03/2020T14:32",
            "authorization_number": "202651",
            "merchant_usn": "16013439434",
            "esitef_usn": "200320048363860",
            "sitef_usn": "202651",
            "host_usn": "999202651   ",
            "amount": "510",
            "payment_type": "C",
            "issuer": "2",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "20/03/2020T14:32"
        }
    ]
}

Payment with stored card

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "multiple_payment_methods": [
        {
            "token": "g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ==",
            "authorizer_id": "1",
            "installments": "1",
            "installment_type": "4",
            "amount": "512",
            "security_code": "123"
        },
        {
            "token": "g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ==",
            "authorizer_id": "2",
            "installments": "1",
            "installment_type": "3",
            "amount": "510",
            "security_code": "321"
        }
    ]
}
--verbose

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "payments": [
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPC",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20125445982",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "1",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "20/03/2020T14:32",
            "authorization_number": "202650",
            "merchant_usn": "16013439434",
            "esitef_usn": "200320048363850",
            "sitef_usn": "202650",
            "host_usn": "999202650   ",
            "amount": "512",
            "payment_type": "C",
            "issuer": "1",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "20/03/2020T14:32"
        },
        {
            "authorizer_code": "000",
            "authorizer_message": "Transacao Aprov.",
            "status": "PPC",
            "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
            "order_id": "20125445982",
            "customer_receipt":"====CUPOM COMPRADOR====",
            "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
            "authorizer_id": "2",
            "acquirer_id": "5",
            "acquirer_name": "Redecard",
            "authorizer_date": "20/03/2020T14:32",
            "authorization_number": "202651",
            "merchant_usn": "16013439434",
            "esitef_usn": "200320048363860",
            "sitef_usn": "202651",
            "host_usn": "999202651   ",
            "amount": "510",
            "payment_type": "C",
            "issuer": "2",
            "authorizer_merchant_id": "000000000000005",
            "payment_date": "20/03/2020T14:32"
        }
    ]
}

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 e-SiTef. 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 e-SiTef initialization transaction request will be used.	< 2 N	NO
`installment_type`	Financing type. If this field is not sent, the value informed in the e-SiTef 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 e-SiTef. 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. Important: a payment with schedule implies on storing the customer's card data on e-SiTef'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`	Multiple payment methods operation e-SiTef response code. Any code different from `0` means failure. Learn more.	< 4 N
`message`	Multiple payment methods operation e-SiTef response message.	< 500 AN
payments[]	Multiple payment methods operation payments responses array. Each item corresponds to the response for one of the chosen payment methods. Its fields are described below.
`code`	e-SiTef response code for this payment method. Any code different from `0` means failure. Learn more..	< 4 N
`message`	e-SiTef 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 e-SiTef. Learn more.	= 3 AN
`nit`	Identifier of the payment transaction on e-SiTef.	= 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 e-SiTef.	= 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 Cielo e-Commerce).	< 3 AN
`payment_date`	Payment authorization date on e-SiTef 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. Only available to Cielo e-Commerce.	< 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 e-SiTef. This field can assume the following value: `NOV` – New. `EXP` – Expired. `ACC` – Accepted `REJ` – Rejected `REV` – In review `INV` – Invalid	= 3 AN

← Card query service Payment with multiple payment methods confirmation service →