Search attempts

GET

/api/attempts

CURL *hnd = curl_easy_init();

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

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/attempts?limit=20&status=AUTHORIZING"),
    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/attempts?limit=20&status=AUTHORIZING"

  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/attempts?limit=20&status=AUTHORIZING"))
    .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/attempts?limit=20&status=AUTHORIZING")
  .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/attempts',
  params: {limit: '20', status: 'AUTHORIZING'},
  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/attempts?limit=20&status=AUTHORIZING';
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/attempts?limit=20&status=AUTHORIZING")
  .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/attempts";

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

    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/attempts?limit=20&status=AUTHORIZING' \
  --header 'Authorization: Bearer <token>'

The level the operator reasons at: an attempt of the session, a method, a plan — each carried with its home session and order. Same filters as the other searches; from/to ride the ATTEMPT’s own createdAt, providerRef matches through its transactions.

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: AUTHORIZING AUTHORIZED DECLINED CANCELLED CAPTURED VOIDED

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.

Responses

200

The matching attempts, newest first — one keyset page, each with its context.

application/json

object

attempts

required

The matching attempts, newest first.

Array<object>

The attempt, with the home that gives it meaning — session, merchant, order.

object

sessionId

required

The session this belongs to.

string format: uuid

merchantId

required

The merchant it belongs to.

string

orderId

required

Their own order reference.

string

attempt

required

The attempt itself.

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

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

{
  "attempts": [
    {
      "attempt": {
        "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"
}