Webhooks are a powerful feature that allows you to receive real-time notifications about events happening in your LocalPayment account. By configuring webhooks, you can automate workflows, update your systems, and stay informed about transactions, payouts, and other important activities without manually polling the API.
These messages contain data about specific events, such as:
- Successful or failed transactions.
- Changes in payout status.
- Account updates or errors.
Setting Up Webhooks
To start receiving webhook notifications, follow these steps:
- Configure Your Webhook Endpoint:
- Provide a secure URL (HTTPS) where LocalPayment can send notifications. Ensure your endpoint can handle POST requests and parse JSON payloads.
- Enable Webhooks in LocalPayment:
- Log in to your LocalPayment account.
- Navigate to the Notifications section in the dashboard.
- Enter your webhook URL and select the events you want to subscribe to.
- Verify the Webhook:
- LocalPayment will send a test notification to your endpoint to verify its functionality.
- Your server must respond with a
200 OKstatus to confirm successful setup.
- Handle Notifications
- Once configured, LocalPayment will send real-time notifications to your endpoint whenever subscribed events occur.
- Process the data and update your systems accordingly.
Webhook Security
To ensure the authenticity of webhook notifications, LocalPayment includes a signature in the request headers. Verify this signature using your API secret key to confirm that the notification came from LocalPayment.
Example of Signature Verification:
{
"headers": {
"X-LocalPayment-Signature": "sha256=abc123..."
},
"body": {
"event": "transaction.completed",
"data": { ... }
}
}Example Webhook Payloads
Example of a payin cash webhook:
{
"transactionType": "PayIn",
"transactionFlow": null,
"data": {
"transactionType": "PayIn",
"externalId": "11111111",
"internalId": "cfb68f11-b111-1111-1ce1-11a1xxff111b",
"paymentMethod": {
"type": "Cash",
"code": "1602",
"flow": "DIRECT"
},
"country": "MEX",
"currency": "MXN",
"amount": 500.0,
"accountNumber": "111.111.00000022",
"confirmed": {
"currency": "MXN",
"fxQuote": 0.0,
"amount": 0.0
},
"payment": {
"currency": "MXN",
"fxQuote": 0.0,
"financingFee": 0.0,
"amount": 0.0
},
"localTaxes": [],
"withHoldings": [],
"fees": {
"description": "Fee",
"currency": "MXN",
"fxSource": 0.000,
"fxQuote": 0.0,
"amount": 0.6,
"account": "111.111.00000022"
},
"status": {
"code": "200",
"description": "COMPLETED",
"detail": "The payin was credited"
},
"ticket": {
"id": "pi_0N0XGyG0II6I0x000hWbTd0k",
"image": "https://api.v3.localpayment.com/api/images/Code128C/11001113235262120230512011200011",
"barcode": "11002073231111110110111011100011",
"expirationDate": "2023-05-12T22:38:44Z"
},
"merchant": {
"type": "COMPANY",
"name": "Odreval Limited",
"lastname": "",
"document": {
"type": "",
"id": ""
},
"email": "[email protected]"
},
"payer": {
"type": "INDIVIDUAL",
"name": "Valeria",
"lastname": "Perez",
"email": "[email protected]",
"phone": {
"countryCode": "1",
"areaCode": "11",
"number": "+522231039010"
},
"address": {
"street": "",
"number": "1",
"city": "",
"state": "AG",
"country": "MEX",
"zipCode": ""
}
},
"intermediaries": [],
"date": {
"creationDate": "2023-05-05T22:38:41Z",
"processedDate": "2023-05-05T22:38:46Z",
"expirationDate": "2023-05-12T22:38:44Z"
},
"errors": []
}
}Example of a payin bank transfer webhook:
{
"transactionType": "PayIn",
"transactionFlow": null,
"data": {
"transactionType": "PayIn",
"externalId": "XXXXX",
"internalId": "XXXXX",
"paymentMethod": {
"type": "BankTransfer",
"code": "1027",
"flow": "direct"
},
"country": "ARG",
"currency": "ARS",
"amount": 7000,
"accountNumber": "XXXXX",
"confirmed": {
"currency": "ARS",
"fxQuote": 1,
"amount": 7000
},
"payment": {
"currency": "ARS",
"fxQuote": 1,
"financingFee": 0,
"amount": 7000
},
"localTaxes": [
{
"code": "0001",
"percentage": 1.2,
"description": "IDC",
"currency": "ARS",
"fxSource": 221.515899,
"fxQuote": 0,
"amount": 84,
"account": "XXXXX"
}
],
"withHoldings": [],
"fees": {
"description": "Fee",
"currency": "ARS",
"fxSource": 221.515899,
"fxQuote": 1,
"amount": 200,
"account": "XXXXX"
},
"status": {
"code": "200",
"description": "COMPLETED",
"detail": "The payin was credited"
},
"merchant": {
"type": "COMPANY",
"name": "Merchant name",
"lastname": "Merchant lastname",
"document": {
"type": "XXXXX",
"id": "XXXXX"
},
"email": "[email protected]"
},
"payer": {
"type": "INDIVIDUAL",
"name": "Payer name",
"lastname": "Payer lastname",
"document": {
"type": "XXXXX",
"id": "XXXXX"
},
"email": "[email protected]",
"bank": {
"name": "Payer fullname",
"code": "007",
"account": {
"type": "C",
"number": "XXXXX"
}
}
},
"intermediaries": [],
"wireInstructions": {
"beneficiary": {
"name": "LOCALPAYMENT SRL",
"document": {
"type": "CUIT",
"id": "30716132028"
},
"bank": {
"name": "BANCO BICA",
"code": "0055",
"branch": {},
"account": {
"type": "C",
"number": "4260004000100091408087"
}
}
},
"referenceCode": "ZSS9-S6W5-S6N5"
},
"date": {
"creationDate": "2023-05-01T00:47:05Z",
"processedDate": "2023-05-01T00:47:06Z",
"expirationDate": "2023-05-08T00:47:06Z"
},
"errors": []
}
}Best Practices for Using Webhooks
- Use HTTPS: Always secure your webhook endpoint with HTTPS to protect sensitive data.
- Verify Signatures: Validate the
X-Signatureheader to ensure notifications are from LocalPayment. - Handle Retries: LocalPayment may retry failed webhook deliveries. Ensure your endpoint is idempotent to avoid duplicate processing.
- Monitor Logs: Keep track of incoming webhooks and errors to troubleshoot issues quickly.
- Test in Sandbox: Use LocalPayment’s sandbox environment to test your webhook implementation before going live.