Home

Descripción general

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, xid e cavv). 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. Activación Portal Carat

Después de eso, será redirigido para aceptar los permisos en PagBank. Permisos PagBank

Al final, se informará que la activación fue exitosa y el estado en el Portal Carat aparecerá como activo. Mensaje de activación exitosa Mensaje de activación exitosa

REST#

Los siguientes parámetros son obligatorios para Pago y Preautorización:

ParámetroDescripciónFormatoObligatorio
additional_data.payerElemento para el envío de datos del comprador.
nameNombre del cliente.< 100 ANSÍ
surnameApellido del cliente.< 100 ANSÍ
emailDirección de correo electrónico del cliente,< 100 ANSÍ
identification_numberNúmero de documento fiscal del cliente,< 100 ANSÍ

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: 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"
}
}
}'

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: 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"
}
}
}'

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: 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"
}
}
]
}
]
}
}'

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: 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="
}
}'

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: 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"
}
}
}'

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: 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"
}
}
}'

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: MERCHANTCODE' \
--header 'merchant_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--header 'Authorization: Bearer CODE' \
--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"
}
}