Search sessions

GET

/api/sessions

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://example.com/api/sessions?limit=20&status=PENDING");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://example.com/api/sessions?limit=20&status=PENDING"),
    Headers =
    {
        { "Authorization", "Bearer <token>" },
    },
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

import (
  "fmt"
  "net/http"
  "io"
)

func main() {

  url := "https://example.com/api/sessions?limit=20&status=PENDING"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <token>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://example.com/api/sessions?limit=20&status=PENDING"))
    .header("Authorization", "Bearer <token>")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://example.com/api/sessions?limit=20&status=PENDING")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://example.com/api/sessions',
  params: {limit: '20', status: 'PENDING'},
  headers: {Authorization: 'Bearer <token>'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://example.com/api/sessions?limit=20&status=PENDING';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://example.com/api/sessions?limit=20&status=PENDING")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://example.com/api/sessions";

    let querystring = [
        ("limit", "20"),
        ("status", "PENDING"),
    ];

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.get(url)
        .query(&querystring)
        .headers(headers)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request GET \
  --url 'https://example.com/api/sessions?limit=20&status=PENDING' \
  --header 'Authorization: Bearer <token>'

Every filter is optional, and they combine freely: orderId (one basket can produce two sessions), providerRef (the runbook’s grep, through the transactions), merchantId (an admin’s narrowing), from/to (epoch ms, [from, to) on the session’s createdAt). No filter at all lists everything the caller may see, newest first — one keyset page at a time.

Authorizations

apiToken

Parameters

Query Parameters

orderId

string

>= 1 characters

The merchant’s own order reference.

providerRef

string

>= 1 characters

A PSP’s reference, as their dashboard shows it.

merchantId

string

>= 1 characters

Narrow to one merchant (an admin’s filter). Intersects with the caller’s own scope: asking for someone else’s yields an empty page, never an error.

from

integer

Epoch ms, inclusive — on the entity’s own createdAt.

integer

Epoch ms, exclusive — [from, to).

limit

integer

default: 20 >= 1 <= 100

Page size (max 100).

cursor

string

The previous page’s nextCursor, verbatim.

status

string

Allowed values: PENDING CAPTURING PAID ABORTING ABORTED EXPIRING EXPIRED AWAITING AWAITED_REFUSED

The payment journey, and nothing else. PENDING: open, the payer may still pay. CAPTURING: covered, the money is being taken. PAID: done. ABORTING/ABORTED: the payer gave up, holds released. EXPIRING/EXPIRED: the session timed out, holds released. AWAITING: a lender is studying the file (BNPL), nothing taken. AWAITED_REFUSED: that lender said no. The three terminal states — PAID, ABORTED, EXPIRED (and AWAITED_REFUSED) — are where you route away.

Responses

200

The matching sessions, newest first — one keyset page (Q12).

application/json

object

sessions

required

The matching sessions, newest first.

Array<object>

The dashboard view — every operation with both facets: the verdict and the ack.

object

sessionId

required

Our handle for the session — the id the payer’s browser never sees.

string format: uuid

merchantId

required

Which merchant it belongs to.

string

orderId

required

The merchant’s own order reference — what you search on.

string

status

required

string

Allowed values: PENDING CAPTURING PAID ABORTING ABORTED EXPIRING EXPIRED AWAITING AWAITED_REFUSED

total

required

What the order costs.

object

amount

required

Amount in the MINOR unit of the currency — 1000_00 is one thousand euros, never 1000.

integer

currency

required

ISO 4217 code, uppercase. One currency per session.

string

/^[A-Z]{3}$/

captured

required

How much has actually been taken so far.

object

amount

required

Amount in the MINOR unit of the currency — 1000_00 is one thousand euros, never 1000.

integer

currency

required

ISO 4217 code, uppercase. One currency per session.

string

/^[A-Z]{3}$/

createdAt

required

Epoch milliseconds.

integer

expiresAt

required

Epoch milliseconds.

integer

notification

Where this session’s ending was announced, and how that went. Absent: no callback was declared.

object

url

required

Where the ending is announced to the merchant.

string

deliveredAt

When they acknowledged it — epoch milliseconds. Absent: still owed.

integer

failures

required

How many delivery attempts have failed so far (the calendar allows four).

integer

abandoned

required

The calendar is spent — nobody is coming (merchant-webhook Q6).

boolean

attempts

required

Every attempt of the session, oldest first.

Array<object>

object

attemptId

required

Our handle for this attempt — what the refund door addresses.

string format: uuid

createdAt

required

When the attempt was opened — epoch milliseconds (Q13).

integer

updatedAt

required

The last event that touched it — its transactions’ moves included.

integer

method

required

Archetype of the method that carried it (card, oney…).

string

methodId

required

The method INSTANCE of the session it was started on.

string

provider

required

The PSP adapter that served this attempt (D-051) — always present.

string

status

required

Where this attempt stands. AUTHORIZING: dispatched, verdict still due (always out-of-band). AUTHORIZED: the money is held. DECLINED: refused, nothing taken. CANCELLED: the payer backed out at the PSP. CAPTURED: taken. VOIDED: the hold was released.

string

Allowed values: AUTHORIZING AUTHORIZED DECLINED CANCELLED CAPTURED VOIDED

partialAuth

Who decided a grant below the request: the payer in their app (chosen), or the issuer (mandated).

string

Allowed values: chosen mandated

plan

BNPL attempts only: the plan the payer chose.

object

installments

required

How many instalments the payer took.

integer

withFees

required

Whether that plan carried fees.

boolean

requested

required

What the attempt asked for.

object

amount

required

Amount in the MINOR unit of the currency — 1000_00 is one thousand euros, never 1000.

integer

currency

required

ISO 4217 code, uppercase. One currency per session.

string

/^[A-Z]{3}$/

granted

required

What was actually authorized — what counts against the balance.

object

amount

required

Amount in the MINOR unit of the currency — 1000_00 is one thousand euros, never 1000.

integer

currency

required

ISO 4217 code, uppercase. One currency per session.

string

/^[A-Z]{3}$/

refunded

required

How much of it has already been sent back.

object

amount

required

Amount in the MINOR unit of the currency — 1000_00 is one thousand euros, never 1000.

integer

currency

required

ISO 4217 code, uppercase. One currency per session.

string

/^[A-Z]{3}$/

refundable

required

What can still be refunded on it — granted minus refunded, zero unless it settled.

object

amount

required

Amount in the MINOR unit of the currency — 1000_00 is one thousand euros, never 1000.

integer

currency

required

ISO 4217 code, uppercase. One currency per session.

string

/^[A-Z]{3}$/

cardAlias

The card registration this attempt produced, when the order asked for one (for later merchant-initiated payments).

string

cardScheme

The card network this attempt ran on, as the PSP named it — visa, cb, mastercard, amex… Card attempts only, and only when the platform named one we could place: an absence means the verdict said nothing, never that the payment had no network.

string

owedToPayer

Money taken that nothing can hand back (direct-settlement) — the ops debt.

string

transactions

required

Every PSP operation of this attempt, oldest first — the authorization, then its capture, void or refunds.

Array<object>

object

transactionId

required

Our handle for this PSP operation — what a refund door addresses.

string format: uuid

createdAt

required

When the operation was opened — epoch milliseconds (Q13).

integer

updatedAt

required

The last event that touched it — for a terminal transaction, its verdict’s instant.

integer

type

required

What this operation asked the PSP: hold the money, take it in one go, capture a hold, release a hold, or send money back.

string

Allowed values: authorization payment capture void refund

amount

required

What this operation moved, in minor units.

object

amount

required

Amount in the MINOR unit of the currency — 1000_00 is one thousand euros, never 1000.

integer

currency

required

ISO 4217 code, uppercase. One currency per session.

string

/^[A-Z]{3}$/

providerRef

The PSP’s reference — what their dashboard greps (D-047).

string

status

required

The VERDICT facet: what the PSP finally decided about this operation — as opposed to the ack facet below, which is what the driving call answered on the spot.

object

kind

required

Where the operation stands. pending means the verdict is still due — it always arrives out-of-band.

string

Allowed values: pending succeeded failed cancelled

statusCode

The PSP’s own code, split at the source — successes carry theirs too.

string

statusMessage

The PSP’s own sentence, as they said it — never glued to the code.

string

category

What a refusal means, when the PSP’s answer could be read.

string

Allowed values: bank-refusal insufficient-funds invalid-card-data authentication-failed expired method-unavailable

ackCode

What the driving call answered (the ack facet).

string

ackMessage

What the driving call said — a transport failure’s raw cause included.

string

ackHttpStatus

Absent beside a present ackMessage = no HTTP response ever came.

integer

extraData

The caller’s reconciliation tag, on refunds only (lot 5) — echoed verbatim.

string

nextCursor

Opaque keyset cursor — pass back as cursor for the next page; absent = last page.

string

Example

{
  "sessions": [
    {
      "status": "PENDING",
      "attempts": [
        {
          "status": "AUTHORIZING",
          "partialAuth": "chosen",
          "cardScheme": "visa",
          "transactions": [
            {
              "type": "authorization",
              "status": {
                "kind": "pending",
                "category": "bank-refusal"
              }
            }
          ]
        }
      ]
    }
  ]
}

400

InvalidRequest — the request could not be read: a missing or malformed field, a bad pattern, or a property this door does not declare (the message names it). Every door with a schema can answer this, before any business rule is consulted. Most often here: a cursor that cannot be decoded — the ONE 400 this API raises itself, after validation has passed.

application/json

object

code

required

Stable machine-readable code — the one thing to branch on. Never parse the message.

string

message

required

English sentence for logs and operators. Wording may change; the code will not.

string

Example

{
  "code": "InvalidRequest",
  "message": "unreadable cursor"
}

401

Unauthorized — the only code this response carries: no usable access token (absent, malformed, expired). One answer for every failure shape, so nothing can be learned by watching which one comes back.

application/json

object

code

required

Stable machine-readable code — the one thing to branch on. Never parse the message.

string

message

required

English sentence for logs and operators. Wording may change; the code will not.

string

Example

{
  "code": "Unauthorized",
  "message": "a valid access token is required"
}