checkout

Version 0.1.09 opérations

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

GET/checkout/{reference}

Paramètres

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

Réponses

200
- referencestringobligatoire
- statusstringobligatoire
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
- amountnumberobligatoire
- currencystringobligatoire
- descriptionstring | nullobligatoire
- expiresAtstring (date-time)obligatoire
- merchantCheckoutMerchantDtoobligatoire
  - displayNamestringobligatoire
  - themeColorstring | nullobligatoire
  - logoUrlstring | nullobligatoire
    Public URL of the payment account logo (GET /checkout/:reference/logo); null without a logo
- providersCheckoutProviderDto[]obligatoire
  Providers the payer may choose right now (routed to an active affiliation)
  - codestringobligatoire
    - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
  - namestringobligatoire
- successUrlstring | nullobligatoire
- failUrlstring | nullobligatoire
- successMessagestring | nullobligatoire
  Message of the payment link for the success page (lot 2.5), null otherwise
404payment_not_found
429rate_limited (Retry-After)

Exemples de code

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

Exemple : 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.

Paramètres

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

Réponses

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

Exemples de code

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

Paramètres

referencestringpathobligatoire

Réponses

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

Exemples de code

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

Exemple : 200

"string"

Payment status for the result page polling (public)

GET/checkout/{reference}/status

Paramètres

referencestringpathobligatoire

Réponses

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

Exemples de code

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

Exemple : 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}

Paramètres

slugstringpathobligatoire

Réponses

200
- slugstringobligatoire
- titlestringobligatoire
- descriptionstring | nullobligatoire
- statusstringobligatoire
  - enum: "active", "disabled", "expired", "completed"
- amountTypestringobligatoire
  - enum: "fixed", "open"
- amountnumber | nullobligatoire
- minAmountnumber | nullobligatoire
- maxAmountnumber | nullobligatoire
- currencystringobligatoire
- payerFieldsPayerFieldSettingsDtoobligatoire
  - namestringobligatoire
    - enum: "hidden", "optional", "required"
  - emailstringobligatoire
    - enum: "hidden", "optional", "required"
  - phonestringobligatoire
    - enum: "hidden", "optional", "required"
- expiresAtstring (date-time) | nullobligatoire
- merchantCheckoutMerchantDtoobligatoire
  - displayNamestringobligatoire
  - themeColorstring | nullobligatoire
  - logoUrlstring | nullobligatoire
    Public URL of the payment account logo (GET /checkout/:reference/logo); null without a logo
404payment_link_not_found
429rate_limited (Retry-After)

Exemples de code

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

Exemple : 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

Paramètres

slugstringpathobligatoire

Réponses

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

Exemples de code

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

Exemple : 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.

Paramètres

slugstringpathobligatoire

Corps de la requête application/json

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

Réponses

201
- referencestringobligatoire
- payUrlstringobligatoire
  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)

Exemples de code

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

Exemple : corps de la requête

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

Exemple : 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.

Paramètres

referencestringpathobligatoire

Corps de la requête application/json

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

Réponses

201
- attemptIdstring (uuid)obligatoire
- providerstringobligatoire
  - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
- kindstringobligatoire
  - enum: "redirect", "qr", "form"
- redirectUrlstring
  Where to send the payer (kind redirect)
- qrAttemptQrDto
  - contentstringobligatoire
    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)

Exemples de code

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

Exemple : corps de la requête

{
  "provider": "clictopay"
}

Exemple : 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.

Paramètres

referencestringpathobligatoire
attemptIdstringpathobligatoire

Réponses

200
- attemptIdstring (uuid)obligatoire
- providerstringobligatoire
  - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
- kindstringobligatoire
  - enum: "redirect", "qr", "form"
- redirectUrlstring
  Where to send the payer (kind redirect)
- qrAttemptQrDto
  - contentstringobligatoire
    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)
- statusstringobligatoire
  - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
- paymentStatusstringobligatoire
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
404payment_not_found, attempt_not_found
429rate_limited (Retry-After)

Exemples de code

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

Exemple : 200

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