# 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                   | Value | Description                                                                              |
| ----------------------- | ----- | ---------------------------------------------------------------------------------------- |
| `New`                   | 300   | Order request created from the API                                                       |
| `PendingPayment`        | 310   | User has committed agreement information and is about to enter initial payment           |
| `PendingCustomerNumber` | 320   | User has input agreement details and initial payment, system waiting for customer number |
| `Order Completed`       | 330   | Order was successfully completed                                                         |

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

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

### XML Format (POST)

```xml
<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

| Property         | Type   | Description            | Format                |
| ---------------- | ------ | ---------------------- | --------------------- |
| `Token`          | string | Order token identifier | Alphanumeric          |
| `OrderEvent`     | string | Order event type       | See Event table above |
| `ExternalId`     | string | External reference ID  | Alphanumeric          |
| `Created`        | string | Order creation date    | YYYY-MM-DD            |
| `CustomerNumber` | string | Customer identifier    | Alphanumeric          |
| `Checksum`       | string | Security checksum      | Alphanumeric          |

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

```json
// 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
```