Skip to content
PayplugPayplug Elements

One session

GET
/api/sessions/{sessionId}
curl -s "https://services.sandbox.payplug-elements.msem.tech/api/sessions/0193f6c1-7a2e-7b4d-9f01-2c3d4e5f6a7b" \
  -H "authorization: Bearer $ACCESS_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

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “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

Section titled “ Responses ”

200

Section titled “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.

Media typeapplication/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
cardCode

The card as the PSP masked it — its first six and last four digits, the rest X — when it gave it.

string
cardCountry

The country of the card’s issuer, ISO 3166 alpha-2 — when the PSP gave it.

string
owedToPayer

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

string
settlementOverdueAt

When this attempt’s settlement was recorded overdue — still without a verdict a day after the session’s term (the settlement-overdue alert). Epoch milliseconds. While the attempt is still AUTHORIZING, an administrator can conclude it from the dashboard.

integer
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, send money back, or debit the registered card later.

string
Allowed values: authorization payment capture void refund debit
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
ackTraceId

The PSP’s own reference for the driving call’s exchange, when it named one — what its support asks for.

string
extraData

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

string
replayOf

The refused operation this one replays — asked again by an administrator.

string
refundOf

On a refund: the later debit it gives back — absent, the attempt’s own taking.

string
incidents

What waits for someone on this session — absent when nothing is open.

Array<object>
object
kind
required

The kind of incident — the ops alert’s name.

string
since
required

Since when it is open, epoch ms.

integer
attemptId

The tranche it belongs to.

string
transactionId

The operation it is about.

string
acknowledgeable
required

Nothing in the domain concludes it: an administrator says when it is dealt with from the dashboard. Otherwise it closes on its own.

boolean
laterDebit

The later debit this session allows — a card registered for the merchant to debit, on a method that can (POST /api/sessions/{sessionId}/debit). Absent when there is none.

object
attemptId
required

The tranche that registered the card.

string
recurringExpiry
required

Last day the registration may be used (YYYY-MM-DD).

string
maximumFutureDebit

The ceiling: per debit — or, for a guarantee, all of them together.

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}$/
futureDebitType

Why the card will be debited later.

string
committed
required

What the debits already took or may still take (succeeded + in flight).

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}$/
inFlight
required

A debit awaits its verdict — one at a time.

boolean
acknowledgedIncidents

The incidents already said dealt with.

Array<object>
object
kind
required
string
ref
required

The operation acknowledged — a transaction, a tranche, or empty.

string
at
required

When, epoch ms.

integer
note

What was done.

string
by

Who said it.

string
chargebacks

The disputes raised against this session’s payments, and their delivery to the merchant. Absent when there is none.

Array<object>
object
id
required

The dispute’s identifier — what the dashboard’s gestures on it name.

string
providerId
required
string
providerRef
required

The PSP’s reference for the dispute.

string
type
required

chargeback (a debit) or representment (a credit).

string
amount
required
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}$/
receivedAt
required

When the PSP raised it, epoch ms.

integer
message
required

The document the merchant receives — event: chargeback.

object
key
additional properties
url

Where it is delivered — absent when the merchant declared no address.

string
deliveredAt

When the merchant acknowledged it, epoch ms.

integer
failures
required

Failed attempts of the current calendar.

integer
lastFailureReason

Why the last attempt failed.

string
abandoned
required

Never delivered, the retries spent — an incident.

boolean
attachedBy

Who attached it by hand — absent when its reference named the payment.

string
acknowledged

An abandoned dispute dealt with by hand.

object
at
required

When it was said dealt with, epoch ms.

integer
by

Who said it.

string
note

What was done.

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

Who sells this line. Required on a session that offers a BNPL method. The one field of detail the payment page sees: with group-cart-by-brand, a line shows its brand, and a brand’s lines show as one.

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",
      "cardCode": "497010XXXXXX0007",
      "cardCountry": "FR",
      "settlementOverdueAt": 1791000000000,
      "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

Section titled “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.

Media typeapplication/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

Section titled “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.

Media typeapplication/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

Section titled “404”

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

Media typeapplication/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"
}