> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Receba notificações de pagamento

Receba notificações instantâneas via webhook para cada pagamento da sua Conta Virtual e atualize seus sistemas e confirme os créditos automaticamente.

Depois de criar uma conta virtual e associá-la a um cliente ou fatura específica em seus sistemas internos, o Localpayment envia automaticamente uma notificação via webhook para o seu servidor sempre que um pagamento for recebido com sucesso nessa conta.

**Importante**: Uma conta virtual funciona como um destino de pagamento dedicado. Embora você gerencie a atribuição interna, o número da conta em si pode receber fundos de qualquer pagador. A notificação de pagamento conterá detalhes do pagador real, permitindo que você concilie o pagamento com seu mapeamento interno de clientes.

Essas notificações em tempo real permitem que você confirme créditos, atualize saldos e concilie pagamentos automaticamente, sem verificação manual.

***

## Antes de começar

Certifique-se de ter:

* Conta virtual criada com sucesso através do endpoint [Criar conta virtual](https://docs.localpayment.com/pt-br/reference/create-virtual-account.md).
* Um endpoint de notificação (URL do webhook) configurado em sua conta de comerciante.
* A capacidade de receber solicitações HTTPS POST dos servidores da Localpayment.
* Lógica no seu backend para validar e analisar payloads de webhook com segurança.

***

## Como funciona

1. O pagador envia uma transferência para o número da Conta Virtual previamente gerado pelo seu sistema.
2. Assim que os fundos forem creditados e validados pelo Localpayment, uma notificação de pagamento será enviada para o endpoint webhook configurado.
3. Seu sistema deve reconhecer a notificação com uma resposta 200 OK.
4. Em seguida, você poderá atualizar seus registros internos para marcar a Conta Virtual como paga ou o pedido correspondente como concluído.

> [!NOTE]
>
> ###
>
> O Localpayment garante a entrega por meio de novas tentativas com recuo exponencial caso seu servidor não responda com HTTP 200.

***

## Exemplo de notificação (carga útil do webhook)

Segue abaixo um exemplo de carga útil para um pagamento bem-sucedido creditado em uma Conta Virtual:

```json ARG theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "ARG",
  "data": {
      "transactionType": "PayIn",
      "externalId": "59a61a76-2480-4996-8633-528227e1db10",
      "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
      "paymentMethod": {
          "type": "BankTransfer",
          "code": "1025",
          "flow": "DIRECT"
      },
      "country": "ARG",
      "currency": "ARS",
      "amount": 1.09,
      "accountNumber": "{{accountNumber}}",
      "confirmed": {
          "currency": "ARS",
          "fxQuote": 1,
          "amount": 1.09
      },
      "payment": {
          "currency": "ARS",
          "fxQuote": 1,
          "financingFee": 0,
          "amount": 1.09
      },
      "localTaxes": [
          {
              "code": "0001",
              "percentage": 1.2,
              "description": "IDC",
              "currency": "ARS",
              "fxSource": 1193.82,
              "fxQuote": 0,
              "amount": 0.01,
              "account": "{{accountNumber}}"
          }
      ],
      "withHoldings": [],
      "fees": {
          "description": "Fee",
          "currency": "ARS",
          "fxSource": 1170.50002,
          "fxQuote": 1,
          "amount": 0,
          "account": "{{accountNumber}}"
      },
      "status": {
          "code": "200",
          "description": "COMPLETED",
          "detail": "The payin was credited"
      },
      "beneficiary": {
          "type": "INDIVIDUAL",
          "name": "John",
          "lastName": "Doe",
          "fullName": "John Doe",
          "document": {
              "type": "CUIT",
              "id": "20314567894"
          },
          "bank": {
              "account": {
                  "number": "0000369600000000123456"
              }
          },
          "informedName": "Unknown"
      },
      "merchant": {
          "type": "MERCHANT",
          "name": "Localpayment Test",
          "lastName": ""
      },
      "payer": {
          "type": "INDIVIDUAL",
          "name": "Carlos",
          "lastName": "Mendez",
          "fullName": "Carlos Mendez",
          "document": {
              "type": "CUIT",
              "id": "20314567894"
          },
          "email": "carlos.mendez@email.com",
          "bank": {
              "name": "BANCO DE GALICIA Y BUENOS AIRES S.A.U.",
              "code": "007",
              "branch": {},
              "account": {
                  "type": "C",
                  "number": "0070055930004044654321"
              }
          }
      },
      "date": {
          "creationDate": "2025-04-30T17:26:37.186",
          "processedDate": "2025-04-30T17:26:37.363"
      },
      "errors": [],
      "referenceCode": "DHF2-XOHO-NE77",
      "tracking": {
          "id": "7L8GYKNXWJELWYGP2MPRZ5",
          "reference": "7L8GYKNXWJELWYGP2MPRZ5",
          "concept": "CVU TEST"
      }
  }
}
```

```json BRA theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "BRA",
  "data": {
      "transactionType": "PayIn",
      "externalId": "d96a9440-afe2-453f-a3b5-155a7fb17241",
      "internalId": "d220f7cc-e2cd-4b40-95ae-59d85bf68a7e",
      "paymentMethod": {
          "type": "BankTransfer",
          "code": "1350",
          "flow": "DIRECT"
      },
      "country": "BRA",
      "currency": "BRL",
      "amount": 55554.63,
      "accountNumber": "{{accountNumber}}",
      "confirmed": {
          "currency": "BRL",
          "fxQuote": 1,
          "amount": 55554.63
      },
      "payment": {
          "currency": "BRL",
          "fxQuote": 1,
          "financingFee": 0,
          "amount": 55554.63
      },
      "localTaxes": [
          {
              "code": "0002",
              "percentage": 0.38,
              "description": "IOF",
              "currency": "BRL",
              "fxSource": 5.5813,
              "fxQuote": 0,
              "amount": 211.11,
              "account": "{{accountNumber}}"
          }
      ],
      "withHoldings": [],
      "fees": {
          "description": "Fee",
          "currency": "BRL",
          "fxSource": 5.80427174,
          "fxQuote": 1,
          "amount": 55.55,
          "account": "{{accountNumber}}"
      },
      "status": {
          "code": "200",
          "description": "COMPLETED",
          "detail": "The payin was credited"
      },
      "beneficiary": {
          "type": "INDIVIDUAL",
          "name": "Rafael",
          "lastName": "Oliveira",
          "fullName": "Rafael Oliveira",
          "document": {
              "type": "CPF",
              "id": "12345678909"
          },
          "bank": {
              "code": "450",
              "branch": {},
              "account": {
                  "number": "52415912345",
                  "alias": "cf226732-139c-4ec8-b672-8aa0fc7ee6ea",
                  "aliases": [
                      {
                          "value": "cf406732-139c-4ec8-b672-8aa0fc7ee6ea"
                      }
                  ]
              }
          }
      },
      "merchant": {
          "type": "COMPANY",
          "name": "ACME"
      },
      "payer": {
          "type": "INDIVIDUAL",
          "name": "Rafael",
          "lastName": "Oliveira",
          "fullName": "Rafael Oliveira",
          "document": {
              "type": "CPF",
              "id": "12345678909"
          },
          "email": "rafael.oliveira@email.com",
          "bank": {
              "code": "001",
              "branch": {},
              "account": {
                  "type": "C",
                  "number": "45063"
              }
          }
      },
      "date": {
          "creationDate": "2025-04-17T17:01:52.850",
          "processedDate": "2025-04-17T17:01:53.025"
      },
      "errors": [],
      "referenceCode": "5XWA-MGQ0-ZKZ6",
      "tracking": {
          "id": "E0000000022250417170028008753346",
          "reference": "",
          "concept": "11778498595"
      }
  }
}
```

```json CHL theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "CHL",
  "data": {
      "transactionType": "PayIn",
      "externalId": "c3f819ba-240a-47cd-8cbe-e95a43e1552d",
      "internalId": "e8da1f0e-38ef-46b9-8360-4d40f78605af",
      "paymentMethod": {
          "type": "BankTransfer",
          "code": "2550",
          "flow": "DIRECT"
      },
      "country": "CHL",
      "currency": "CLP",
      "amount": 100,
      "accountNumber": "{{accountNumber}}",
      "confirmed": {
          "currency": "CLP",
          "fxQuote": 1,
          "amount": 100
      },
      "payment": {
          "currency": "CLP",
          "fxQuote": 1,
          "financingFee": 0,
          "amount": 100
      },
      "localTaxes": [],
      "withHoldings": [],
      "fees": {
          "description": "Fee",
          "currency": "CLP",
          "fxSource": 967.340406,
          "fxQuote": 1,
          "amount": 0,
          "account": "{{accountNumber}}"
      },
      "status": {
          "code": "200",
          "description": "COMPLETED",
          "detail": "The payin was credited"
      },
      "beneficiary": {
          "type": "INDIVIDUAL",
          "name": "Valentina",
          "lastName": "Rojas",
          "fullName": "Valentina Rojas",
          "document": {
              "type": "RUT",
              "id": "123456789"
          },
          "bank": {
              "name": "Banco Security",
              "code": "049",
              "branch": {},
              "account": {
                  "type": "C",
                  "number": "928630123"
              }
          }
      },
      "merchant": {
          "type": "COMPANY",
          "name": "Localpayment Test"
      },
      "payer": {
          "type": "INDIVIDUAL",
          "name": "Valentina",
          "lastName": "Rojas",
          "fullName": "Valentina Rojas",
          "document": {
              "type": "RUT",
              "id": "123456789"
          },
          "email": "valentina.rojas@email.com",
          "bank": {
              "name": "BANCO DE CRÉDITO E INVERSIONES (BCI)",
              "code": "016",
              "branch": {},
              "account": {
                  "type": "C",
                  "number": "57229123"
              }
          },
          "userReference": "Test 928630996"
      },
      "date": {
          "creationDate": "2025-07-16T16:12:50.163",
          "processedDate": "2025-07-16T16:12:50.396"
      },
      "errors": [],
      "referenceCode": "QSR5-FE1Y-DIVT",
      "tracking": {
          "id": "000739531483",
          "reference": "2025-07-16-12.10.09.237295",
          "concept": "Test 928630996"
      }
  }
}
```

```json COL theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "COL",
  "data": {
      "transactionType": "PayIn",
      "externalId": "cf194632-7ec4-4a44-9b92-9bbacad5349a",
      "internalId": "b97ac13c-1acb-4bc0-8b2a-067945e26161",
      "paymentMethod": {
          "type": "BankTransfer",
          "code": "2006",
          "flow": "DIRECT"
      },
      "country": "COL",
      "currency": "COP",
      "amount": 1000,
      "accountNumber": "{{accountNumber}}",
      "confirmed": {
          "currency": "COP",
          "fxQuote": 1.0,
          "amount": 1000.0
      },
      "payment": {
          "currency": "COP",
          "fxQuote": 1.0,
          "financingFee": 0.0,
          "amount": 1000.0
      },
      "localTaxes": [],
      "withHoldings": [],
      "fees": {
          "description": "Fee",
          "currency": "COP",
          "fxSource": 3705.82,
          "fxQuote": 1.0,
          "amount": 1.0,
          "account": "{{accountNumber}}"
      },
      "status": {
          "code": "200",
          "description": "COMPLETED",
          "detail": "The payin was credited"
      },
      "beneficiary": {
          "type": "INDIVIDUAL",
          "name": "Andres",
          "lastName": "Herrera",
          "fullName": "Andres Herrera",
          "document": {
              "type": "CC",
              "id": "1020456789"
          },
          "bank": {
              "name": "BANCO DE BOGOTÁ",
              "code": "1001",
              "account": {
                  "type": "KEY",
                  "number": "@XXXXXXXOXX0000"
              }
          }
      },
      "merchant": {
          "type": "COMPANY",
          "name": "Test company",
          "lastName": ""
      },
      "payer": {
          "type": "INDIVIDUAL",
          "name": "Andres",
          "lastName": "Herrera",
          "fullName": "Andres Herrera",
          "document": {
              "type": "CC",
              "id": "1020456789"
          },
          "email": "andres.herrera@email.com",
          "bank": {
              "name": "BANCO POPULAR",
              "code": "1002",
              "account": {
                  "type": "BREB",
                  "number": "signer:wTUTnHK5mLAQXLgVuhoANKGaKTdgRFmrx7@breb"
              }
          }
      },
      "date": {
          "creationDate": "2026-02-25T18:53:25Z",
          "processedDate": "2026-02-25T18:53:26Z"
      },
      "errors": [],
      "referenceCode": "V0ZO-AIPV-NOD9",
      "tracking": {
          "id": "20260225900504001TFY123451234501234",
          "reference": "20260225900504001TFY123451234501234",
          "concept": "Test payment"
      }
  }
}
```

```json CRI-CRC theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "CRI",
  "data": {
    "transactionType": "PayIn",
    "externalId": "bc56ff3e-5291-40e9-89e1-ef258b6095a9",
    "internalId": "c06bbea8-48d1-4659-9664-633b7f9f080d",
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "1420",
      "flow": "DIRECT"
    },
    "country": "CRI",
    "currency": "CRC",
    "amount": 500,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
      "currency": "CRC",
      "fxQuote": 1.0,
      "amount": 500.0
    },
    "payment": {
      "currency": "CRC",
      "fxQuote": 1.0,
      "financingFee": 0.0,
      "amount": 500.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "grossingUps": [],
    "fees": {
      "description": "Fee",
      "currency": "CRC",
      "fxSource": 453.811158,
      "fxQuote": 1.0,
      "amount": 0.0,
      "account": "{{accountNumber}}"
    },
    "status": {
      "code": "200",
      "description": "COMPLETED",
      "detail": "The payin was credited"
    },
    "beneficiary": {
      "type": "COMPANY",
      "name": "LP MERGE SRL",
      "document": {
        "type": "CEJ",
        "id": "3100000001"
      },
      "bank": {
        "account": {
          "number": "CR99000000000000000001"
        }
      }
    },
    "merchant": {
      "type": "COMPANY",
      "name": "LP MERGE SRL"
    },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "John",
      "lastName": "Doe",
      "document": {
        "type": "CI",
        "id": "01-0100-0001"
      },
      "email": "NA",
      "bank": {
        "name": "Banco Nacional de Costa Rica",
        "code": "0102",
        "branch": {
          "code": "",
          "name": ""
        },
        "account": {
          "number": "CR99000000000000000002"
        }
      }
    },
    "date": {
      "creationDate": "2026-06-22T14:46:18Z",
      "processedDate": "2026-06-22T14:46:19Z"
    },
    "errors": [],
    "referenceCode": "IQCT-J9P2-WZRG",
    "tracking": {
      "id": "2026062210222010504969350",
      "reference": "26736337",
      "concept": "Steph_test_____"
    }
  }
}
```

```json CRI-USD theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "CRI",
  "data": {
    "transactionType": "PayIn",
    "externalId": "bc56ff3e-5291-40e9-89e1-ef258b6095a9",
    "internalId": "c06bbea8-48d1-4659-9664-633b7f9f080d",
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "1421",
      "flow": "DIRECT"
    },
    "country": "CRI",
    "currency": "USD",
    "amount": 500,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
      "currency": "USD",
      "fxQuote": 1.0,
      "amount": 500.0
    },
    "payment": {
      "currency": "USD",
      "fxQuote": 1.0,
      "financingFee": 0.0,
      "amount": 500.0
    },
    "localTaxes": [],
    "withHoldings": [],
    "grossingUps": [],
    "fees": {
      "description": "Fee",
      "currency": "USD",
      "fxSource": 453.811158,
      "fxQuote": 1.0,
      "amount": 0.0,
      "account": "{{accountNumber}}"
    },
    "status": {
      "code": "200",
      "description": "COMPLETED",
      "detail": "The payin was credited"
    },
    "beneficiary": {
      "type": "COMPANY",
      "name": "LP MERGE SRL",
      "document": {
        "type": "CEJ",
        "id": "3100000001"
      },
      "bank": {
        "account": {
          "number": "CR99000000000000000001"
        }
      }
    },
    "merchant": {
      "type": "COMPANY",
      "name": "LP MERGE SRL"
    },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "John",
      "lastName": "Doe",
      "document": {
        "type": "CI",
        "id": "01-0100-0001"
      },
      "email": "NA",
      "bank": {
        "name": "Banco Nacional de Costa Rica",
        "code": "0102",
        "branch": {
          "code": "",
          "name": ""
        },
        "account": {
          "number": "CR99000000000000000002"
        }
      }
    },
    "date": {
      "creationDate": "2026-06-22T14:46:18Z",
      "processedDate": "2026-06-22T14:46:19Z"
    },
    "errors": [],
    "referenceCode": "IQCT-J9P2-WZRG",
    "tracking": {
      "id": "2026062210222010504969350",
      "reference": "26736337",
      "concept": "Steph_test_____"
    }
  }
}
```

```json MEX (SPEI) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "MEX",
  "data": {
      "transactionType": "PayIn",
      "externalId": "c2eabb54-6314-414d-9bdc-1004fba09737",
      "internalId": "72b3e90d-22ec-4afd-a360-f3a08301c660",
      "paymentMethod": {
          "type": "BankTransfer",
          "code": "1630",
          "flow": "DIRECT"
      },
      "country": "MEX",
      "currency": "MXN",
      "amount": 1000,
      "accountNumber": "{{accountNumber}}",
      "confirmed": {
          "currency": "MXN",
          "fxQuote": 1,
          "amount": 1000
      },
      "payment": {
          "currency": "MXN",
          "fxQuote": 1,
          "financingFee": 0,
          "amount": 1000
      },
      "localTaxes": [],
      "withHoldings": [],
      "fees": {
          "description": "Fee",
          "currency": "MXN",
          "fxSource": 1,
          "fxQuote": 1,
          "amount": 50,
          "account": "{{accountNumber}}"
      },
      "status": {
          "code": "200",
          "description": "COMPLETED",
          "detail": "The payin was credited"
      },
      "beneficiary": {
          "type": "INDIVIDUAL",
          "name": "Juan",
          "lastName": "Perez",
          "fullName": "Juan Perez",
          "document": {
              "type": "RFC",
              "id": "PEPJ800101XXX"
          },
          "bank": {
              "account": {
                  "number": "646011319800123456"
              }
          },
          "informedName": "LPV3_PayinVA"
      },
      "merchant": {
          "type": "COMPANY",
          "name": "Test Merchant"
      },
      "payer": {
          "type": "INDIVIDUAL",
          "name": "Alejandra",
          "lastName": "Guzman",
          "fullName": "Alejandra Guzman",
          "document": {
              "type": "RFC",
              "id": "KCWV771228TS4"
          },
          "email": "alejandra.guzman@email.com",
          "bank": {
              "name": "Sistema de Transferencias y Pagos",
              "code": "646",
              "branch": {},
              "account": {
                  "type": "C",
                  "number": "646011319800123456"
              }
          }
      },
      "date": {
          "creationDate": "2024-02-19T20:18:30.373",
          "processedDate": "2024-02-19T20:18:30.601"
      },
      "errors": [],
      "referenceCode": "C2VV-MVVN-QHFI",
      "tracking": {
          "id": "lpv3_1111-19feb2024-2400",
          "reference": "999999",
          "concept": "concepto pago LPV3_4707"
      }
  }
}
```

```json MEX (TEF) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "MEX",
  "data": {
      "transactionType": "PayIn",
      "externalId": "3fb782c0-9c26-47b8-a66d-6c127934403e",
      "internalId": "b7f7284f-1684-4ec9-a932-5da2aed7e159",
      "paymentMethod": {
          "type": "BankTransfer",
          "code": "1680",
          "flow": "DIRECT"
      },
      "country": "MEX",
      "currency": "MXN",
      "amount": 1000.01,
      "accountNumber": "{{accountNumber}}",
      "confirmed": {
          "currency": "MXN",
          "fxQuote": 1,
          "amount": 1000.01
      },
      "payment": {
          "currency": "MXN",
          "fxQuote": 1,
          "financingFee": 0,
          "amount": 1000.01
      },
      "localTaxes": [],
      "withHoldings": [],
      "fees": {
          "description": "Fee",
          "currency": "MXN",
          "fxSource": 18.76902,
          "fxQuote": 1,
          "amount": 0,
          "account": "{{accountNumber}}"
      },
      "status": {
          "code": "200",
          "description": "COMPLETED",
          "detail": "The payin was credited"
      },
      "beneficiary": {
          "type": "COMPANY",
          "name": "My Company",
          "document": {
              "type": "RUC",
              "id": "200123456789"
          },
          "bank": {
              "name": "{{bankName}}",
              "code": "{{bankCode}}",
              "account": {
                  "number": "000000000000000009"
              }
          },
          "informedName": "My Company"
      },
      "merchant": {
          "type": "COMPANY",
          "name": "Localpayment Test",
          "lastName": ""
      },
      "payer": {
          "type": "COMPANY",
          "name": "John",
          "lastName": "Doe",
          "document": {
              "type": "RFC",
              "id": ""
          },
          "email": "NA",
          "bank": {
              "name": "BANCO INBURSA",
              "code": "036",
              "account": {
                  "type": "CLABE",
                  "number": "00000000000000000001"
              }
          }
      },
      "date": {
          "creationDate": "2025-08-21T15:15:05.113",
          "processedDate": "2025-08-21T15:15:05.346"
      },
      "errors": [],
      "referenceCode": "AHB3-2LHB-8RG1",
      "tracking": {
          "id": "1234-2025",
          "reference": "999999",
          "concept": "Test payment"
      }
  }
}
```

```json MEX (SPID) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "transactionFlow": null,
  "country": "MEX",
  "data": {
    "transactionType": "PayIn",
    "externalId": "1f6b6f3a-3c3f-4e08-ba14-ac0d2a521ad5",
    "internalId": "43aa5b5b-7566-4630-b86f-afb8486ccab4",
    "paymentMethod": {
      "type": "BankTransfer",
      "code": "1698",
      "flow": "DIRECT"
    },
    "country": "MEX",
    "currency": "USD",
    "amount": 3,
    "accountNumber": "{{accountNumber}}",
    "confirmed": {
      "currency": "USD",
      "fxQuote": 1,
      "amount": 3
    },
    "payment": {
      "currency": "USD",
      "fxQuote": 1,
      "financingFee": 0,
      "amount": 3
    },
    "localTaxes": [],
    "withHoldings": [],
    "fees": {
      "description": "Fee",
      "currency": "USD",
      "fxSource": 1,
      "fxQuote": 1,
      "amount": 0.01,
      "account": "{{accountNumber}}"
    },
    "status": {
      "code": "200",
      "description": "COMPLETED",
      "detail": "The payin was credited"
    },
    "beneficiary": {
      "type": "COMPANY",
      "name": "Test Company",
      "document": {
        "type": "RFC",
        "id": "XXX010101000"
      },
      "bank": {
        "account": {
          "number": "000111111111111111"
        }
      },
      "informedName": "Company name"
    },
    "merchant": {
      "type": "COMPANY",
      "name": "Localpayment Test"
    },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "John",
      "lastName": "Doe",
      "document": {
        "type": "RFC",
        "id": "XXX010101000"
      },
      "email": "NA",
      "bank": {
        "name": "{{bankName}}",
        "code": "{{bankCode}}",
        "branch": {
          "code": "",
          "name": ""
        },
        "account": {
          "type": "C",
          "number": "000111111111111111"
        }
      }
    },
    "date": {
      "creationDate": "2026-01-26T15:10:03Z",
      "processedDate": "2026-01-26T15:10:03Z"
    },
    "errors": [],
    "referenceCode": "XXXX-XXXX-XXXX",
    "tracking": {
      "id": "111XXX1X1",
      "reference": "XXXX",
      "concept": "TEST"
    }
  }
}
```

```json PER theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "transactionType": "PayIn",
    "transactionFlow": null,
    "country": "PER",
    "data": {
        "transactionType": "PayIn",
        "externalId": "ff9178f7-fcda-1e38-acaa-3cbe2c5d4976",
        "internalId": "902127f8-35b3-47a7-b24a-1e39411740e5",
        "paymentMethod": {
            "type": "BankTransfer",
            "code": "6100",
            "flow": "DIRECT"
        },
        "country": "PER",
        "currency": "PEN",
        "amount": 5,
        "accountNumber": "{{accountNumber}}",
        "confirmed": {
            "currency": "PEN",
            "fxQuote": 1,
            "amount": 5
        },
        "payment": {
            "currency": "PEN",
            "fxQuote": 1,
            "financingFee": 0,
            "amount": 5
        },
        "localTaxes": [
            {
                "code": "0006",
                "percentage": 0.005,
                "description": "ITF",
                "currency": "PEN",
                "fxSource": 3.742498,
                "fxQuote": 0,
                "amount": 0,
                "account": "{{accountNumber}}"
            }
        ],
        "withHoldings": [],
        "fees": {
            "description": "Fee",
            "currency": "PEN",
            "fxSource": 3.386033,
            "fxQuote": 1,
            "amount": 1,
            "account": "{{accountNumber}}"
        },
        "status": {
            "code": "200",
            "description": "COMPLETED",
            "detail": "The payin was credited"
        },
        "beneficiary": {
            "type": "INDIVIDUAL",
            "name": "Lucia",
            "lastName": "Torres",
            "fullName": "Lucia Torres",
            "document": {
                "type": "DNI",
                "id": "45678901"
            },
            "bank": {
                "account": {
                    "number": "92250610000000101234"
                }
            }
        },
        "merchant": {
            "type": "COMPANY",
            "name": "Localpayment Test"
        },
        "payer": {
            "type": "INDIVIDUAL",
            "name": "Lucia",
            "lastName": "Torres",
            "fullName": "Lucia Torres",
            "document": {
                "type": "DNI",
                "id": "45678901"
            },
            "email": "lucia.torres@email.com",
            "bank": {
                "name": "INTERBANK (BANCO INTERNACIONAL DEL PERÚ)",
                "code": "003",
                "branch": {},
                "account": {
                    "type": "C",
                    "number": "00310701315123456789"
                }
            }
        },
        "date": {
            "creationDate": "2025-10-20T16:07:50Z",
            "processedDate": "2025-10-20T16:07:50Z"
        },
        "errors": [],
        "referenceCode": "6WXD-CXLO-U8UN",
        "tracking": {
            "id": "2025102011074908084191797675",
            "reference": "00100000297079044806",
            "concept": ""
        }
    }
}
```

## Campos de webhook para correspondência

A notificação do webhook contém campos específicos que servem como identificadores. Use a tabela abaixo para associar o pagamento recebido aos seus registros internos.

| Campo | Descrição |
| - | - |
| `accountNumber` | Número da conta do comerciante. |
| `amount` | Valor recebido. |
| `payer.name ` and  `payer.lastName` | Nome completo do pagador. |
| `payer.document.id` | Identificação nacional do pagador (se disponível). |
| `payer.bank.account.number` | Número da conta de origem utilizada pelo pagador. |
| `beneficiary.name` and `beneficiary.document.id` | Nome e ID do titular da conta virtual. |
| `beneficiary.bank.account.number` | O número da conta local da conta virtual que recebeu o pagamento (CVU para Argentina, CLABE para México, CCI para Peru, etc.). Utilize este campo para associar o pagamento recebido à conta virtual específica em seus registros. |
| `referenceCode` | Uma referência gerada pelo Localpayment no formato `XXXX-XXXX-XXXX` (três blocos alfanuméricos de quatro caracteres). Use apenas para referência legível por humanos. Para idempotência e desduplicação, use `internalId` ou `externalId`. |
| `tracking.id` | Identificador gerado pela plataforma de pagamento ou pelo banco do pagador. O formato varia conforme o país. Para a Colômbia Bre-B, esta é a referência oficial para conciliação. |
| `tracking.reference` | Também gerado pelo trilho/banco. Não há garantia de que esteja presente ou seja único em todos os trilhos. No México, é uma referência bancária mais curta inserida pelo pagador; no Peru, pode estar vazia. |
| `tracking.concept` | Destinado a conter a descrição do pagamento. Frequentemente contém sequências geradas pelo sistema em vez de texto livre do pagador. Use apenas como contexto suplementar. |
| `date.creationDate` and `date.processedDate` | O objeto `date` fornece os carimbos de data/hora UTC que rastreiam a transação desde sua criação no sistema (`creationDate`) até sua liquidação financeira final (`processedDate`). |

## Utilizando Referências de Pagamento

Os pagadores podem adicionar uma referência (por exemplo, um número de pedido) à sua transferência. Esses dados aparecem no objeto `tracking` do webhook para correspondência direta.

> [!WARNING]
>
> ###
>
> **Importante**
>
> * **Disponibilidade:** O objeto `tracking` está **disponível apenas em webhooks**, não em relatórios de transações ou na API.
> * Para o **México (SPID)**, o `externalId` corresponde à chave de rastreamento do Banco de México (Clave de Rastreo), tornando-a o campo oficial para reconciliação.

### Exemplo de objeto de rastreamento

```json ARG theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "7L8GYKNXWJELWYGP2MPRZ5",
    "reference": "7L8GYKNXWJELWYGP2MPRZ5",
    "concept": "CVU TEST"
}
```

```json BRA theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "E0000000022250417170028001234567",
    "reference": "",
    "concept": "11778498533"
}
```

```json CHL theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "000739531234",
    "reference": "2025-07-16-12.10.09.237212",
    "concept": "Test 928630123"
}
```

```json COL theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
            "id": "20260225900504001TFY123451234500001",
            "reference": "20260225900504001TFY123451234500001",
            "concept": "Transfer via BRE-B"
        }
```

```json MEX (SPEI and TEF) theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "lpv3_1111-19feb2024-24123",
    "reference": "999999",
    "concept": "concepto pago LPV3_4707"
}
```

```json PER theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
"tracking": {
    "id": "20251020110749080841911234567",
    "reference": "00100000297079041234",
    "concept": ""
}
```

***

## Identificadores-chave na notificação

A notificação inclui diversos campos de referência e rastreamento gerados por diferentes partes. Compreender a origem e a confiabilidade de cada um deles ajuda a construir uma estratégia de reconciliação confiável.

### referenceCode

Gerado pelo Localpayment. Segue sempre o formato `XXXX-XXXX-XXXX` — três blocos alfanuméricos de quatro caracteres — em todos os países e trilhos, o que confirma que a notificação se originou da Localpayment.

`referenceCode` é uma referência Localpayment legível por humanos, não uma chave de idempotência. Para desduplicação e idempotência, use `internalId` ou `externalId`.

### tracking.id

Gerado pela plataforma de pagamentos ou pelo banco do pagador, não pela Localpayment. O formato varia conforme o país:

| País | Formato |
| - | - |
| Argentina | Chave alfanumérica longa (ex: `7L8GYKNXWJELWYGP2MPRZ5`) |
| Brasil (PIX) | Número E (ex: `E0000000022250417170028008753346`) |
| Chile | Número curto (ex: `000739531483`) |
| Colômbia (Bre-B) | ID da transação da rede Bre-B — referência de reconciliação autorizada |
| México | Chave atribuída pelo banco de origem |
| Peru | Número curto — não há garantia de exclusividade |

Não trate `tracking.id` como sendo universalmente único em todos os trilhos. Use-o como o principal identificador junto aos trilhos para a Colômbia Bre-B; para outros países, considere-o como uma referência complementar.

### `tracking.reference`

Também gerado pelo trilho ou pelo banco. Seu conteúdo e disponibilidade variam:

* **Argentina, Chile, Colômbia**: espelha `tracking.id`.
* **México (SPEI/TEF)**: uma referência bancária mais curta que o pagador insere no momento da transferência.
* **Peru**: pode estar vazio ou conter `"NO REF"`.

Não confie em `tracking.reference` como um identificador garantido ou único.

### `tracking.concept`

Este campo destina-se a conter a descrição do pagamento. Na prática, frequentemente contém sequências de caracteres geradas pelo sistema ou marcadores de posição, em vez de texto livre do pagador:

| País | Valor típico |
| - | - |
| Chile | `"Sin mensaje"` |
| Colômbia (Bre-B) | `"Transfer via BRE-B"` (gerado por trilho) |
| Peru | `"payin generated by virtual account"` |

Não use `tracking.concept` como campo-chave nem presuma que ele contenha texto livre inserido pelo pagador. Trate-o apenas como contexto suplementar.

***

## Específico para cada país

Ao usar Contas Virtuais, existem detalhes importantes específicos de cada país que você deve considerar. Esses detalhes podem afetar a forma como as notificações de pagamento são processadas e como você concilia as transações. Abaixo, segue um resumo das diferenças conhecidas em alguns mercados:

<table>
  <thead>
    <tr>
      <th>
        País / Método de pagamento
      </th>

      <th>
        Considerações sobre Webhooks
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **Costa Rica (SINPE)**
      </td>

      <td>
        * O campo `tracking.concept` contém a descrição inserida pelo pagador no momento da transferência. Esse valor pode ser **truncado pelo banco de origem**, e é por isso que você pode ver sublinhados no final (por exemplo, `"Steph_test_____"`).
      </td>
    </tr>

    <tr>
      <td>
        **Colômbia (Bre-B)**
      </td>

      <td>
        * `paymentMethod.code` é sempre `"2006"` para pagamentos da conta virtual Bre-B.
        * `payer.bank.account.type` é sempre `"BREB"` — confirma que o pagador enviou fundos através da rede Bre-B.
        * `beneficiary.bank.account.type` é sempre `"KEY"` — a chave Bre-B receptora atribuída à sua Conta Virtual.
        * A Bre-B liquida os pagamentos em tempo real: o único status de pagamento é `"200" COMPLETED`. Não existem estados intermediários.
        * `tracking.id` e `tracking.reference` contêm o ID da transação da rede Bre-B — use-os como referência oficial para a reconciliação.
        * `tracking.concept` pode conter uma descrição inserida pelo pagador, mas geralmente contém uma sequência gerada pelo sistema (por exemplo, `"Transfer via BRE-B"`). Não o trate como texto livre garantidamente inserido pelo pagador.
      </td>
    </tr>

    <tr>
      <td>
        **México (SPID)**
      </td>

      <td>
        * As transferências SPID estão **disponíveis exclusivamente para empresas pagadoras**.
        * O campo `externalId` corresponde à **chave de rastreamento (Clave de Rastreo)** atribuída pelo Banco de México.
        * Usar `externalId` como referência autorizada para a reconciliação.
      </td>
    </tr>

    <tr>
      <td>
        **Peru**
      </td>

      <td>
        * Algumas instituições financeiras **não** informam o nome completo do pagador. Para mais detalhes, consulte: [Instituições financeiras sem disponibilidade do nome completo do pagador](#financial-institutions-without-payer-full-name-availability).
      </td>
    </tr>
  </tbody>
</table>

### Instituições financeiras sem disponibilidade do nome completo do pagador

* **Peru**: Algumas instituições financeiras peruanas não fornecem o nome completo do pagador nos detalhes da transação. Como essa informação não está disponível nos dados de liquidação enviados por essas entidades, você pode não conseguir identificar corretamente o pagador.

> [accordion] Lista de Instituições Financeiras
>
> * 007 – CITIBANK DEL PERU S.A.
> * 056 – BANCO SANTANDER PERU S.A.
> * 805 – CAJA MUNICIPAL DE AHORRO Y CRÉDITO SULLANA
> * 813 – CAJA MUNICIPAL DE AHORRO Y CRÉDITO TACNA

***

## Lidando com a notificação

Seu servidor deve processar cada notificação da seguinte forma:

1. **Verifique a assinatura da solicitação**.
2. **Valide o **`internalId`** ou **`externalId` para garantir a idempotência; nunca processe a mesma notificação duas vezes.
3. **Atualize seu sistema** para marcar a fatura, carteira ou pedido correspondente como pago.
4. **Retorne **`HTTP 200 OK` para confirmar o recebimento.

***

## Confirmação do recebimento da notificação

O Localpayment considera que o webhook foi entregue com sucesso somente quando o seu servidor responde com:

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
HTTP/1.1 200 OK
Content-Type: application/json
```

Caso não seja recebida nenhuma confirmação, o Localpayment tenta reenviar a notificação várias vezes, com intervalos cada vez maiores.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.