Order Webhooks

Order webhooks provide real-time notifications about order status changes that occur in the FarPay PaymentWindow when users interact with payment forms and commit data.

Overview

Order webhooks are triggered by events in the FarPay PaymentWindow and provide detailed information about:

• Order creation and initialization
• Payment form interactions
• Customer number processing
• Order completion status

These webhooks enable you to track the progress of payment orders and respond to user interactions in real-time.

Order Events

Event Flow

New (300) → PendingPayment (310) → PendingCustomerNumber (320) → Order Completed (330)

Event Details

New (300)

• Trigger: Order request created via API
• Context: Initial order setup
• Action: Prepare for payment processing

PendingPayment (310)

• Trigger: User commits agreement information (direct debit, card details, etc.)
• Context: Agreement established, ready for payment
• Action: User proceeds to payment form or MobilePay

PendingCustomerNumber (320)

• Trigger: User completes agreement and initial payment
• Context: Order created without customer present
• Action: System waits for customer number assignment

Order Completed (330)

• Trigger: Order successfully finalized
• Context: All required information provided
• Action: Order ready for processing

Webhook Payload Structure

JSON Format (POST)

{
  "Order": {
    "Token": "Token123ABC",
    "OrderEvent": "New",
    "ExternalId": "REF99102933C",
    "Created": "2018-05-02",
    "CustomerNumber": "2",
    "Checksum": "KJVDDNDKJNAURINDSKJDVNSKJD"
  }
}

XML Format (POST)

<Order>
  <Token>Token123ABC</Token>
  <OrderEvent>New</OrderEvent>
  <ExternalId>REF99102933C</ExternalId>
  <Created>2018-05-02</Created>
  <CustomerNumber>2</CustomerNumber>
  <Checksum>KJVDDNDKJNAURINDSKJDVNSKJD</Checksum>
</Order>

URL Parameters (GET)

https://yourdomain.com/webhook?Token=Token123ABC&OrderEvent=New&ExternalId=REF99102933C&Created=2018-05-02&CustomerNumber=2

GET url parameters

Payload Properties

Security Considerations

For security reasons, order webhooks provide limited information:

• User input details are saved in secured environments (PCI DSS for card information)
• Sensitive data is not included in webhooks
• Checksum verification is available for message integrity
• Token-based identification is used for order tracking

Best Practices

1. Event Handling

• Track order progress - Monitor all status changes
• Validate transitions - Ensure status changes are valid
• Handle edge cases - Account for unexpected status changes
• Log all events - Keep detailed logs for debugging

2. Order Management

• Maintain order state - Keep track of order status in your system
• Handle timeouts - Implement timeout handling for pending states
• Handle failed processing - Implement error handling for failed orders
• Customer assignment - Manage customer number assignment

3. Security

• Verify checksums - Validate webhook integrity
• Token validation - Verify order tokens
• Access control - Restrict webhook endpoint access
• Rate limiting - Prevent abuse

4. Integration

• Sync with payment webhooks - Coordinate with payment events
• Update customer records - Keep customer information current
• Trigger business processes - Automate order fulfillment
• Monitor performance - Track order processing times

Testing

Test Scenarios

1. Order creation - Test new order handling
2. Status transitions - Test all status change scenarios
3. Payment pending - Test payment processing states
4. Customer number assignment - Test customer assignment
5. Order completion - Test completion handling
6. Invalid transitions - Test error handling
7. Checksum verification - Test security validation

Test Data Examples

// New order
{
  "Order": {
    "Token": "TOKEN-001",
    "OrderEvent": "New",
    "ExternalId": "EXT-001",
    "Created": "2023-12-31",
    "CustomerNumber": "CUST-001",
    "Checksum": "abc123checksum"
  }
}

// Payment pending
{
  "Order": {
    "Token": "TOKEN-001",
    "OrderEvent": "PendingPayment",
    "ExternalId": "EXT-001",
    "Created": "2023-12-31",
    "CustomerNumber": "CUST-001",
    "Checksum": "def456checksum"
  }
}

// Order completed
{
  "Order": {
    "Token": "TOKEN-001",
    "OrderEvent": "Order Completed",
    "ExternalId": "EXT-001",
    "Created": "2023-12-31",
    "CustomerNumber": "CUST-001",
    "Checksum": "ghi789checksum"
  }
}


## Related Documentation

- [Webhooks Overview](webhooks.md) - General webhook information
- [Payment Webhooks](payment-webhooks.md) - Payment event notifications
- [Agreement Webhooks](agreement-webhooks.md) - Agreement lifecycle events
- [API Documentation](../README.md) - Main API documentation