checkout

Version 0.1.09 operations

What the checkout shows for a payment (public, no merchant data)

GET/checkout/{reference}

Parameters

referencestringpathrequired
viewstringquery
Which checkout page reads the payment. Only payment (the default) counts as a checkout open on the payment timeline; the result and attempt pages, which poll, pass their own view.
- enum: "payment", "result", "attempt"

Responses

200
- referencestringrequired
- statusstringrequired
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
- amountnumberrequired
- currencystringrequired
- descriptionstring | nullrequired
- expiresAtstring (date-time)required
- merchantCheckoutMerchantDtorequired
  - displayNamestringrequired
  - themeColorstring | nullrequired
  - logoUrlstring | nullrequired
    Public URL of the payment account logo (GET /checkout/:reference/logo); null without a logo
- providersCheckoutProviderDto[]required
  Providers the payer may choose right now (routed to an active affiliation)
  - codestringrequired
    - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
  - namestringrequired
- successUrlstring | nullrequired
- failUrlstring | nullrequired
- successMessagestring | nullrequired
  Message of the payment link for the success page (lot 2.5), null otherwise
404payment_not_found
429rate_limited (Retry-After)

Code samples

curl -X GET "$KONNECT_API_URL/checkout/reference"

Example: 200

{
  "reference": "665f1c2e8b3a4d0012ab34cd",
  "status": "pending",
  "amount": 12500,
  "currency": "TND",
  "description": "description",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "merchant": {
    "displayName": "Boutique Exemple",
    "themeColor": "#1a2b3c",
    "logoUrl": "logoUrl"
  },
  "providers": [
    {
      "code": "clictopay",
      "name": "ClicToPay"
    }
  ],
  "successUrl": "successUrl",
  "failUrl": "failUrl",
  "successMessage": "successMessage"
}

Send the payer back to the merchant (public)

GET/checkout/{reference}/return

Records payer_redirected_to_merchant on the payment timeline and redirects to the success URL (succeeded payment), the fail URL, or the checkout result page when the payment is still pending or the merchant gave no URL.

Parameters

referencestringpathrequired
outcomestringquery
- enum: "success", "fail"

Responses

302Redirect to the merchant or the result page
404payment_not_found
429rate_limited (Retry-After)

Code samples

curl -X GET "$KONNECT_API_URL/checkout/reference/return"

Logo of the payment account of a payment (public, PNG or JPEG)

GET/checkout/{reference}/logo

Parameters

referencestringpathrequired

Responses

200The image
404payment_not_found, logo_not_found
429rate_limited (Retry-After)

Code samples

curl -X GET "$KONNECT_API_URL/checkout/reference/logo"

Example: 200

"string"

Payment status for the result page polling (public)

GET/checkout/{reference}/status

Parameters

referencestringpathrequired

Responses

200
- referencestringrequired
- statusstringrequired
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
- providerstring | nullrequired
- expiresAtstring (date-time)required
- successUrlstring | nullrequired
- failUrlstring | nullrequired
- successMessagestring | nullrequired
  Message of the payment link for the success page (lot 2.5), null otherwise
404payment_not_found
429rate_limited (Retry-After)

Code samples

curl -X GET "$KONNECT_API_URL/checkout/reference/status"

Example: 200

{
  "reference": "665f1c2e8b3a4d0012ab34cd",
  "status": "pending",
  "provider": "provider",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "successUrl": "successUrl",
  "failUrl": "failUrl",
  "successMessage": "successMessage"
}

What the payer sees of a payment link (public)

GET/links/{slug}

Parameters

slugstringpathrequired

Responses

200
- slugstringrequired
- titlestringrequired
- descriptionstring | nullrequired
- statusstringrequired
  - enum: "active", "disabled", "expired", "completed"
- amountTypestringrequired
  - enum: "fixed", "open"
- amountnumber | nullrequired
- minAmountnumber | nullrequired
- maxAmountnumber | nullrequired
- currencystringrequired
- payerFieldsPayerFieldSettingsDtorequired
  - namestringrequired
    - enum: "hidden", "optional", "required"
  - emailstringrequired
    - enum: "hidden", "optional", "required"
  - phonestringrequired
    - enum: "hidden", "optional", "required"
- expiresAtstring (date-time) | nullrequired
- merchantCheckoutMerchantDtorequired
  - displayNamestringrequired
  - themeColorstring | nullrequired
  - logoUrlstring | nullrequired
    Public URL of the payment account logo (GET /checkout/:reference/logo); null without a logo
404payment_link_not_found
429rate_limited (Retry-After)

Code samples

curl -X GET "$KONNECT_API_URL/links/slug"

Example: 200

{
  "slug": "Ab3dE6gH9jK2",
  "title": "title",
  "description": "description",
  "status": "active",
  "amountType": "fixed",
  "amount": 1,
  "minAmount": 1,
  "maxAmount": 1,
  "currency": "TND",
  "payerFields": {
    "name": "hidden",
    "email": "buyer@example.com",
    "phone": "hidden"
  },
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "merchant": {
    "displayName": "Boutique Exemple",
    "themeColor": "#1a2b3c",
    "logoUrl": "logoUrl"
  }
}

Logo of the payment account of a link (public, PNG or JPEG)

GET/links/{slug}/logo

Parameters

slugstringpathrequired

Responses

200The image
404payment_link_not_found, logo_not_found
429rate_limited (Retry-After)

Code samples

curl -X GET "$KONNECT_API_URL/links/slug/logo"

Example: 200

"string"

Start a payment from a link (public)

POST/links/{slug}/payments

Creates a payment (channel link) for this payer and answers its checkout URL, where the payer picks a provider.

Parameters

slugstringpathrequired

Request body application/json

amountnumber
Required on an open-amount link, minor units
payerLinkPayerDto
- firstNamestring
- lastNamestring
- emailstring
- phonestring

Responses

201
- referencestringrequired
- payUrlstringrequired
  Checkout page where the payer picks a provider
400validation_failed, amount_required, amount_out_of_bounds, payer_field_required
404payment_link_not_found
409link_disabled, link_expired, link_completed, link_busy, payment_account_inactive
429rate_limited (Retry-After)

Code samples

curl -X POST "$KONNECT_API_URL/links/slug/payments" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 25000,
  "payer": {
    "firstName": "Sami",
    "lastName": "Test",
    "email": "payer@example.test",
    "phone": "+21600000000"
  }
}'

Example: request body

{
  "amount": 25000,
  "payer": {
    "firstName": "Sami",
    "lastName": "Test",
    "email": "payer@example.test",
    "phone": "+21600000000"
  }
}

Example: 201

{
  "reference": "665f1c2e8b3a4d0012ab34cd",
  "payUrl": "payUrl"
}

Open an attempt at a provider (public)

POST/checkout/{reference}/attempts

Decrypts the routed affiliation for the purpose "payment", calls initPayment and returns where to send the payer: a redirect URL, a QR code or form parameters.

Parameters

referencestringpathrequired

Request body application/json

providerstringrequired
- enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"

Responses

201
- attemptIdstring (uuid)required
- providerstringrequired
  - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
- kindstringrequired
  - enum: "redirect", "qr", "form"
- redirectUrlstring
  Where to send the payer (kind redirect)
- qrAttemptQrDto
  - contentstringrequired
    Content to render as a QR code
  - codePaystring
    Short code the payer may type instead
- formobject
  Provider form parameters (kind form, for example an MPGS checkout session)
409payment_not_pending, payment_expired, provider_not_accepted, too_many_attempts
429rate_limited (Retry-After)
502provider_init_failed (with providerErrorCode)

Code samples

curl -X POST "$KONNECT_API_URL/checkout/reference/attempts" \
  -H "Content-Type: application/json" \
  -d '{
  "provider": "clictopay"
}'

Example: request body

{
  "provider": "clictopay"
}

Example: 201

{
  "attemptId": "attemptId",
  "provider": "clictopay",
  "kind": "redirect",
  "redirectUrl": "redirectUrl",
  "qr": {
    "content": "content",
    "codePay": "codePay"
  },
  "form": {}
}

An attempt of a payment as the checkout shows it again (public)

GET/checkout/{reference}/attempts/{attemptId}

Kind, status and the payer-facing payload (redirect URL, QR code or form parameters), for the QR page, the hosted form page and the result page.

Parameters

referencestringpathrequired
attemptIdstringpathrequired

Responses

200
- attemptIdstring (uuid)required
- providerstringrequired
  - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
- kindstringrequired
  - enum: "redirect", "qr", "form"
- redirectUrlstring
  Where to send the payer (kind redirect)
- qrAttemptQrDto
  - contentstringrequired
    Content to render as a QR code
  - codePaystring
    Short code the payer may type instead
- formobject
  Provider form parameters (kind form, for example an MPGS checkout session)
- statusstringrequired
  - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
- paymentStatusstringrequired
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
404payment_not_found, attempt_not_found
429rate_limited (Retry-After)

Code samples

curl -X GET "$KONNECT_API_URL/checkout/reference/attempts/attemptId"

Example: 200

{
  "attemptId": "attemptId",
  "provider": "clictopay",
  "kind": "redirect",
  "redirectUrl": "redirectUrl",
  "qr": {
    "content": "content",
    "codePay": "codePay"
  },
  "form": {},
  "status": "created",
  "paymentStatus": "pending"
}