API Reference

Complete reference for PollenPay REST API. All requests require authentication.

POST

/v1/sessions

Secret Key Auth

Initiate a new financing session

This endpoint is called by the merchant's backend using their secret API key to initiate a financing session. It creates a basket and returns a session ID for redirection.

Parameters

totalAmount

number

Total amount to be billed the customer provided as integer in the minor currency unit (pence, cents, etc). If ommited will be automatically calcualated based on he basket.

basket

array

required

Details of the customer's basket.

Array items contain:

basket[].name

string

required

Name of the product.

basket[].referenceId

string

ID or reference of the product used internally.

basket[].price

number

required

Integer price of the product in the minor currency unit (pence, cents, etc).

basket[].currency

string

required

Currency of the price (e.g., 'GBP', 'USD').

basket[].vat

number

Value Added Tax percentage.

basket[].qty

integer

required

Quantity of the product.

basket[].discount

number

Discount applied to the product, percentage value (e.g., '10' for 10%).

otherBilledItems

array

Details of non product-related cost items, like shipping, discounts, fees, etc.

Array items contain:

otherBilledItems[].type

string

required

Type of additional billable item: 'tax', 'discount', or 'fee'.

otherBilledItems[].name

string

required

Name of the item.

otherBilledItems[].price

number

required

Integer price of the product in the minor currency unit (pence, cents, etc).

otherBilledItems[].currency

string

required

Currency of the price (e.g., 'GBP', 'USD').

customerInfo

object

Optional basic customer information.

Object properties:

customerInfo.referenceId

string

Customer's ID or reference used internally.

customerInfo.email

string

Customer's email address.

customerInfo.phone

string

Customer's phone number.

customerInfo.name

string

Customer's full name.

redirectSuccessUrl

string

The URL on the merchant's site to redirect to upon successful financing.

redirectFailureUrl

string

The URL on the merchant's site to redirect to upon financing failure or cancellation.

Responses

Request

json

{
  "basket": [
    {
      "referenceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "Fancy Shoes",
      "price": 7500,
      "currency": "GBP",
      "qty": 1,
      "vat": 20
    }
  ],
  "otherBilledItems": [
    {
      "type": "fee",
      "name": "Shipping",
      "price": 999,
      "currency": "GBP"
    }
  ],
  "customerInfo": {
    "email": "customer@example.com",
    "phone": "+447123456789"
  },
  "redirectSuccessUrl": "https://merchant.com/order-success",
  "redirectFailureUrl": "https://merchant.com/order-fail"
}

Response Examples

GET

/v1/sessions/{sessionId}/status

Publishable Key Auth

Secret Key Auth

Get the status of a financing session

This endpoint can be called by the merchant's frontend by session ID (can be called using publishable key) to check the real-time status of a financing session.

Parameters

sessionId

string

required

The ID of the financing session.

Responses

Returns the current status of the session.

Response Examples

json

{
  "sessionId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "basketId": "b1c2d3e4-f5a6-7890-1234-567890abcdef",
  "status": "customer_actions_pending",
  "redirectSuccessUrl": "https://merchant.com/order-success",
  "redirectFailureUrl": "https://merchant.com/order-fail",
  "orderId": "o1r2d3e4-f5g6-7890-1234-567890abcdef"
}

POST

/v1/sessions/{sessionId}/settle

Secret Key Auth

Settle a financing session

After the customer is redirected back from PollenPay UI following payment authorisation, the merchant's backend calls this endpoint to finalise the transaction. This step allows the merchant to perform final validations (such as stock checks or fraud analysis) before confirming the order. Based on the outcome, the merchant can either confirm the order as successful or mark it as failed.

Parameters

sessionId

string

required

The ID of the financing session to settle.

status

string

required

The final status of the order from the merchant's perspective. 'approved' will create the order, 'rejected' will terminate the session.

reason

string

A reason for the rejection. Required if the status is 'rejected'.

withOrder

boolean

If true, the response will include the full order object.

Responses

The settlement was processed successfully. Returns the final order details if successful, or a confirmation of failure. If withOrder is true, the full order object is returned.

Request

json

{
  "status": "approved"
}

Response Examples

json

{
  "orderId": "o1r2d3e4-f5g6-7890-1234-567890abcdef",
  "status": "completed",
  "message": "Order successfully created.",
  "order": {
    "id": "o1r2d3e4-f5g6-7890-1234-567890abcdef",
    "shortReference": "ABCDEF12",
    "buyer": {
      "referenceId": "eb56e3c4-08c8-45b1-819a-eb0b5ebed50c",
      "email": "customer@example.com",
      "phone": "+447123456789"
    },
    "receipt": {
      "basket": [
        {
          "referenceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "name": "Fancy Shoes",
          "price": 7500,
          "currency": "GBP",
          "qty": 1,
          "vat": 20
        }
      ],
      "otherBilledItems": [
        {
          "type": "fee",
          "name": "Shipping",
          "price": 999,
          "currency": "GBP"
        }
      ]
    },
    "total": 8500,
    "outstanding": 6375,
    "paid": 2125,
    "currency": "GBP",
    "purchaseDate": 1678886400,
    "paymentMethod": {
      "type": "visa",
      "last4": "4242"
    }
  }
}

GET

/v1/events

Secret Key Auth

Get order events

Query the latest order events for the authenticated merchant. Returns up to 3 most recent events. Optionally filter by a specific orderId using the 'order' query parameter.

Parameters

order

string

Optional order ID to filter events for a specific order.

Responses

Returns the latest order events.

Response Examples

json

[
  {
    "orderId": "o1r2d3e4-f5g6-7890-1234-567890abcdef",
    "iteration": 2,
    "createdAt": 1678972800,
    "type": "payment_success",
    "outstanding": "6375",
    "paymentId": "p1a2y3m4-e5n6-7890-1234-567890abcdef",
    "extras": {}
  },
  {
    "orderId": "o1r2d3e4-f5g6-7890-1234-567890abcdef",
    "iteration": 1,
    "createdAt": 1678886400,
    "type": "order_creation",
    "outstanding": "8500",
    "paymentId": null,
    "extras": {}
  }
]

GET

/v1/orders

Secret Key Auth

Get all orders

Retrieves a list of all finalised orders.

Responses

A list of orders.

Response Examples

json

[
  {
    "id": "o1r2d3e4-f5g6-7890-1234-567890abcdef",
    "shortReference": "ABCDEF12",
    "buyer": {
      "referenceId": "eb56e3c4-08c8-45b1-819a-eb0b5ebed50c",
      "email": "customer@example.com",
      "phone": "+447123456789"
    },
    "receipt": {
      "basket": [
        {
          "referenceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
          "name": "Fancy Shoes",
          "price": 7500,
          "currency": "GBP",
          "qty": 1,
          "vat": 20
        }
      ],
      "otherBilledItems": [
        {
          "type": "fee",
          "name": "Shipping",
          "price": 999,
          "currency": "GBP"
        }
      ]
    },
    "total": 8500,
    "outstanding": 6375,
    "paid": 2125,
    "currency": "GBP",
    "purchaseDate": 1678886400,
    "paymentMethod": {
      "type": "visa",
      "last4": "4242"
    }
  }
]

GET

/v1/orders/{orderId}

Secret Key Auth

Get an order by ID

Retrieves a single order by its unique identifier.

Parameters

orderId

string

required

ID of the order to retrieve.

Responses

A single order.

Response Examples

json

{
  "id": "o1r2d3e4-f5g6-7890-1234-567890abcdef",
  "shortReference": "ABCDEF12",
  "buyer": {
    "referenceId": "eb56e3c4-08c8-45b1-819a-eb0b5ebed50c",
    "email": "customer@example.com",
    "phone": "+447123456789"
  },
  "receipt": {
    "basket": [
      {
        "referenceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
        "name": "Fancy Shoes",
        "price": 7500,
        "currency": "GBP",
        "qty": 1,
        "vat": 20
      }
    ],
    "otherBilledItems": [
      {
        "type": "fee",
        "name": "Shipping",
        "price": 999,
        "currency": "GBP"
      }
    ]
  },
  "total": 8500,
  "outstanding": 6375,
  "paid": 2125,
  "currency": "GBP",
  "purchaseDate": 1678886400,
  "paymentMethod": {
    "type": "visa",
    "last4": "4242"
  }
}

POST

/v1/orders/{orderId}/refund

Secret Key Auth

Initiate a refund for an order

This endpoint allows a merchant to request a refund for specific items or the entire order. It will trigger a 'refund' order event and potentially adjust outstanding amounts.

Parameters

orderId

string

required

The ID of the order to refund.

refundItems

array

List of items to be refunded.

Array items contain:

refundItems[].productId

string

The ID of the product being refunded (if applicable).

refundItems[].name

string

required

The name of the product being refunded.

refundItems[].qty

integer

required

The quantity to refund.

refundItems[].amount

integer

required

The amount to refund for this item in pence.

totalRefundAmount

integer

required

The total amount to be refunded for the order in pence.

reason

string

required

Reason for the refund.

Responses

Refund initiated successfully. Returns the created order event.

Request

json

{
  "refundItems": [
    {
      "name": "Fancy Shoes",
      "qty": 1,
      "amount": 7500
    }
  ],
  "totalRefundAmount": 7500,
  "reason": "Customer returned one item."
}

Response Examples

json

{
  "orderId": "e1f2g3h4-i5j6-7890-1234-567890abcdef",
  "iteration": 2,
  "createdAt": 1678972800,
  "type": "refund",
  "outstanding": "5000",
  "paymentId": null,
  "revisedReceipt": {},
  "supportTicketId": null
}