One session

GET

/api/sessions/{sessionId}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://example.com/api/sessions/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b");

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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b"),
    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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b"

  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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b"))
    .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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b")
  .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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b',
  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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b';
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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b")
  .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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b";

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

    let client = reqwest::Client::new();
    let response = client.get(url)
        .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/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b \
  --header 'Authorization: Bearer <token>'

Everything the dashboard shows of a session: the split verdicts, the ack triples, the serving PSP, the notification calendar — and everything you sent with the order: the basket, the customer, the addresses, the travel details, the URLs. Another merchant’s session answers the same 404 as a nonexistent one.

Authorizations

apiToken

Parameters

Path Parameters

sessionId

required

string format: uuid

/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/

The session, as a search returned it. A lowercase UUID — the ones we mint are v7.

Example

0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b

Responses

200

One session in full: the dashboard view, plus everything the merchant sent with the order — basket, customer, addresses, travel, return and cancel URLs, descriptor.

application/json

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

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.

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

paymentMethodFilters

What the offer was matched against (method-acl.md) — the first thing to read when a method someone expected was not served.

object

country

ISO 3166-1 alpha-2 — where the order was sold.

string

channel

The merchant’s own sales channel.

string

cartItems

The basket as the merchant described it, line by line.

Array<object>

object

label

required

What the buyer reads for this line — shown as-is on the payment page.

string

>= 1 characters

quantity

required

How many units of it.

integer

>= 1

amount

required

Price of the LINE — unit price × quantity, 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}$/

detail

PSP-facing itemization of this line. REQUIRED, in full, on a session that offers a BNPL method: the lender reads every field. Never shown to the payer — the payment page carries the label, the quantity and the amount, nothing of this block.

object

itemId

Your own catalogue reference. Required on a session that offers a BNPL method.

string

>= 1 characters

category

What this line IS, from the lender’s closed list. REQUIRED on every line of a session that offers a BNPL method — the platform has no default for what a shop sells.

string

Allowed values: computersandsoftware electronics appliances homeandgarden fashion healthandbeauty jewellery sport leisureandhobbies carsandmotorbikes furniture kidsandbaby videogamesandconsoles toysandgames pets foodanddrink giftandflowers entertainment travel auctionsandgroupbuying servicesforindividuals servicesforprofessionals

brand

Required on a session that offers a BNPL method.

string

>= 1 characters <= 100 characters

discount

Discount already applied to this line, in minor units.

integer

tax

Tax included in this line, in minor units.

integer

delivery

How this line is delivered. Every field of it is required on a session that offers a BNPL method: the lender reads them, and the platform substitutes nothing.

object

type

How the goods reach the buyer. Required on a BNPL session.

string

Allowed values: storepickup networkpickup travelpickup billingaddress carrier edelivery

speed

Required on a BNPL session.

string

Allowed values: standard express

expectedDate

Required on a BNPL session.

string

/^\d{4}-\d{2}-\d{2}$/

expectedDelay

In days. Required on a BNPL session.

integer

label

Required on a BNPL session.

string

>= 1 characters <= 100 characters

customer

Who is paying, as the merchant knows them. Personal data — the merchant’s own.

object

activity

The buyer’s activity with your shop, handed to the 3-D Secure risk assessment (more history means a better chance of a frictionless authentication). Send what you know.

object

transactionsLast24h

Purchases in the last 24 hours.

integer

transactionsLast12Months

Purchases in the last 12 months.

integer

transactionsLast6Months

Purchases in the last 6 months.

integer

ident

Merchant-side unique customer identifier.

string

>= 1 characters

email

The buyer’s e-mail — where the PSP and the lender write, when they do.

string

>= 3 characters

firstName

The buyer’s own name. Used as the cardholder name when the card form does not collect one.

string

>= 1 characters

lastName

The buyer’s family name.

string

>= 1 characters

billing

The billing address sent with the order.

object

companyName

Company at this address, when there is one. Oney requires it on the shipping block.

string

>= 1 characters

firstName

Given name of the person at this address.

string

>= 1 characters

lastName

Family name of the person at this address.

string

>= 1 characters

title

Civility, PSP-normalized.

string

Allowed values: mr mrs miss

address

Street line — number, street, complement.

string

>= 1 characters

postalCode

Postal code as the country writes it.

string

>= 1 characters

city

City or town.

string

>= 1 characters

country

ISO 3166-1 alpha-2.

string

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

phone

International format.

string

>= 5 characters

mobilePhone

International format.

string

>= 5 characters

shipping

The shipping address sent with the order.

object

companyName

Company at this address, when there is one. Oney requires it on the shipping block.

string

>= 1 characters

firstName

Given name of the person at this address.

string

>= 1 characters

lastName

Family name of the person at this address.

string

>= 1 characters

title

Civility, PSP-normalized.

string

Allowed values: mr mrs miss

address

Street line — number, street, complement.

string

>= 1 characters

postalCode

Postal code as the country writes it.

string

>= 1 characters

city

City or town.

string

>= 1 characters

country

ISO 3166-1 alpha-2.

string

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

phone

International format.

string

>= 5 characters

mobilePhone

International format.

string

>= 5 characters

travel

The travel details sent with the order.

object

passenger

Who travels — the lead traveller, when the contract asks for one.

object

firstName

Given name of the lead traveller.

string

>= 1 characters

lastName

Family name of the lead traveller.

string

>= 1 characters

dateOfBirth

Date of birth, YYYY-MM-DD.

string

/^\d{4}-\d{2}-\d{2}$/

stays

One entry per stay of the trip.

Array<object>

object

location

Where the stay takes place — resort, city, site.

string

>= 1 characters

arrivalDate

Arrival, YYYY-MM-DD.

string

/^\d{4}-\d{2}-\d{2}$/

departureDate

Departure, YYYY-MM-DD.

string

/^\d{4}-\d{2}-\d{2}$/

type

What kind of stay it is, in your own words.

string

>= 1 characters

roomCount

How many rooms or units.

integer

>= 1

passengerCount

How many people travel.

integer

>= 1

insurance

Whether the order includes travel insurance.

boolean

vehicleRent

Whether the order includes a vehicle rental.

boolean

returnUrl

Where the payer is sent once it ends.

string

cancelUrl

Where the payer is sent when they give up.

string

statementDescriptor

The soft descriptor — what the buyer reads on their bank statement.

string

extraData

The merchant’s own free text, carried to the PSP.

string

mustCreateAlias

The order asked for a card alias to be created.

boolean

Example

{
  "status": "PENDING",
  "attempts": [
    {
      "status": "AUTHORIZING",
      "partialAuth": "chosen",
      "cardScheme": "visa",
      "transactions": [
        {
          "type": "authorization",
          "status": {
            "kind": "pending",
            "category": "bank-refusal"
          }
        }
      ]
    }
  ],
  "cartItems": [
    {
      "detail": {
        "category": "computersandsoftware",
        "delivery": {
          "type": "storepickup",
          "speed": "standard"
        }
      }
    }
  ],
  "billing": {
    "title": "mr"
  },
  "shipping": {
    "title": "mr"
  }
}

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.

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": "body/<field> failed validation"
}

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"
}

404

NotFound — the only code this response carries: unknown, or belonging to another merchant. The two are deliberately indistinguishable.

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": "NotFound",
  "message": "no such resource"
}