Skip to main content

Complete Payment Flow: From Checkout to Settlement​

This guide demonstrates the complete payment lifecycle with Walley, from checkout initialization to settlement. It shows you how to build a robust integration that handles every stage of a successful transaction.

Prerequisites​

Before implementing this flow, ensure you have:

Complete payment flow​

The full payment lifecycle involves five key phases, each with specific merchant-side integrations:

Choose your integration approach​

Choose how you'll receive order notifications and obtain the orderId for order management:

  • Approach A: Notification Callback - Simple callback integration. Receive privateId via GET request, then fetch orderId using Get Checkout Information API.
  • Approach B: Webhook Subscription - Event-driven integration. Receive orderId directly in webhook payload, no additional API call needed.

Both approaches support the same retry mechanism. See sections below for implementation details.

Phase 1: Purchase​

Create a checkout session to get a publicToken for rendering the checkout iframe and a privateId for order tracking.

Request:

POST /checkouts HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

{
  "storeId": 123,
  "countryCode": "SE",
  "reference": "ORDER-2024-12345",
  "merchantTermsUri": "https://example.com/terms",
  "notificationUri": "https://example.com/api/walley/notify",
  "cart": {
    "items": [
      {
        "id": "PROD-001",
        "description": "Wireless Headphones",
        "unitPrice": 999.00,
        "quantity": 1,
        "vat": 25.0
      }
    ]
  }
}

Response:

{
  "data": {
    "privateId": "6f4a9bc3-8d2e-4f1a-9b7c-3e8d2f1a9b7c",
    "publicToken": "public-SE-7f1b3d2a2a73d348dfbd17d3965ff1458c249f84c695eac1"
  }
}

Use publicToken to render the checkout iframe. See Initialize Checkout API for all options.

Phase 2: Receive Order Information​

Approach A: Notification Callback + Get Checkout Information​

Step 1: Receive notification

GET /api/walley/notify?privateId=6f4a9bc3-8d2e-4f1a-9b7c-3e8d2f1a9b7c HTTP/1.1
Host: example.com

Respond with 200 OK. See Notification Callback for details.

Step 2: Get Checkout Information

GET /checkouts/6f4a9bc3-8d2e-4f1a-9b7c-3e8d2f1a9b7c HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

Extract data.order.orderId from the response to use for order management. See Get Checkout Information API for complete response details

Approach B: Webhook Subscription (walley:order:created)​

Subscribe to walley:order:created event in Merchant Hub to receive orderId directly in webhook payload - no additional API call needed.

Example webhook payload:

{
  "Type": "walley:order:created",
  "Timestamp": "2024-12-04T15:02:42.5997621+01:00",
  "Payload": {
    "OrderId": "7890abcd-ef12-3456-7890-abcdef123456",
    "Reference": "ORDER-2024-12345",
    "Amount": 1250.00,
    "Currency": "SEK",
    "Status": "Authorized"
  }
}

See Webhooks Overview and Webhooks for Orders for implementation details.

Phase 3: Capture Payment​

When order items are ready to be delivered, capture the payment to finalize the transaction and transfer funds. This can only be done on orders with status NotActivated or PartActivated.

When to execute: When goods are shipped or services are delivered.

Eventual Consistency

The system is eventually consistent. If you attempt to capture payment immediately after receiving the order notification, you may encounter 404 Not Found or 403 Forbidden status codes. Implement retry logic with exponential backoff to handle these transient states while the order becomes fully available.

Basic capture request:

POST /orders/7890abcd-ef12-3456-7890-abcdef123456/captures HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
Content-Type: application/json

{
  "amount": 1248.00,
  "actionReference": "SHIP-2024-12345",
  "items": [
    {
      "id": "PROD-001",
      "description": "Wireless Headphones",
      "unitPrice": 999.00,
      "quantity": 1,
      "vat": 25.0
    },
    {
      "id": "SHIP-001",
      "description": "Standard Shipping",
      "unitPrice": 49.00,
      "quantity": 1,
      "vat": 25.0
    }
  ]
}

Response:

Status: 202 Accepted
Location: /manage/orders/7890abcd-ef12-3456-7890-abcdef123456

Key points:

  • Capture full order or partial amounts (e.g., only shipped items)
  • Only captured amounts are settled to your account
  • Response is 202 Accepted - processing is asynchronous
  • Multiple partial captures are supported

For detailed information including partial capture, capture by amount, replacing items, and error handling, see Capture Order API documentation.

Phase 4: Refund Management​

Refunds can only be issued against captured amounts. When a customer returns items or requires compensation, use the Refund API to process full or partial refunds.

When to execute: When refund is needed.

Basic refund request:

POST /orders/7890abcd-ef12-3456-7890-abcdef123456/refunds HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...
Content-Type: application/json

{
  "amount": 1248.00,
  "description": "Full refund - customer cancellation",
  "actionReference": "REFUND-2024-12345"
}

Key points:

  • Can only refund captured amounts
  • Supports full refunds, partial refunds, and refunds with fees/discounts
  • Response is 202 Accepted - refund is processed asynchronously

For complete refund documentation including partial refunds, adding fees/discounts, replacement articles, and error handling, see Refund Order API documentation.

Phase 5: Settlement​

Query settlement data to reconcile payments with your accounting system. Settlements typically occur daily and include all captured amounts minus refunds.

When to execute: Daily or weekly for financial reconciliation.

Basic API usage:

GET /reports/settlements?query=startDate:>=2024-12-01%20AND%20endDate:<=2024-12-04&page=1&perPage=10 HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

Response:

{
  "data": [
    {
      "id": "1",
      "startDate": "2024-12-01T00:00:00",
      "endDate": "2024-12-04T00:00:00",
      "storeId": 1,
      "totalAmount": 100000.0,
      "currency": "SEK",
      "captured": 103000.0,
      "refunded": -3000.0,
      "reference": "2134"
    }
  ]
}

Get settlement transactions:

GET /reports/settlements/1/transactions?page=1&perPage=10 HTTP/1.1
Host: api.uat.walleydev.com
Authorization: Bearer bXlVc2VybmFtZTpmN2E1ODA4MGQzZTk0M2VmNWYyMTZlMDE...

Response:

{
  "data": [
    {
      "orderId": "7890abcd-ef12-3456-7890-abcdef123456",
      "orderNumber": "ORDER-2024-12345",
      "type": "Purchase",
      "amount": 1248.00,
      "currency": "SEK",
      "purchaseDate": "2024-12-01",
      "invoiceNumber": "11111111"
    }
  ]
}

For complete information on settlements including query parameters, transaction details, file formats, and reconciliation best practices, see the Settlements documentation.

Best practices​

Security: Store API credentials securely, use HTTPS for all communication, validate webhook HMAC signatures (Approach B) or ensure HTTPS notification endpoints (Approach A), and implement IP whitelisting.

Error handling: Implement retry logic with exponential backoff, log all API requests/responses, and set up monitoring for critical failures.

Idempotency: Use idempotency keys for captures and refunds, handle duplicate notifications/webhooks by storing processed IDs, and use database transactions for state changes.

Operations: Capture within authorization validity, process webhooks asynchronously, maintain audit trails, and run daily settlement reconciliation.