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: {MERCHANT_CODE}' \
--header 'merchant_key: {MERCHANT_KEY}' \
--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: {MERCHANT_CODE}' \
--header 'merchant_key: {MERCHANT_KEY}' \
--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: {MERCHANT_CODE}' \
--header 'merchant_key: {MERCHANT_KEY}' \
--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: {MERCHANT_CODE}' \
--header 'merchant_key: {MERCHANT_KEY}' \
--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: {MERCHANT_CODE}' \
--header 'merchant_key: {MERCHANT_KEY}' \
--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: {MERCHANT_CODE}' \
--header 'merchant_key: {MERCHANT_KEY}' \
--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: {MERCHANT_CODE}' \
--header 'merchant_key: {MERCHANT_KEY}' \
--header 'Authorization: {TOKEN_JWT_EXAMPLE}' \
--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"
}
}