PagBank
La tienda tiene la posibilidad de configurar el enrutamiento de transacciones realizadas con tarjeta de crédito en Carat a través de varios medios de pago, uno de ellos es PagBank.
Así, la tienda puede configurar Carat para que las transacciones realizadas con tarjetas VISA o MASTERCARD, por ejemplo, sean enrutadas a través de PagBank.
Interfaces Carat compatibles para integración
Es posible utilizar las siguientes interfaces para la integración con el enrutamiento de PagBank:
REST
- Interfaz de Pago
- Interfaz de Preautorización
- Interfaz de Captura
- Interfaz de Cancelación
Observación: Esta integración también acepta el envío de datos de autenticación 3DS (
eci,xidecavv). Más información.
Autorizadores permitidos
Los siguientes autorizadores son compatibles con el enrutamiento de PagBank:
-
CRÉDITO
- VISA (1)
- MASTERCARD (2)
- AMERICAN EXPRESS (3)
- ELO (41)
-
DÉBITO
- VISA ELECTRON (221)
- MASTERCARD DÉBITO (286)
Acreditación
La activación para usar PagBank en una tienda Carat debe realizarse a través del Portal Carat.
Allí se encuentra la opción de activar haciendo clic en el botón.
Después de eso, será redirigido para aceptar los permisos en PagBank.
Al final, se informará que la activación fue exitosa y el estado en el Portal Carat aparecerá como activo.
REST
Los siguientes parámetros son obligatorios para Pago y Preautorización:
| Parámetro | Descripción | Formato | Obligatorio |
|---|---|---|---|
| additional_data.payer | Elemento para el envío de datos del comprador. | ||
name | Nombre del cliente. | < 100 AN | SÍ |
surname | Apellido del cliente. | < 100 AN | SÍ |
email | Dirección de correo electrónico del cliente, | < 100 AN | SÍ |
identification_number | Número de documento fiscal del cliente, | < 100 AN | SÍ |
Pago
Es posible enviar los siguientes campos en pago:
Ejemplo de pago
Solicitud:
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"
}
}
}'
Respuesta:
{
"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"
}
}
Ejemplo de pago recurrente
Solicitud:
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"
}
}
}'
Respuesta:
{
"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"
}
}
Ejemplo de pago con antifraude
Solicitud:
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"
}
}
]
}
]
}
}'
Respuesta:
{
"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"
}
}
Ejemplo de pago con 3DS
Solicitud:
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="
}
}'
Respuesta:
{
"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"
}
}
Preautorización
Es posible enviar los siguientes campos en Preautorización:
Ejemplo
Solicitud:
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"
}
}
}'
Respuesta:
{
"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"
}
}
Captura
Es posible enviar los siguientes campos en captura.
Observación: la captura puede ser total o parcial.
Ejemplo
Solicitud:
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"
}
}
}'
Respuesta:
{
"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"
}
}
Cancelación
Es posible enviar los siguientes campos en cancelación:
Observación: la cancelación puede ser total o parcial. Además, la cancelación tiene un tiempo de sincronización de unos 3 a 5 minutos y puede fallar si el tiempo de la transacción es muy corto.
Ejemplo
Solicitud:
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}"
}'
Respuesta:
{
"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"
}
}