Payment Webhooks

Payment webhooks provide real-time notifications about payment events that occur between FarPay and payment service providers (card providers, MobilePay, NETS, etc.). These webhooks enable you to track payment status changes and respond immediately to payment events.

Overview

Payment webhooks are triggered by events in the FarPay core system and provide detailed information about:

• Payment success or failure
• Customer cancellations
• Bank rejections and reimbursements
• Refund processing
• Payment method changes

Payment Events

Payment Types

Webhook Payload Structure

JSON Format (POST)

{
  "Type": "Payment",
  "Event": "Succeeded",
  "InvoiceNumber": "1234567BAVV",
  "CustomerNumber": "66776655",
  "PaymentDueDate": "2023-02-15",
  "Currency": "DKK",
  "InvoiceAmount": "1215.0000",
  "Amount": "1125.0000",
  "PaymentType": "LS",
  "PaymentReference": "ABC123-Reference",
  "AgreementId": "1234"
}

XML Format (POST)

<Payment>
  <Type>Payment</Type>
  <Event>Succeeded</Event>
  <InvoiceNumber>1234567BAVV</InvoiceNumber>
  <CustomerNumber>66776655</CustomerNumber>
  <PaymentDueDate>2023-02-15</PaymentDueDate>
  <Currency>DKK</Currency>
  <InvoiceAmount>1215.0000</InvoiceAmount>
  <Amount>1125.0000</Amount>
  <PaymentType>LS</PaymentType>
  <PaymentReference>ABC123-Reference</PaymentReference>
  <AgreementId>1234</AgreementId>
</Payment>

URL Parameters (GET)

https://yourdomain.com/webhook?Type=Payment&Event=Succeeded&PaymentReference=ABC123-Reference&InvoiceNumber=1234567BAVV&CustomerNumber=66776655&PaymentDueDate=2023-02-15&Currency=DKK&InvoiceAmount=1215.000&Amount=1215.000&PaymentType=LS

Payload Properties

Special Event Types

RejectedByCustomer (230)

Occurs when a customer rejects a scheduled payment through their online bank.

Payload Example

{
  "Type": "Payment",
  "Event": "RejectedByCustomer",
  "InvoiceNumber": "12345678abcnnn",
  "CustomerNumber": "abc123",
  "PaymentDueDate": "2023-07-01",
  "Currency": "DKK",
  "InvoiceAmount": "123.1234",
  "Amount": "123.1234",
  "PaymentType": "BS",
  "PaymentReference": "",
  "AgreementId": ""
}

Payment Type Behavior

BS Rejection Examples

Before bank transfer:

{
  "Type": "Payment",
  "Event": "RejectedByCustomer",
  "InvoiceNumber": "234-cvcv-445673",
  "CustomerNumber": "123123123123",
  "PaymentDueDate": "2023-07-01",
  "Currency": "DKK",
  "InvoiceAmount": "750.9900",
  "Amount": "0.0000",
  "PaymentType": "BS",
  "PaymentReference": "",
  "AgreementId": ""
}

After bank transfer:

{
  "Type": "Payment",
  "Event": "RejectedByCustomer",
  "InvoiceNumber": "234-cvcv-445673",
  "CustomerNumber": "123123123123",
  "PaymentDueDate": "2023-07-01",
  "Currency": "DKK",
  "InvoiceAmount": "750.9900",
  "Amount": "750.9900",
  "PaymentType": "BS",
  "PaymentReference": "",
  "AgreementId": ""
}

ReimbursedByBank (240)

Occurs when a financial institution cancels a payment and transfers money back to the customer.

Payload Example

{
  "Type": "Payment",
  "Event": "ReimbursedByBank",
  "InvoiceNumber": "234-cvcv-445673",
  "CustomerNumber": "123123123123",
  "PaymentDueDate": "2023-07-01",
  "Currency": "DKK",
  "InvoiceAmount": "750.9900",
  "Amount": "750.9900",
  "PaymentType": "BS",
  "PaymentReference": "",
  "AgreementId": "12345"
}

Direct Debit Behavior

Best Practices

1. Event Handling

• Handle all event types - Don't ignore events you don't expect
• Log all events - Keep detailed logs for debugging and audit
• Process asynchronously - Use queues for heavy processing
• Implement idempotency - Handle duplicate webhooks gracefully

2. Data Validation

• Validate required fields - Check all required properties
• Verify data types - Ensure amounts are numeric, dates are valid
• Check business logic - Validate amounts match expectations
• Handle edge cases - Account for zero amounts, missing references

3. Error Handling

• Always return 200 - Acknowledge webhook receipt
• Log errors - Keep detailed error logs
• Graceful degradation - Continue processing other events
• Monitor failures - Set up alerts for processing errors

4. Security

• Verify webhook origin - Use checksums when available
• Validate data integrity - Check for tampering
• Use HTTPS - Secure all webhook endpoints
• Rate limiting - Prevent abuse of your endpoints

Testing

Test Scenarios

1. Payment success - Verify correct processing of successful payments
2. Payment failure - Test handling of failed payments
3. Customer rejection - Test rejection scenarios
4. Bank reimbursement - Test reimbursement handling
5. Refund processing - Test refund event handling
6. Invalid data - Test error handling with malformed data
7. Duplicate webhooks - Test idempotency

Test Data Examples

// Successful payment
{
  "Type": "Payment",
  "Event": "Succeeded",
  "InvoiceNumber": "TEST-001",
  "CustomerNumber": "CUST-001",
  "PaymentDueDate": "2023-12-31",
  "Currency": "DKK",
  "InvoiceAmount": "100.0000",
  "Amount": "100.0000",
  "PaymentType": "Visa",
  "PaymentReference": "TEST-REF-001",
  "AgreementId": "AGREE-001"
}

// Failed payment
{
  "Type": "Payment",
  "Event": "Failed",
  "InvoiceNumber": "TEST-002",
  "CustomerNumber": "CUST-002",
  "PaymentDueDate": "2023-12-31",
  "Currency": "DKK",
  "InvoiceAmount": "200.0000",
  "Amount": "0.0000",
  "PaymentType": "Visa",
  "PaymentReference": "TEST-REF-002",
  "AgreementId": "AGREE-002"
}

Related Documentation

• Webhooks Overview - General webhook information
• Agreement Webhooks - Agreement lifecycle events
• Order Webhooks - Order status tracking
• API Documentation - Main API documentation