> ## 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.

# Recibir notificaciones de pago

Recibe notificaciones instantáneas mediante webhook para cada pago de Cuenta Virtual, y actualiza tus sistemas y confirma los créditos automáticamente.

Una vez que crees una cuenta virtual y la asocies a un cliente o factura específicos dentro de tus sistemas internos, Localpayment enviará automáticamente una notificación webhook a tu servidor cada vez que se reciba un pago correctamente en esa cuenta.

**Importante**: Una cuenta virtual funciona como destino de pago exclusivo. Si bien tú gestionas tu atribución interna, el número de cuenta puede recibir fondos de cualquier pagador. La notificación de pago incluirá los detalles del pagador real, lo que te permitirá conciliar el pago con tu registro interno de clientes.

Estas notificaciones en tiempo real te permiten confirmar automáticamente los créditos, actualizar los saldos y conciliar los pagos sin necesidad de verificación manual.

***

## Antes de comenzar

Asegúrate de tener:

* Se ha creado correctamente una cuenta virtual a través del endpoint [Crear cuenta virtual](https://docs.localpayment.com/es/reference/create-virtual-account.md).
* Un endpoint de notificación (URL de webhook) configurado en tu cuenta de comerciante.
* La capacidad de recibir solicitudes HTTPS POST desde los servidores de Localpayment.
* Lógica en tu sistema backend para validar y analizar de forma segura las cargas útiles de los webhooks.

***

## Cómo funciona

1. El pagador envía una transferencia al número de cuenta virtual generado previamente por tu sistema.
2. Una vez que Localpayment acredite y valide los fondos, se enviará una notificación de Payin al endpoint de webhook configurado.
3. Tu sistema debe confirmar la notificación con una respuesta 200 OK.
4. A continuación, puedes actualizar tus registros internos para marcar la Cuenta Virtual como pagada o el pedido correspondiente como completado.

> [!NOTE]
>
> ###
>
> Localpayment garantiza la entrega mediante reintentos con retroceso exponencial si tu servidor no responde con HTTP 200.

***

## Ejemplo de notificación (carga útil del webhook)

A continuación se muestra un ejemplo de la carga útil de un pago exitoso acreditado a una cuenta 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 coincidencia

La notificación del webhook contiene campos específicos que sirven como identificadores. Utiliza la tabla a continuación para cotejar el pago recibido con tus registros internos.

| Campo | Descripción |
| - | - |
| `accountNumber` | Número de cuenta del comerciante. |
| `amount` | Cantidad recibida. |
| `payer.name ` y  `payer.lastName` | Nombre completo del pagador. |
| `payer.document.id` | Documento nacional de identidad del pagador (si está disponible). |
| `payer.bank.account.number` | Número de cuenta de origen utilizado por el pagador. |
| `beneficiary.name` y `beneficiary.document.id` | Nombre e identificación del titular de la cuenta virtual. |
| `beneficiary.bank.account.number` | Número de cuenta local de la cuenta virtual que recibió el pago (CVU para Argentina, CLABE para México, CCI para Perú, etc.). Utiliza este campo para vincular el pago recibido con la cuenta virtual específica en tus registros. |
| `referenceCode` | Una referencia generada por Localpayment en el formato `XXXX-XXXX-XXXX` (tres bloques alfanuméricos de cuatro caracteres). Úsalo solo como referencia legible por humanos. Para idempotencia y deduplicación, utiliza `internalId` o `externalId`. |
| `tracking.id` | Identificador generado por la plataforma de pago o el banco del pagador. El formato varía según el país. Para Colombia Bre-B, esta es la referencia de conciliación autorizada. |
| `tracking.reference` | También generado por la plataforma de pago o el banco. No se garantiza su presencia ni su unicidad entre plataformas. En México, se trata de una referencia bancaria más corta ingresada por el pagador; en Perú, puede estar vacía. |
| `tracking.concept` | Su función es incluir la descripción del pago. A menudo contiene cadenas generadas por el sistema en lugar de texto libre del pagador. Úsalo únicamente como contexto complementario. |
| `date.creationDate` and `date.processedDate` | El objeto `date` proporciona las marcas de tiempo UTC que rastrean la transacción desde su creación en el sistema (`creationDate`) hasta su liquidación financiera final (`processedDate`). |

## Uso de referencias de pago

Los pagadores pueden agregar una referencia (por ejemplo, un número de pedido) a su transferencia. Estos datos aparecen en el objeto `tracking` del webhook para coincidencia directa.

> [!WARNING]
>
> ###
>
> **Importante**
>
> * **Disponibilidad:** El objeto `tracking` **solo está disponible en los webhooks**, no en los informes de transacciones ni en la API.
> * Para **México (SPID)**, el `externalId` corresponde a la clave de seguimiento del Banco de México (Clave de Rastreo), lo que lo convierte en el campo autorizado para la conciliación.

### Ejemplo del objeto tracking

```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 clave en la notificación

La notificación incluye varios campos de referencia y seguimiento generados por diferentes partes. Comprender el origen y la fiabilidad de cada uno te ayudará a desarrollar una estrategia de conciliación fiable.

### referenceCode

Generado por Localpayment. Siempre sigue el formato `XXXX-XXXX-XXXX` — tres bloques alfanuméricos de cuatro caracteres — en todos los países y plataformas de pago, lo que confirma que la notificación se originó en Localpayment.

`referenceCode` es una referencia de Localpayment legible por humanos, no una clave de idempotencia. Para la deduplicación y la idempotencia, utiliza `internalId` o `externalId`.

### tracking.id

Generado por la plataforma de pago o el banco del pagador, no por Localpayment. El formato varía según el país:

| País | Formato |
| - | - |
| Argentina | Clave alfanumérica larga (por ejemplo, `7L8GYKNXWJELWYGP2MPRZ5`) |
| Brasil (PIX) | Número E (por ejemplo, `E0000000022250417170028008753346`) |
| Chile | Numérico corto (por ejemplo, `000739531483`) |
| Colombia (Bre-B) | ID de transacción de la red Bre-B: referencia de conciliación autorizada |
| México | Clave asignada por el banco de origen |
| Perú | Número corto — no se garantiza que sea único |

No trates `tracking.id` como único universal en todos los medios de pago. Úsalo como identificador principal del medio de pago para Colombia Bre-B; para otros países, trátalo como referencia complementaria.

### `tracking.reference`

También generado por la plataforma de pago o el banco. Su contenido y disponibilidad varían:

* **Argentina, Chile, Colombia**: refleja `tracking.id`.
* **México (SPEI/TEF)**: una referencia bancaria más corta que el pagador ingresa al momento de la transferencia.
* **Perú**: puede estar vacío o contener `"NO REF"`.

No confíes en `tracking.reference` como identificador garantizado o único.

### `tracking.concept`

Diseñado para contener la descripción del pago. En la práctica, este campo suele contener cadenas generadas por el sistema o marcadores de posición en lugar de texto libre del pagador:

| País | Valor típico |
| - | - |
| Chile | `"Sin mensaje"` |
| Colombia (Bre-B) | `"Transfer via BRE-B"` (generado por la plataforma de pago) |
| Perú | `"payin generated by virtual account"` |

No usar `tracking.concept` como un campo clave o asumir que contiene texto libre ingresado por el pagador. Trátalo únicamente como contexto complementario.

***

## Específico del país

Al usar cuentas virtuales, es importante tener en cuenta detalles específicos de cada país. Estos pueden afectar el procesamiento de las notificaciones de pago y la conciliación de las transacciones. A continuación, se presenta un resumen de las diferencias conocidas en ciertos mercados:

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

      <th>
        Consideraciones sobre los webhooks
      </th>
    </tr>
  </thead>

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

      <td>
        * El campo `tracking.concept` contiene la descripción ingresada por el pagador en el momento de la transferencia. Este valor puede ser **truncado por el banco originador**, razón por la cual puedes ver guiones bajos al final (por ejemplo, `"Steph_test_____"`).
      </td>
    </tr>

    <tr>
      <td>
        **Colombia (Bre-B)**
      </td>

      <td>
        * `paymentMethod.code` siempre es `"2006"` para pagos de la cuenta virtual Bre-B.
        * `payer.bank.account.type` siempre es `"BREB"` — confirma que el pagador envió los fondos a través de la red Bre-B.
        * `beneficiary.bank.account.type` siempre es `"KEY"` — la llave Bre-B receptora asignada a tu cuenta virtual.
        * Bre-B liquida en tiempo real: el único estado de pago es `"200" COMPLETED`. No existen estados intermedios.
        * `tracking.id` y `tracking.reference` contienen el ID de transacción de la red Bre-B; utilízalos como referencia autorizada para la conciliación.
        * `tracking.concept` puede contener una descripción ingresada por el pagador, pero a menudo lleva una cadena generada por el sistema (por ejemplo, `"Transfer via BRE-B"`). No lo trates como texto libre ingresado por el pagador garantizado.
      </td>
    </tr>

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

      <td>
        * Las transferencias SPID están disponibles **exclusivamente para los pagadores de la empresa**.
        * El campo `externalId` corresponde a la **clave de seguimiento (Clave de Rastreo)** asignada por el Banco de México.
        * Usar `externalId` como referencia autorizada para la reconciliación.
      </td>
    </tr>

    <tr>
      <td>
        **Perú**
      </td>

      <td>
        * Algunas entidades financieras **no** facilitan el nombre completo del pagador. Para más detalles, consulta: [Instituciones financieras sin disponibilidad del nombre completo del pagador](#financial-institutions-without-payer-full-name-availability).
      </td>
    </tr>
  </tbody>
</table>

### Instituciones financieras sin disponibilidad del nombre completo del pagador

* **Perú**: Algunas instituciones financieras peruanas no proporcionan el nombre completo del pagador en los detalles de la transacción. Debido a que esta información no está disponible en los datos de liquidación que envían estas entidades, es posible que no puedas identificar correctamente al pagador.

> [accordion] Lista de instituciones financieras
>
> * 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

***

## Gestión de la notificación

Tu servidor debe procesar cada notificación de la siguiente manera:

1. **Verifica la firma de la solicitud**.
2. **Validar el **`internalId`** o **`externalId` para garantizar la idempotencia; nunca proceses la misma notificación dos veces.
3. **Actualiza tu sistema** para marcar la factura, la billetera o el pedido correspondiente como pagado.
4. **Devolver **`HTTP 200 OK` para acusar recibo.

***

## Acuse de recibo de la notificación

Localpayment considera que el webhook se ha entregado correctamente solo cuando tu servidor responde con:

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

Si no se recibe ninguna confirmación, Localpayment vuelve a intentar enviar la notificación varias veces con intervalos cada vez mayores.


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