The payment session

The two shapes of a payment session — the checkout view returned by GET, and the settlement record returned by the write endpoints.

A payment session is Localoy's request to collect one order's amount through your checkout. It exists in one environment and belongs to one partner. See Accept payments for the flow.

The API returns a session in two shapes: the checkout view from GET /payments/sessions/{id}, and the settlement record from /result and /refund.

Checkout view#

Attributes

idstringrequired: The session ID — the session_id your checkout page receives.
statusstringrequired: PENDING, PROCESSING, SUCCEEDED, FAILED, CANCELLED, EXPIRED or REFUNDED.
environmentstringrequired: SANDBOX or PRODUCTION.
amountMinorintegerrequired: The amount to charge, in minor units — 90000 is ৳900.00.
currencystringrequired: Always BDT.
descriptionstringrequired: What the customer is paying for.
subjectobjectrequired: The order being paid. All three fields are null on a sandbox test session.

type — EVENT_TICKET_ORDER, ACTIVITY_BOOKING or DINING_RESERVATION.

id — the order's ID.

experienceId — the Localoy listing the order is for.
customerobjectrequired: name, phone and email of the customer, each possibly null.
returnUrlstringrequired: Where to send the customer's browser when you are done, whatever the outcome.
expiresAtstringrequired: When the session expires, ISO 8601 UTC.
isExpiredbooleanrequired: Whether expiresAt has passed.
isTestbooleanrequired: true for a sandbox session.
providerReferencestring | nullrequired: Your gateway's transaction ID, once reported.
settledAtstring | nullrequired: When a SUCCEEDED result was recorded.
createdAtstringrequired: When the session was opened.

Checkout view

{
  "id": "cm5s3ss10n00000000000001",
  "status": "PENDING",
  "environment": "PRODUCTION",
  "amountMinor": 90000,
  "currency": "BDT",
  "description": "Kayak (1 hour) × 2",
  "subject": {
    "type": "ACTIVITY_BOOKING",
    "id": "cm5b00k1ng0000000000001",
    "experienceId": "cm5act1v1ty000000000001"
  },
  "customer": {
    "name": "Nusrat Jahan",
    "phone": "01712345678",
    "email": null
  },
  "returnUrl": "https://partner.localoy.app/payments/return?session_id=cm5s3ss10n00000000000001&token=…",
  "expiresAt": "2026-09-26T09:00:00.000Z",
  "isExpired": false,
  "isTest": false,
  "providerReference": null,
  "settledAt": null,
  "createdAt": "2026-09-26T08:30:00.000Z"
}

Settlement record#

A flat record with the outcome fields. It has no subject, customer, returnUrl, isExpired or isTest.

Attributes

id, environment, status, amountMinor, currency, description—required: As in the checkout view.
subjectType, subjectId, experienceIdstring | nullrequired: The checkout view's subject fields, flattened.
customerName, customerPhone, customerEmailstring | nullrequired: The checkout view's customer fields, flattened.
checkoutUrlstringrequired: The checkout URL the session was opened with.
expiresAtstringrequired: When the session expires.
providerReferencestring | nullrequired: Your gateway's transaction or refund reference.
paidAmountMinorinteger | nullrequired: The amount you reported as paid.
failureCode, failureReasonstring | nullrequired: From your last FAILED result.
settledAtstring | nullrequired: When the payment succeeded.
refundedAtstring | nullrequired: When the refund was recorded.
settledAfterExpirybooleanrequired: true if the success was reported after the session expired.
platformFeeBps, platformFeeMinorinteger | nullrequired: Localoy's fee on this payment, in basis points and minor units, fixed when a production payment settles. null before that and on sandbox sessions.
createdAt, updatedAtstringrequired: When the session was opened and last changed.

Settlement record

{
  "id": "cm5s3ss10n00000000000001",
  "environment": "PRODUCTION",
  "status": "SUCCEEDED",
  "subjectType": "ACTIVITY_BOOKING",
  "subjectId": "cm5b00k1ng0000000000001",
  "experienceId": "cm5act1v1ty000000000001",
  "amountMinor": 90000,
  "currency": "BDT",
  "description": "Kayak (1 hour) × 2",
  "customerName": "Nusrat Jahan",
  "customerPhone": "01712345678",
  "customerEmail": null,
  "checkoutUrl": "https://pay.example.com/checkout",
  "expiresAt": "2026-09-26T09:00:00.000Z",
  "providerReference": "TXN-88213094",
  "paidAmountMinor": 90000,
  "failureCode": null,
  "failureReason": null,
  "settledAt": "2026-09-26T08:41:07.512Z",
  "refundedAt": null,
  "settledAfterExpiry": false,
  "platformFeeBps": 0,
  "platformFeeMinor": 0,
  "createdAt": "2026-09-26T08:30:00.000Z",
  "updatedAt": "2026-09-26T08:41:07.512Z"
}