Receive Payment Notifications

Once a Virtual Account has been created and assigned to a payer, Localpayment automatically sends a webhook notification to your server each time a payment is successfully received in that account. These notifications allow you to confirm credits in real time, update balances, and reconcile payments on your system without manual verification.

Before You Begin

Ensure that you have:

Successfully created a Virtual Account through the Create Virtual Account endpoint.
A notification endpoint (webhook URL) configured in your merchant account.
The ability to receive HTTPS POST requests from Localpayment’s servers.
Logic in your backend to validate and parse webhook payloads securely.

How It Works

A payer sends a transfer to the Virtual Account number previously generated by your system.
Once the funds are credited and validated by Localpayment, a PayIn notification is sent to your configured webhook endpoint.
Your system must acknowledge the notification with a 200 OK response.
You can then update your internal records to mark the Virtual Account as paid or the corresponding order as fulfilled.

📘
Localpayment guarantees delivery using retries with exponential backoff if your server does not respond with HTTP 200.

Example Notification (Webhook Payload)

Below is a sample payload for a successful payment credited to a Virtual Account:

{
  "transactionType": "PayIn",
  "externalId": "{{externalId}}",
  "internalId": "{{internalId}}",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1630",
    "flow": "DIRECT"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{YourAccountNumber}}",
  "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": "{{YourAccountNumber}}"
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "The payin was credited"
  },
  "beneficiary": {
    "type": "INDIVIDUAL",
    "name": "Pedro",
    "lastName": "Perez",
    "document": {
      "type": "RFC",
      "id": "LEKF8111118Z5"
    },
    "bank": {
      "account": {
        "number": "646011319800015054"
      }
    },
    "informedName": "LPV3_PayinVA"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "MerchantName"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "José",
    "lastName": "Sandoval",
    "document": {
      "type": "ND",
      "id": "ND"
    },
    "email": "NA",
    "bank": {
      "name": "Sistema de Transferencias y Pagos",
      "code": "646",
      "branch": {},
      "account": {
        "type": "C",
        "number": "646010319800001674"
      }
    }
  },
  "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"
  }
}

{
    "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": "484.484.00000058",
    "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": "484.484.00000060"
    },
    "status": {
        "code": "200",
        "description": "COMPLETED",
        "detail": "The payin was credited"
    },
    "beneficiary": {
        "type": "COMPANY",
        "name": "My Company",
        "document": {
            "type": "RUC",
            "id": "200123456789"
        },
        "bank": {
            "name": "HEY BANCO",
            "code": "167",
            "account": {
                "number": "000000000000000009"
            }
        },
        "informedName": "My Company"
    },
    "merchant": {
        "type": "COMPANY",
        "name": "Localpayment Test",
        "lastName": "Localpayment Test"
    },
    "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": "",
        "reference": "",
        "concept": "TESTTEFCOMP123"
    }
}

{
  "transactionType": "PayIn",
  "externalId": "TRANSFERENCIA-568GYKNXWJELWYGP2MPRZ5",
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "1025",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1.09,
  "accountNumber": "{{YourAccountNumber}}",
  "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": "{{YourAccountNumber}}"
    }
  ],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 1170.50002,
    "fxQuote": 1,
    "amount": 0,
    "account": "{{YourAccountNumber}}"
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "The payin was credited"
  },
  "beneficiary": {
    "type": "INDIVIDUAL",
    "name": "Jorge",
    "lastName": "Villagra",
    "document": {
      "type": "CUIT",
      "id": "20337994513"
    },
    "bank": {
      "account": {
        "number": "0000369600000000000161"
      }
    },
    "informedName": "Unknown"
  },
  "merchant": {
    "type": "INDIVIDUAL",
    "name": "Localpayment Test",
    "lastName": "Localpayment Test"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "LUCIANO GONZALEZ",
    "lastName": "LUCIANO GONZALEZ",
    "document": {
      "type": "CUIT",
      "id": "20448710913"
    },
    "email": "NA",
    "bank": {
      "name": "BANCO DE GALICIA Y BUENOS AIRES S.A.U.",
      "code": "007",
      "branch": {},
      "account": {
        "type": "C",
        "number": "0070055930004044938502"
      }
    }
  },
  "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"
  }
}

{
  "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": "{{YourAccountNumber}}",
  "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": "{{YourAccountNumber}}"
    }
  ],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "BRL",
    "fxSource": 5.80427174,
    "fxQuote": 1,
    "amount": 55.55,
    "account": "{{YourAccountNumber}}"
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "The payin was credited"
  },
  "beneficiary": {
    "type": "COMPANY",
    "name": "ACME",
    "lastName": "",
    "document": {
      "type": "",
      "id": ""
    },
    "bank": {
      "code": "450",
      "branch": {},
      "account": {
        "number": "52415985301",
        "alias": "cf226732-139c-4ec8-b672-8aa0fc7ee6ee",
        "aliases": [
          {
            "value": "cf406732-139c-4ec8-b672-8aa0fc7ee6ee"
          }
        ]
      }
    }
  },
  "merchant": {
    "type": "COMPANY",
    "name": "ACME"
  },
  "payer": {
    "type": "COMPANY",
    "name": "VIAGENS TOUR LTDA",
    "lastName": "",
    "document": {
      "type": "CNPJ",
      "id": "01932559000112"
    },
    "email": "[email protected]",
    "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"
  }
}

{
  "transactionType": "PayIn",
  "externalId": "{{externalId}}",
  "internalId": "326637dd-af0b-41e6-91ad-c1a4ac162d70",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "6100",
    "flow": "DIRECT"
  },
  "country": "PER",
  "currency": "PEN",
  "amount": 85.10,
  "accountNumber": "604.604.00000148",
  "confirmed": {
    "currency": "PEN",
    "fxQuote": 1,
    "amount": 85.10
  },
  "payment": {
    "currency": "PEN",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 85.10
  },
  "localTaxes": [
    {
      "code": "0018",
      "percentage": 18,
      "description": "TEST4",
      "currency": "PEN",
      "fxSource": 3.468017,
      "fxQuote": 0,
      "amount": 15.30,
      "account": "604.604.00000148"
    }
  ],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "PEN",
    "fxSource": 3.4750944,
    "fxQuote": 1,
    "amount": 20.90,
    "account": "604.604.00000148"
  },
  "status": {
    "code": "200",
    "description": "COMPLETED",
    "detail": "The payin was credited"
  },
  "beneficiary": {
    "bank": {
      "account": {
        "number": "92250610000000012345"
      }
    }
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Acme Inc."
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastName": "Doe",
    "email": "NA",
    "bank": {
      "name": "PREXPE",
      "code": "776",
      "branch": {},
      "account": {
        "type": "C",
        "number": "77600100000123456789"
      }
    }
  },
  "date": {
    "creationDate": "2025-10-01T22:25:14.107",
    "processedDate": "2025-10-01T22:25:14.429"
  },
  "errors": [],
  "referenceCode": "MDSS-T475-BEEM",
  "tracking": {
    "id": "2025100117250207764123456789",
    "reference": "043016551234",
    "concept": ""
  }
}

Please note that entity 009 – BANCO SCOTIABANK PERU does not have a full name available in Peru.

Key Response Fields

Field	Description
`transactionType`	Always `PayIn` for incoming Virtual Account payments.
`externalId`	A unique identifier for the transaction in your system. Set during payment initiation.
`internalId`	A unique identifier for the transaction in Localpayment’s system.
`amount`	Amount received in the destination currency.
`currency`	ISO 4217 currency code of the transaction.
`status`	Object with information about the status of the virtual account.
`status.code`	The status code (e.g., `200` for `Completed`).
`beneficiary`	Information about the Virtual Account holder.
`payer`	Information about the individual or entity that made the transfer.
`date.processedDate`	UTC timestamp when the payment was confirmed.

Handling the Notification

Your server must process each notification as follows:

Verify the request signature.
Validate the internalId or externalId to ensure idempotency — never process the same notification twice.
Update your system to mark the corresponding invoice, wallet, or order as paid.
Return HTTP 200 OK to acknowledge receipt.

Acknowledging the Notification

Localpayment considers the webhook successfully delivered only when your server responds with:

HTTP/1.1 200 OK
Content-Type: application/json

If no acknowledgment is received, Localpayment retries the notification up to several times with increasing intervals.