PagBank
The store has the possibility to configure the routing of credit card transactions in Carat through various payment methods, one of which is PagBank.
Thus, the store can configure Carat so that transactions made with VISA or MASTERCARD cards, for example, are routed through PagBank.
Supported Carat Interfaces for Integration#
The following interfaces can be used for integration with PagBank routing:
REST
- Payment Interface
- Pre-Authorization Interface
- Capture Interface
- Cancellation Interface
Note: This integration also supports sending 3DS authentication data (
eci,xidecavv). Learn more.
Allowed Authorizers#
The following authorizers are supported by PagBank routing:
CREDIT
- VISA (1)
- MASTERCARD (2)
- AMERICAN EXPRESS (3)
- ELO (41)
DEBIT
- VISA ELECTRON (221)
- MASTERCARD DEBIT (286)
Accreditation#
Activation to use PagBank in a Carat store must be done via the Carat Portal.
There is an option to activate by clicking the button.
After that, you will be redirected to accept permissions in PagBank.
At the end, you will be informed of the successful activation and the status in the Carat Portal will appear as active.
REST#
The following parameters are mandatory for Payment and Pre-Authorization:
| Parameter | Description | Format | Required |
|---|---|---|---|
| additional_data.payer | Element for sending buyer-related data. | ||
name | Customer's first name. | < 100 AN | YES |
surname | Customer's surname. | < 100 AN | YES |
email | Customer's email address. | < 100 AN | YES |
identification_number | Customer's tax document number. | < 100 AN | YES |
Payment#
You can send the following fields in payment:
Payment Example#
Request:
curl --location 'http://localhost:8080/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: MERCHANTCODE' \
--header 'merchant_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data-raw '{
"merchant_usn": "2423423434",
"order_id": "0001755693903650",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "1834",
"card": {
"expiry_date": "1226",
"security_code": "123",
"number": "XXXXXXXXXXXXXXXX"
},
"additional_data": {
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"identification_number": "47764543004"
}
}
}'
Response:
{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "20000",
"status": "CON",
"nit": "29211ab6d779a6931215e3d7bc19bb6abc747424daad848c60066bb04cb48c57",
"order_id": "0001755721406930",
"customer_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 17:23:50 \n CODIGO PEDIDO: 0001755721406930 \n \n ID TRANSACAO: \nCHAR_B1FA7A35-BA37-46B4-9BB4-A984330D0300\n \n VALOR: 18,34 \n \n (e-SiTef) \n \n1a VIA - CLIENTE \n \n",
"merchant_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 17:23:50 \n CODIGO PEDIDO: 0001755721406930 \n \n ID TRANSACAO: \nCHAR_B1FA7A35-BA37-46B4-9BB4-A984330D0300\n \n VALOR: 18,34 \n NSU e-SiTef: 250820038414360 \n \n (e-SiTef) \n \n2a VIA - ESTABELECIMENTO \n \n",
"authorizer_id": "2",
"acquirer_id": "1328",
"acquirer_name": "Pagbank",
"merchant_usn": "2423423434",
"esitef_usn": "250820038414360",
"host_usn": "032416400102",
"tid": "CHAR_B1FA7A35-BA37-46B4-9BB4-A984330D0300",
"amount": "1834",
"payment_type": "C",
"payment_date": "20/08/2025T17:23"
}
}
Recurring Payment Example#
Request:
curl --location 'http://localhost:8080/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: MERCHANTCODE' \
--header 'merchant_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "RMC1755721854726",
"installments": "1",
"installment_type": "4",
"authorizer_id": "41",
"amount": "1100",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "XXXXXXXXXXXXXXXX"
},
"additional_data": {
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"identification_number": "47764543004"
},
"cardOnFileUsage":"first",
"cardOnFileReason": "recurring",
"acquirer": {
"cardOnFile": {
"usage": "first",
"reason": "recurring"
},
"recurrency": "true"
}
}
}'
Response:
{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "20000",
"status": "CON",
"nit": "9f77551490b1a8b9b20610d7093559a6c4383ed9bc7a512db37c2a3722e77e3d",
"order_id": "RMC1755721854726",
"customer_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 17:31:15 \n CODIGO PEDIDO: RMC1755721854726 \n \n ID TRANSACAO: \nCHAR_E672B951-60E0-4968-94E4-D81B2C31C4C8\n \n VALOR: 11,00 \n \n (e-SiTef) \n \n1a VIA - CLIENTE \n \n",
"merchant_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 17:31:15 \n CODIGO PEDIDO: RMC1755721854726 \n \n ID TRANSACAO: \nCHAR_E672B951-60E0-4968-94E4-D81B2C31C4C8\n \n VALOR: 11,00 \n NSU e-SiTef: 250820038414390 \n \n (e-SiTef) \n \n2a VIA - ESTABELECIMENTO \n \n",
"authorizer_id": "41",
"acquirer_id": "1328",
"acquirer_name": "Pagbank",
"merchant_usn": "12050620649",
"esitef_usn": "250820038414390",
"host_usn": "032416400102",
"tid": "CHAR_E672B951-60E0-4968-94E4-D81B2C31C4C8",
"amount": "1100",
"payment_type": "C",
"payment_date": "20/08/2025T17:31"
}
}
Anti-fraud Payment Example#
Request:
curl --location 'http://localhost:8080/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: MERCHANTCODE' \
--header 'merchant_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data-raw '{
"merchant_usn": "12050620649",
"order_id": "1672769143439",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "1301",
"card": {
"expiry_date": "1224",
"security_code": "123",
"number": "XXXXXXXXXXXXXXXX"
},
"additional_data": {
"vehicle":{
"make": "Bentley",
"model": "Bacalar",
"renavam": "12312312312",
"registration": "ABC1234",
"vid": "5GZCZ43D13S812715",
"type": "car",
"usage": "private",
"owner": {
"tax_id": "540.830.640-21",
"name": "Cicero"
}
},
"creation_date": "11/12/2024",
"anti_fraud": "enabled_before_auth",
"visitor_id": "XKhas09jcks",
"device": {
"user_id": null,
"fingerprint": "e4f2c690951038a8f77aa583847",
"provider": "SO",
"category": "Mobile",
"model": "S10",
"platform": "Android",
"manufacturer": "Samsung",
"os": "Android 11",
"browser": "Chrome",
"language": "pt"
},
"items": [
{
"title": "title1",
"quantity": "1",
"unit_price": "1111",
"description": "description1",
"id": "id1",
"discount_amount": "111",
"sku": "sku1",
"creation_date": "11/01/2011"
}
],
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"born_date": "1990-01-01T11:11:11",
"creation_date": "02/03/2004",
"is_new_client": "true",
"is_vip_client": "true",
"phones": [
{
"number": "333333333",
"ddd": "22",
"ddi": "11"
},
{
"number": "666666666",
"ddd": "55",
"ddi": "44"
}
],
"identification_number": "47764543004"
},
"shipment": {
"name": "Fernando",
"surname": "Bezerra",
"address": {
"zip_code": "98764312",
"street_number": "987",
"street_name": "Rua Shipment",
"complement": "ap. 587",
"city": "São Shipment",
"state": "MA",
"country": "BRA"
}
},
"passengers": [
{
"name": "Miguel",
"last_name": "Herrera",
"frequent_flyer_card": "frequentFlyerCard",
"legal_document_type": "1",
"legal_document": "12312312312",
"birth_date": "1980-07-28T10:40:00",
"customer_class": "customerClass",
"nationality": "BRA",
"is_frequent_traveler": "true",
"is_with_special_needs": "true"
}
],
"connections": [
{
"company": "Verde",
"class": "first",
"from": "GRU",
"to": "CGH",
"departure_date": "2023-09-07T07:09:00",
"journey_type": "OUTWARD",
"origin_city": "San Juan",
"destination_city": "Homero Lopez",
"class_code": "VIP"
},
{
"company": "Rosa",
"class": "economy",
"from": "BSB",
"to": "VCP",
"departure_date": "2022-10-21T16:39:00",
"journey_type": "RETURN",
"origin_city": "San Pablo",
"destination_city": "Juanito Cruz",
"class_code": "ECONOMY"
}
],
"hotel_reservations": [
{
"hotel": "Hotel Green Tree",
"address": {
"zip_code": "83392019",
"street_number": "529",
"street_name": "Rua Hoteleira",
"complement": "ap. 019",
"city": "San Hotel",
"state": "AC",
"country": "EN"
},
"rooms": [
{
"number": "902",
"code": "ROOM902",
"type": "King Size",
"check_in_date": "2020-01-09T12:30:00",
"check_out_date": "2020-01-19T13:00:00",
"number_of_guests": "1",
"board_basis": "Vegan",
"guests": [
{
"name": "José Aníbal",
"document": "98798798712",
"document_type": "cpf",
"birth_date": "12/03/1970",
"nationality": "BRA"
}
]
}
],
"category": "categoryhotel"
}
],
"billing_data": {
"address": {
"zip_code": "12341234",
"street_number": "666",
"street_name": "Rua Billing",
"complement": "ap. 2369",
"city": "São Billing",
"state": "AM",
"country": "BRA"
}
},
"travel": {
"transport_type": "flight",
"expiration_date": "2022-02-14T01:30:00"
},
"discount_info": "Informações de desconto",
"events": [
{
"name": "Evento de Rock",
"date": "2021-11-22T09:28:00",
"type": "show",
"subtype": "music",
"venue": {
"name": "Debicard Hall",
"street_name": "Rua do Evento",
"street_number": "928",
"city": "Jardinópolis",
"state": "MS",
"country": "DO",
"capacity": "300"
},
"tickets": [
{
"id": "12h374612h4h",
"category": "social",
"section": "Seção 1",
"premium": "true",
"attendee": {
"name": "Daniel Almeida",
"document": "71728293945",
"document_type": "other",
"birth_date": "03/10/1990"
}
}
]
}
]
}
}'
Response:
{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "20000",
"status": "CON",
"nit": "e6e2f71e1c582d8cccdb3d79c2b00e232165479f9dd282bb2af5e273d30f3247",
"order_id": "0001755726662008",
"customer_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 18:51:26 \n CODIGO PEDIDO: 0001755726662008 \n \n ID TRANSACAO: \nCHAR_CA0A7DCE-C5B5-4DC6-B672-A843B76BE7F2\n \n VALOR: 18,00 \n \n (e-SiTef) \n \n1a VIA - CLIENTE \n \n",
"merchant_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 18:51:26 \n CODIGO PEDIDO: 0001755726662008 \n \n ID TRANSACAO: \nCHAR_CA0A7DCE-C5B5-4DC6-B672-A843B76BE7F2\n \n VALOR: 18,00 \n NSU e-SiTef: 250820038414590 \n \n (e-SiTef) \n \n2a VIA - ESTABELECIMENTO \n \n",
"authorizer_id": "2",
"acquirer_id": "1328",
"acquirer_name": "Pagbank",
"merchant_usn": "2423423434",
"esitef_usn": "250820038414590",
"host_usn": "032416400102",
"tid": "CHAR_CA0A7DCE-C5B5-4DC6-B672-A843B76BE7F2",
"amount": "1800",
"payment_type": "C",
"payment_date": "20/08/2025T18:51"
}
}
3DS Payment Example#
Request:
curl --location 'http://localhost:8080/e-sitef/api/v2/payments/' \
--header 'Content-Type: application/json' \
--header 'merchant_id: MERCHANTCODE' \
--header 'merchant_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data-raw '{
"merchant_usn": "2423423434",
"order_id": "0001755726662008",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "1800",
"card": {
"expiry_date": "1226",
"security_code": "123",
"number": "XXXXXXXXXXXXXXXX"
},
"additional_data": {
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"identification_number": "47764543004"
}
},
"external_authentication": {
"xid": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
"eci": "05",
"cavv": "jMoRyYgNSt0ZAREBBu8LHI+3oZo="
}
}'
Response:
{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "20000",
"status": "CON",
"nit": "e6e2f71e1c582d8cccdb3d79c2b00e232165479f9dd282bb2af5e273d30f3247",
"order_id": "0001755726662008",
"customer_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 18:51:26 \n CODIGO PEDIDO: 0001755726662008 \n \n ID TRANSACAO: \nCHAR_CA0A7DCE-C5B5-4DC6-B672-A843B76BE7F2\n \n VALOR: 18,00 \n \n (e-SiTef) \n \n1a VIA - CLIENTE \n \n",
"merchant_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 18:51:26 \n CODIGO PEDIDO: 0001755726662008 \n \n ID TRANSACAO: \nCHAR_CA0A7DCE-C5B5-4DC6-B672-A843B76BE7F2\n \n VALOR: 18,00 \n NSU e-SiTef: 250820038414590 \n \n (e-SiTef) \n \n2a VIA - ESTABELECIMENTO \n \n",
"authorizer_id": "2",
"acquirer_id": "1328",
"acquirer_name": "Pagbank",
"merchant_usn": "2423423434",
"esitef_usn": "250820038414590",
"host_usn": "032416400102",
"tid": "CHAR_CA0A7DCE-C5B5-4DC6-B672-A843B76BE7F2",
"amount": "1800",
"payment_type": "C",
"payment_date": "20/08/2025T18:51"
}
}
Pre-Authorization#
It is possible to send the following fields in Pre-authorization:
Example#
Request:
curl --location 'http://localhost:8080/e-sitef/api/v2/preauthorizations/' \
--header 'merchant_id: MERCHANTCODE' \
--header 'merchant_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchant_usn": "2423423434",
"order_id": "0001755722641945",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "1300",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "XXXXXXXXXXXXXXXX"
},
"additional_data": {
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"identification_number": "47764543004"
}
}
}'
Response:
{
"code": "0",
"message": "OK. Transaction successful.",
"pre_authorization": {
"authorizer_code": "20000",
"status": "CON",
"nit": "e6918d1a70c54090939abefc3e543293ed95702bda814ecd6d177a7e77444d7f",
"order_id": "0001755722641945",
"customer_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 17:44:44 \n CODIGO PEDIDO: 0001755722641945 \n \n ID TRANSACAO: \nCHAR_044B5CEB-84F9-47A9-A886-BB8C55D96FA5\n \n VALOR: 13,00 \n \n (e-SiTef) \n \n1a VIA - CLIENTE \n \n",
"merchant_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 17:44:44 \n CODIGO PEDIDO: 0001755722641945 \n \n ID TRANSACAO: \nCHAR_044B5CEB-84F9-47A9-A886-BB8C55D96FA5\n \n VALOR: 13,00 \n NSU e-SiTef: 250820038414404 \n \n (e-SiTef) \n \n2a VIA - ESTABELECIMENTO \n \n",
"authorizer_id": "2",
"acquirer_id": "1328",
"acquirer_name": "Pagbank",
"merchant_usn": "2423423434",
"esitef_usn": "250820038414404",
"host_usn": "032416400102",
"tid": "CHAR_044B5CEB-84F9-47A9-A886-BB8C55D96FA5",
"amount": "1300",
"payment_type": "C"
}
}
Capture#
It is possible to send the following fields in capture.
Note: the capture can be full or partial.
Example#
Request:
curl --location 'http://localhost:8080/e-sitef/api/v2/preauthorizations/' \
--header 'merchant_id: MERCHANTCODE' \
--header 'merchant_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
"merchant_usn": "2423423434",
"order_id": "0001755723116888",
"installments": "1",
"installment_type": "4",
"authorizer_id": "2",
"amount": "1300",
"card": {
"expiry_date": "1222",
"security_code": "123",
"number": "XXXXXXXXXXXXXXXX"
},
"additional_data": {
"payer": {
"name": "John",
"surname": "Doe",
"email": "john@doe.com",
"identification_number": "47764543004"
}
}
}'
Response:
{
"code": "0",
"message": "OK. Transaction successful.",
"pre_authorization": {
"authorizer_code": "20000",
"status": "CON",
"nit": "1342033462cce3110b5cb4f0e9dd62fa744bc08afb303daa9e96dc65e6169fd8",
"order_id": "0001755723116888",
"customer_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 17:52:22 \n CODIGO PEDIDO: 0001755723116888 \n \n ID TRANSACAO: \nCHAR_D11A0701-6621-4AC4-89E1-0756B2C17B50\n \n VALOR: 13,00 \n \n (e-SiTef) \n \n1a VIA - CLIENTE \n \n",
"merchant_receipt": " CREDITO \n \n ESTAB: LOJAPAGBANK \n DATA: 20/08/2025 HORA: 17:52:22 \n CODIGO PEDIDO: 0001755723116888 \n \n ID TRANSACAO: \nCHAR_D11A0701-6621-4AC4-89E1-0756B2C17B50\n \n VALOR: 13,00 \n NSU e-SiTef: 250820038414454 \n \n (e-SiTef) \n \n2a VIA - ESTABELECIMENTO \n \n",
"authorizer_id": "2",
"acquirer_id": "1328",
"acquirer_name": "Pagbank",
"merchant_usn": "2423423434",
"esitef_usn": "250820038414454",
"host_usn": "032416400102",
"tid": "CHAR_D11A0701-6621-4AC4-89E1-0756B2C17B50",
"amount": "1300",
"payment_type": "C"
}
}
Cancel#
It is possible to send the following fields in cancel:
Note: the cancellation can be full or partial. Additionally, the cancellation has a synchronization time of about 3 to 5 minutes and may fail if the transaction time is too short.
Example#
Request:
curl --location 'http://localhost:8080/e-sitef/api/v2/cancellations/1342033462cce3110b5cb4f0e9dd62fa744bc08afb303daa9e96dc65e6169fd8' \
--header 'Content-Type: application/json' \
--header 'merchant_id: MERCHANTCODE' \
--header 'merchant_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Authorization: Bearer CODE' \
--data '{
"amount": "1300"
}'
Response:
{
"code": "0",
"message": "OK. Transaction successful.",
"cancellation": {
"authorizer_code": "20000",
"authorizer_message": "Refund successful.",
"status": "CON",
"nit": "1c1caed9c650b298e52e8b1acd7d9eb6b6e85bf029dc285f682b86e6283479ac",
"order_id": "1665693831749",
"customer_receipt":"=== COMPROVANTE ===",
"merchant_receipt":"=== COMPROVANTE ===",
"authorizer_id": "2",
"acquirer_id": "202",
"authorizer_date": "08/09/2022T17:43",
"merchant_usn": "12050620649",
"esitef_usn": "221013109643171",
"host_usn": "828420940",
"tid": "221013109643160",
"amount": "1300",
"payment_type": "C",
"is_host_cancel": "false"
}
}