Skip to main content

Complete payment flow: from checkout to settlement​

This guide walks you through Walley's full payment lifecycle, from checkout to settlement, with the API calls needed at each stage.

Prerequisites​

Before implementing this flow, make sure you have:

Payment lifecycle overview​

Five phases make up the full payment lifecycle, each with its own integration steps:

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?checkoutId={checkout.id}",
  "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​

Use the Notification Callback to learn that a checkout has been completed, then fetch the orderId via 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.

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.

Wait briefly before capturing

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-34d6-78f0-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
  • Recommended to provide items array for partial captures to ensure accurate reconciliation
  • For B2B customers, the items array is required to correctly display VAT information to the end customer

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 you need to compensate them, use the Refund API to process full or partial refunds.

When to execute: When a customer returns items or you process compensation.

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",
  "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:

  • Can only refund captured amounts
  • Supports full refunds, partial refunds, and refunds with fees/discounts
  • Response is 202 Accepted — refund is processed asynchronously
  • Recommended to provide items array for partial refunds to ensure accurate reconciliation
  • For B2B customers, the items array is required to correctly display VAT information to the end customer

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 settlement request:

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, ensure HTTPS notification endpoints, 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 by storing processed IDs, and use database transactions for state changes.

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