payments

Version 0.1.06 opérations

Payments of the organisation, newest first, keyset paginated

GET/paymentsClé API

Paramètres

cursoranyquery
limitintegerquery
- max: 200
- default: 50
toanyquery
Created before (ISO 8601)
fromanyquery
Created at or after (ISO 8601)
accountanyquery
Payment account id
provideranyquery
statusanyquery
organisationIdanyquery
Required with a session

Réponses

200
- itemsPaymentDto[]obligatoire
  - idstring (uuid)obligatoire
  - referencestringobligatoire
    24 hexadecimal characters
  - statusstringobligatoire
    - enum: "pending", "succeeded", "failed", "expired", "canceled"
  - amountnumberobligatoire
  - currencystringobligatoire
  - descriptionstring | nullobligatoire
  - orderIdstring | nullobligatoire
  - payerPayerDtoobligatoire
    - firstNamestring
    - lastNamestring
    - emailstring
      Receives the receipt
    - phonestring
  - acceptedProvidersstring[]obligatoire
  - providerstring | nullobligatoire
    Provider of the succeeded attempt, or of the last attempt opened
  - organisationIdstring (uuid)obligatoire
  - paymentAccountIdstring (uuid)obligatoire
  - channelstringobligatoire
    - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
  - successUrlstring | nullobligatoire
  - failUrlstring | nullobligatoire
  - webhookUrlstring | nullobligatoire
  - expiresAtstring (date-time)obligatoire
  - metadataobjectobligatoire
  - payUrlstringobligatoire
    Hosted checkout page of this payment
  - succeededAttemptIdstring (uuid) | nullobligatoire
  - attemptsCountnumberobligatoire
  - paymentLinkIdstring (uuid) | nullobligatoire
    The payment link the payer started from (channel link), null otherwise
  - resultany
    Result summary (API responses only, not in webhook bodies)
  - createdAtstring (date-time)obligatoire
  - updatedAtstring (date-time)obligatoire
- nextCursorstring | nullobligatoire

Exemples de code

curl -X GET "$KONNECT_API_URL/payments" \
  -H "x-api-key: $KONNECT_API_KEY"

Exemple : 200

{
  "items": [
    {
      "id": "id",
      "reference": "665f1c2e8b3a4d0012ab34cd",
      "status": "pending",
      "amount": 12500,
      "currency": "TND",
      "description": "description",
      "orderId": "order-1001",
      "payer": {
        "firstName": "Sami",
        "lastName": "Test",
        "email": "payer@example.test",
        "phone": "+21600000000"
      },
      "acceptedProviders": [
        "clictopay"
      ],
      "provider": "provider",
      "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
      "paymentAccountId": "paymentAccountId",
      "channel": "api",
      "successUrl": "successUrl",
      "failUrl": "failUrl",
      "webhookUrl": "webhookUrl",
      "expiresAt": "2026-10-01T09:30:00.000Z",
      "metadata": {},
      "payUrl": "payUrl",
      "succeededAttemptId": "succeededAttemptId",
      "attemptsCount": 1,
      "paymentLinkId": "paymentLinkId",
      "result": {
        "status": "pending",
        "provider": "provider",
        "attemptId": "attemptId",
        "failureCode": "declined",
        "authorizationCode": "authorizationCode",
        "instrument": {},
        "attemptsCount": 1,
        "failedAttemptsCount": 1,
        "checkoutOpensCount": 1,
        "firstOpenedAt": "2026-10-01T09:30:00.000Z",
        "completedAt": "2026-10-01T09:30:00.000Z",
        "durationMs": 1,
        "merchantConfirmation": "confirmed",
        "merchantConfirmationReason": {}
      },
      "createdAt": "2026-10-01T09:30:00.000Z",
      "updatedAt": "2026-10-01T09:30:00.000Z"
    }
  ],
  "nextCursor": "nextCursor"
}

Create a payment and get its checkout URL

POST/paymentsClé API

The providers offered to the payer are the account routing intersected with acceptedProviders. Honours the Idempotency-Key header: a replay with the same body returns the first response.

Paramètres

Idempotency-Keystringheader

Corps de la requête application/json

organisationIdstring (uuid)
Required with a session (the organisation the payment belongs to); ignored with an API key, which names its own organisation
paymentAccountIdstring (uuid)
Payment account (collection point); the default account when omitted
amountnumberobligatoire
Integer minor units (millimes for TND)
currencystringobligatoire
- enum: "TND"
descriptionstring
- maxLength: 280
orderIdstring
Your own order reference
payerPayerDto
- firstNamestring
- lastNamestring
- emailstring
  Receives the receipt
- phonestring
acceptedProvidersstring[]
Providers offered to the payer, intersected with the account routing; every routed provider when omitted
successUrlstring
failUrlstring
webhookUrlstring
Per-payment webhook URL; must be on the origin of a registered webhook endpoint of the organisation, whose secret signs the deliveries
expiresInMinutesnumber
Lifetime in minutes; the platform setting payments.default_expiry_minutes when omitted
- min: 1
- max: 43200
metadataobject
Free merchant data, 4 KB at most once serialised
channelstring
- enum: "api", "link"
- default: "api"

Réponses

201
- idstring (uuid)obligatoire
- referencestringobligatoire
  24 hexadecimal characters
- statusstringobligatoire
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
- amountnumberobligatoire
- currencystringobligatoire
- descriptionstring | nullobligatoire
- orderIdstring | nullobligatoire
- payerPayerDtoobligatoire
  - firstNamestring
  - lastNamestring
  - emailstring
    Receives the receipt
  - phonestring
- acceptedProvidersstring[]obligatoire
- providerstring | nullobligatoire
  Provider of the succeeded attempt, or of the last attempt opened
- organisationIdstring (uuid)obligatoire
- paymentAccountIdstring (uuid)obligatoire
- channelstringobligatoire
  - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
- successUrlstring | nullobligatoire
- failUrlstring | nullobligatoire
- webhookUrlstring | nullobligatoire
- expiresAtstring (date-time)obligatoire
- metadataobjectobligatoire
- payUrlstringobligatoire
  Hosted checkout page of this payment
- succeededAttemptIdstring (uuid) | nullobligatoire
- attemptsCountnumberobligatoire
- paymentLinkIdstring (uuid) | nullobligatoire
  The payment link the payer started from (channel link), null otherwise
- resultany
  Result summary (API responses only, not in webhook bodies)
- createdAtstring (date-time)obligatoire
- updatedAtstring (date-time)obligatoire
400organisation_required, metadata_too_large, webhook_url_not_registered
403permission_denied or account_out_of_scope
409payment_account_inactive

Exemples de code

curl -X POST "$KONNECT_API_URL/payments" \
  -H "x-api-key: $KONNECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "paymentAccountId": "paymentAccountId",
  "amount": 12500,
  "currency": "TND",
  "description": "Order 1001",
  "orderId": "order-1001",
  "payer": {
    "firstName": "Sami",
    "lastName": "Test",
    "email": "payer@example.test",
    "phone": "+21600000000"
  },
  "acceptedProviders": [
    "clictopay"
  ],
  "successUrl": "https://shop.example.test/ok",
  "failUrl": "https://shop.example.test/ko",
  "webhookUrl": "https://shop.example.test/konnect/webhook",
  "expiresInMinutes": 60,
  "metadata": {},
  "channel": "api"
}'

Exemple : corps de la requête

{
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "paymentAccountId": "paymentAccountId",
  "amount": 12500,
  "currency": "TND",
  "description": "Order 1001",
  "orderId": "order-1001",
  "payer": {
    "firstName": "Sami",
    "lastName": "Test",
    "email": "payer@example.test",
    "phone": "+21600000000"
  },
  "acceptedProviders": [
    "clictopay"
  ],
  "successUrl": "https://shop.example.test/ok",
  "failUrl": "https://shop.example.test/ko",
  "webhookUrl": "https://shop.example.test/konnect/webhook",
  "expiresInMinutes": 60,
  "metadata": {},
  "channel": "api"
}

Exemple : 201

{
  "id": "id",
  "reference": "665f1c2e8b3a4d0012ab34cd",
  "status": "pending",
  "amount": 12500,
  "currency": "TND",
  "description": "description",
  "orderId": "order-1001",
  "payer": {
    "firstName": "Sami",
    "lastName": "Test",
    "email": "payer@example.test",
    "phone": "+21600000000"
  },
  "acceptedProviders": [
    "clictopay"
  ],
  "provider": "provider",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "paymentAccountId": "paymentAccountId",
  "channel": "api",
  "successUrl": "successUrl",
  "failUrl": "failUrl",
  "webhookUrl": "webhookUrl",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "metadata": {},
  "payUrl": "payUrl",
  "succeededAttemptId": "succeededAttemptId",
  "attemptsCount": 1,
  "paymentLinkId": "paymentLinkId",
  "result": {
    "status": "pending",
    "provider": "provider",
    "attemptId": "attemptId",
    "failureCode": "declined",
    "authorizationCode": "authorizationCode",
    "instrument": {
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "maskedId": "****5678"
    },
    "attemptsCount": 1,
    "failedAttemptsCount": 1,
    "checkoutOpensCount": 1,
    "firstOpenedAt": "2026-10-01T09:30:00.000Z",
    "completedAt": "2026-10-01T09:30:00.000Z",
    "durationMs": 1,
    "merchantConfirmation": "confirmed",
    "merchantConfirmationReason": {
      "outcome": "delivered",
      "statusCode": 1,
      "tries": 1,
      "timeoutMs": 1,
      "endpointDisabled": true,
      "nextRetryAt": "2026-10-01T09:30:00.000Z",
      "deliveryId": "deliveryId"
    }
  },
  "createdAt": "2026-10-01T09:30:00.000Z",
  "updatedAt": "2026-10-01T09:30:00.000Z"
}

One payment by reference

GET/payments/{reference}Clé API

Paramètres

referencestringpathobligatoire

Réponses

200
- idstring (uuid)obligatoire
- referencestringobligatoire
  24 hexadecimal characters
- statusstringobligatoire
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
- amountnumberobligatoire
- currencystringobligatoire
- descriptionstring | nullobligatoire
- orderIdstring | nullobligatoire
- payerPayerDtoobligatoire
  - firstNamestring
  - lastNamestring
  - emailstring
    Receives the receipt
  - phonestring
- acceptedProvidersstring[]obligatoire
- providerstring | nullobligatoire
  Provider of the succeeded attempt, or of the last attempt opened
- organisationIdstring (uuid)obligatoire
- paymentAccountIdstring (uuid)obligatoire
- channelstringobligatoire
  - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
- successUrlstring | nullobligatoire
- failUrlstring | nullobligatoire
- webhookUrlstring | nullobligatoire
- expiresAtstring (date-time)obligatoire
- metadataobjectobligatoire
- payUrlstringobligatoire
  Hosted checkout page of this payment
- succeededAttemptIdstring (uuid) | nullobligatoire
- attemptsCountnumberobligatoire
- paymentLinkIdstring (uuid) | nullobligatoire
  The payment link the payer started from (channel link), null otherwise
- resultany
  Result summary (API responses only, not in webhook bodies)
- createdAtstring (date-time)obligatoire
- updatedAtstring (date-time)obligatoire
404payment_not_found

Exemples de code

curl -X GET "$KONNECT_API_URL/payments/reference" \
  -H "x-api-key: $KONNECT_API_KEY"

Exemple : 200

{
  "id": "id",
  "reference": "665f1c2e8b3a4d0012ab34cd",
  "status": "pending",
  "amount": 12500,
  "currency": "TND",
  "description": "description",
  "orderId": "order-1001",
  "payer": {
    "firstName": "Sami",
    "lastName": "Test",
    "email": "payer@example.test",
    "phone": "+21600000000"
  },
  "acceptedProviders": [
    "clictopay"
  ],
  "provider": "provider",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "paymentAccountId": "paymentAccountId",
  "channel": "api",
  "successUrl": "successUrl",
  "failUrl": "failUrl",
  "webhookUrl": "webhookUrl",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "metadata": {},
  "payUrl": "payUrl",
  "succeededAttemptId": "succeededAttemptId",
  "attemptsCount": 1,
  "paymentLinkId": "paymentLinkId",
  "result": {
    "status": "pending",
    "provider": "provider",
    "attemptId": "attemptId",
    "failureCode": "declined",
    "authorizationCode": "authorizationCode",
    "instrument": {
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "maskedId": "****5678"
    },
    "attemptsCount": 1,
    "failedAttemptsCount": 1,
    "checkoutOpensCount": 1,
    "firstOpenedAt": "2026-10-01T09:30:00.000Z",
    "completedAt": "2026-10-01T09:30:00.000Z",
    "durationMs": 1,
    "merchantConfirmation": "confirmed",
    "merchantConfirmationReason": {
      "outcome": "delivered",
      "statusCode": 1,
      "tries": 1,
      "timeoutMs": 1,
      "endpointDisabled": true,
      "nextRetryAt": "2026-10-01T09:30:00.000Z",
      "deliveryId": "deliveryId"
    }
  },
  "createdAt": "2026-10-01T09:30:00.000Z",
  "updatedAt": "2026-10-01T09:30:00.000Z"
}

Cancel a pending payment

POST/payments/{reference}/cancelClé API

No new attempt can be opened afterwards. An attempt already open at a provider keeps being followed: a success reported later is recorded and raised, never hidden.

Paramètres

referencestringpathobligatoire

Corps de la requête application/json

reasonstring
- maxLength: 200
organisationIdstring (uuid)
Organisation, with a session

Réponses

200
- idstring (uuid)obligatoire
- referencestringobligatoire
  24 hexadecimal characters
- statusstringobligatoire
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
- amountnumberobligatoire
- currencystringobligatoire
- descriptionstring | nullobligatoire
- orderIdstring | nullobligatoire
- payerPayerDtoobligatoire
  - firstNamestring
  - lastNamestring
  - emailstring
    Receives the receipt
  - phonestring
- acceptedProvidersstring[]obligatoire
- providerstring | nullobligatoire
  Provider of the succeeded attempt, or of the last attempt opened
- organisationIdstring (uuid)obligatoire
- paymentAccountIdstring (uuid)obligatoire
- channelstringobligatoire
  - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
- successUrlstring | nullobligatoire
- failUrlstring | nullobligatoire
- webhookUrlstring | nullobligatoire
- expiresAtstring (date-time)obligatoire
- metadataobjectobligatoire
- payUrlstringobligatoire
  Hosted checkout page of this payment
- succeededAttemptIdstring (uuid) | nullobligatoire
- attemptsCountnumberobligatoire
- paymentLinkIdstring (uuid) | nullobligatoire
  The payment link the payer started from (channel link), null otherwise
- resultany
  Result summary (API responses only, not in webhook bodies)
- createdAtstring (date-time)obligatoire
- updatedAtstring (date-time)obligatoire
409payment_not_pending

Exemples de code

curl -X POST "$KONNECT_API_URL/payments/reference/cancel" \
  -H "x-api-key: $KONNECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Order canceled by the customer",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000"
}'

Exemple : corps de la requête

{
  "reason": "Order canceled by the customer",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000"
}

Exemple : 200

{
  "id": "id",
  "reference": "665f1c2e8b3a4d0012ab34cd",
  "status": "pending",
  "amount": 12500,
  "currency": "TND",
  "description": "description",
  "orderId": "order-1001",
  "payer": {
    "firstName": "Sami",
    "lastName": "Test",
    "email": "payer@example.test",
    "phone": "+21600000000"
  },
  "acceptedProviders": [
    "clictopay"
  ],
  "provider": "provider",
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "paymentAccountId": "paymentAccountId",
  "channel": "api",
  "successUrl": "successUrl",
  "failUrl": "failUrl",
  "webhookUrl": "webhookUrl",
  "expiresAt": "2026-10-01T09:30:00.000Z",
  "metadata": {},
  "payUrl": "payUrl",
  "succeededAttemptId": "succeededAttemptId",
  "attemptsCount": 1,
  "paymentLinkId": "paymentLinkId",
  "result": {
    "status": "pending",
    "provider": "provider",
    "attemptId": "attemptId",
    "failureCode": "declined",
    "authorizationCode": "authorizationCode",
    "instrument": {
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "maskedId": "****5678"
    },
    "attemptsCount": 1,
    "failedAttemptsCount": 1,
    "checkoutOpensCount": 1,
    "firstOpenedAt": "2026-10-01T09:30:00.000Z",
    "completedAt": "2026-10-01T09:30:00.000Z",
    "durationMs": 1,
    "merchantConfirmation": "confirmed",
    "merchantConfirmationReason": {
      "outcome": "delivered",
      "statusCode": 1,
      "tries": 1,
      "timeoutMs": 1,
      "endpointDisabled": true,
      "nextRetryAt": "2026-10-01T09:30:00.000Z",
      "deliveryId": "deliveryId"
    }
  },
  "createdAt": "2026-10-01T09:30:00.000Z",
  "updatedAt": "2026-10-01T09:30:00.000Z"
}

Full timeline of a payment, oldest first

GET/payments/{reference}/timelineClé API

Payment events, attempt events and webhook tries merged in one order and keyset paginated, with the attempts and their normalised results, the webhook deliveries with every try, and the payment with its result summary (spec 2.1b).

Paramètres

referencestringpathobligatoire
categorystring[]query
Repeat to keep several categories; all by default
cursoranyquery
nextCursor of the previous page
limitintegerquery
- max: 200
- default: 100
organisationIdanyquery
Optional with a session

Réponses

200
- paymentPaymentDtoobligatoire
  - idstring (uuid)obligatoire
  - referencestringobligatoire
    24 hexadecimal characters
  - statusstringobligatoire
    - enum: "pending", "succeeded", "failed", "expired", "canceled"
  - amountnumberobligatoire
  - currencystringobligatoire
  - descriptionstring | nullobligatoire
  - orderIdstring | nullobligatoire
  - payerPayerDtoobligatoire
    - firstNamestring
    - lastNamestring
    - emailstring
      Receives the receipt
    - phonestring
  - acceptedProvidersstring[]obligatoire
  - providerstring | nullobligatoire
    Provider of the succeeded attempt, or of the last attempt opened
  - organisationIdstring (uuid)obligatoire
  - paymentAccountIdstring (uuid)obligatoire
  - channelstringobligatoire
    - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
  - successUrlstring | nullobligatoire
  - failUrlstring | nullobligatoire
  - webhookUrlstring | nullobligatoire
  - expiresAtstring (date-time)obligatoire
  - metadataobjectobligatoire
  - payUrlstringobligatoire
    Hosted checkout page of this payment
  - succeededAttemptIdstring (uuid) | nullobligatoire
  - attemptsCountnumberobligatoire
  - paymentLinkIdstring (uuid) | nullobligatoire
    The payment link the payer started from (channel link), null otherwise
  - resultany
    Result summary (API responses only, not in webhook bodies)
  - createdAtstring (date-time)obligatoire
  - updatedAtstring (date-time)obligatoire
- attemptsTimelineAttemptDto[]obligatoire
  Oldest first
  - idstring (uuid)obligatoire
  - numbernumberobligatoire
    1 for the first attempt of the payment
  - providerstringobligatoire
  - statusstringobligatoire
  - externalRefstring | nullobligatoire
  - amountnumberobligatoire
  - providerFeenumber | nullobligatoire
  - affiliationAttemptAffiliationDtoobligatoire
    - affiliationIdstring (uuid)obligatoire
    - labelstringobligatoire
    - environmentstringobligatoire
      - enum: "sandbox", "production"
    - publicIdentifierstring | nullobligatoire
      Never a secret
    - credentialVersionnumberobligatoire
  - checksCountnumberobligatoire
  - resultAttemptResultDtoobligatoire
    - failureCodestring | nullobligatoire
      - enum: "declined", "insufficient_funds", "limit_exceeded", "card_expired", "invalid_instrument", "authentication_failed", "fraud_suspected", "canceled_by_payer", "session_expired", "payment_expired", "provider_unavailable", "invalid_request", "merchant_auth_failed", "unknown_reference", "unknown"
    - providerResultCodestring | nullobligatoire
      The provider own code
    - providerMessagestring | nullobligatoire
      The provider message, redacted
    - authorizationCodestring | nullobligatoire
    - instrumentany | nullobligatoire
    - initiatedAtstring (date-time) | nullobligatoire
    - redirectedAtstring (date-time) | nullobligatoire
    - authorizedAtstring (date-time) | nullobligatoire
    - completedAtstring (date-time) | nullobligatoire
    - durationsAttemptDurationsDtoobligatoire
      - initMsnumber | nullobligatoire
        initiated_at to redirected_at
      - payerMsnumber | nullobligatoire
        redirected_at to completed_at
      - totalMsnumber | nullobligatoire
        initiated_at to completed_at
  - createdAtstring (date-time)obligatoire
  - rawany
    Admin view only
- webhooksTimelineWebhooksDtoobligatoire
  - deliveriesWebhookDeliveryDto[]obligatoire
    - idstring (uuid)obligatoire
    - endpointIdstring (uuid)obligatoire
    - paymentIdstring (uuid)obligatoire
    - eventIdstring (uuid)obligatoire
    - eventTypestringobligatoire
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringobligatoire
    - statusstringobligatoire
      - enum: "pending", "delivered", "failed"
    - attemptsnumberobligatoire
    - lastStatusCodenumber | nullobligatoire
    - lastErrorstring | nullobligatoire
    - lastAttemptAtstring (date-time) | nullobligatoire
    - deliveredAtstring (date-time) | nullobligatoire
    - lastOutcomestring | nullobligatoire
      - enum: "delivered", "http_4xx", "http_5xx", "timeout", "connection_refused", "dns_error", "tls_error", "redirect_not_followed", "response_too_large", "invalid_url_or_blocked", "other"
    - nextRetryAtstring (date-time) | nullobligatoire
    - manualTriesnumberobligatoire
    - createdAtstring (date-time)obligatoire
  - triesWebhookTryDto[]obligatoire
    Every HTTP try, oldest first
    - idstring (uuid)obligatoire
    - deliveryIdstring (uuid)obligatoire
    - endpointIdstring (uuid)obligatoire
    - eventIdstring (uuid)obligatoire
    - eventTypestringobligatoire
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringobligatoire
    - tryNumbernumberobligatoire
    - triggerstringobligatoire
      - enum: "automatic", "manual"
    - requestedBystring (uuid) | nullobligatoire
    - requestHeadersobjectobligatoire
    - requestBodystringobligatoire
      The body as sent, byte for byte
    - startedAtstring (date-time)obligatoire
    - durationMsnumberobligatoire
    - outcomestringobligatoire
      - enum: "delivered", "http_4xx", "http_5xx", "timeout", "connection_refused", "dns_error", "tls_error", "redirect_not_followed", "response_too_large", "invalid_url_or_blocked", "other"
    - statusCodenumber | nullobligatoire
    - responseHeadersobject | nullobligatoire
    - responseExcerptstring | nullobligatoire
      First 2 KB, redacted
    - errorMessagestring | nullobligatoire
    - nextRetryAtstring (date-time) | nullobligatoire
- itemsTimelineItemDto[]obligatoire
  Oldest first
  - idstring (uuid)obligatoire
  - seqstringobligatoire
    Timeline order, shared by the three source tables
  - kindstringobligatoire
    - enum: "payment_event", "attempt_event"
  - typestringobligatoire
  - categorystringobligatoire
    - enum: "payment", "checkout", "attempt", "notification", "email", "anomaly", "refund", "reconciliation"
  - occurredAtstring (date-time)obligatoire
  - attemptIdstring (uuid) | nullobligatoire
  - actorTimelineActorDtoobligatoire
    - typestringobligatoire
      - enum: "system", "merchant_user", "api_key", "payer", "provider", "admin"
    - idstring | nullobligatoire
      User or API key id
  - sourcestringobligatoire
    - enum: "merchant_api", "dashboard", "checkout", "provider_callback", "poller", "outbox_worker", "admin_console", "system", "init", "callback", "poll", "manual"
  - fromStatusstring | nullobligatoire
  - toStatusstring | nullobligatoire
  - detailsobjectobligatoire
    Redacted
  - attemptEventAttemptEventDto
    - idstring (uuid)obligatoire
    - typestringobligatoire
    - fromStatusstring | nullobligatoire
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - toStatusstring | nullobligatoire
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - sourcestringobligatoire
      - enum: "init", "callback", "poll", "manual"
    - detailsobjectobligatoire
      Redacted
    - createdAtstring (date-time)obligatoire
  - webhookTryWebhookTryDto
    - idstring (uuid)obligatoire
    - deliveryIdstring (uuid)obligatoire
    - endpointIdstring (uuid)obligatoire
    - eventIdstring (uuid)obligatoire
    - eventTypestringobligatoire
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringobligatoire
    - tryNumbernumberobligatoire
    - triggerstringobligatoire
      - enum: "automatic", "manual"
    - requestedBystring (uuid) | nullobligatoire
    - requestHeadersobjectobligatoire
    - requestBodystringobligatoire
      The body as sent, byte for byte
    - startedAtstring (date-time)obligatoire
    - durationMsnumberobligatoire
    - outcomestringobligatoire
      - enum: "delivered", "http_4xx", "http_5xx", "timeout", "connection_refused", "dns_error", "tls_error", "redirect_not_followed", "response_too_large", "invalid_url_or_blocked", "other"
    - statusCodenumber | nullobligatoire
    - responseHeadersobject | nullobligatoire
    - responseExcerptstring | nullobligatoire
      First 2 KB, redacted
    - errorMessagestring | nullobligatoire
    - nextRetryAtstring (date-time) | nullobligatoire
- nextCursorstring | nullobligatoire
- eventTypesVersionnumberobligatoire
  PAYMENT_EVENT_TYPES_VERSION of packages/domain
404payment_not_found

Exemples de code

curl -X GET "$KONNECT_API_URL/payments/reference/timeline" \
  -H "x-api-key: $KONNECT_API_KEY"

Exemple : 200

{
  "payment": {
    "id": "id",
    "reference": "665f1c2e8b3a4d0012ab34cd",
    "status": "pending",
    "amount": 12500,
    "currency": "TND",
    "description": "description",
    "orderId": "order-1001",
    "payer": {
      "firstName": "Sami",
      "lastName": "Test",
      "email": "payer@example.test",
      "phone": "+21600000000"
    },
    "acceptedProviders": [
      "clictopay"
    ],
    "provider": "provider",
    "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
    "paymentAccountId": "paymentAccountId",
    "channel": "api",
    "successUrl": "successUrl",
    "failUrl": "failUrl",
    "webhookUrl": "webhookUrl",
    "expiresAt": "2026-10-01T09:30:00.000Z",
    "metadata": {},
    "payUrl": "payUrl",
    "succeededAttemptId": "succeededAttemptId",
    "attemptsCount": 1,
    "paymentLinkId": "paymentLinkId",
    "result": {
      "status": "pending",
      "provider": "provider",
      "attemptId": "attemptId",
      "failureCode": "declined",
      "authorizationCode": "authorizationCode",
      "instrument": {
        "type": null,
        "brand": null,
        "last4": null,
        "maskedId": null
      },
      "attemptsCount": 1,
      "failedAttemptsCount": 1,
      "checkoutOpensCount": 1,
      "firstOpenedAt": "2026-10-01T09:30:00.000Z",
      "completedAt": "2026-10-01T09:30:00.000Z",
      "durationMs": 1,
      "merchantConfirmation": "confirmed",
      "merchantConfirmationReason": {
        "outcome": null,
        "statusCode": null,
        "tries": null,
        "timeoutMs": null,
        "endpointDisabled": null,
        "nextRetryAt": null,
        "deliveryId": null
      }
    },
    "createdAt": "2026-10-01T09:30:00.000Z",
    "updatedAt": "2026-10-01T09:30:00.000Z"
  },
  "attempts": [
    {
      "id": "id",
      "number": 1,
      "provider": "provider",
      "status": "status",
      "externalRef": "externalRef",
      "amount": 1,
      "providerFee": 1,
      "affiliation": {
        "affiliationId": "affiliationId",
        "label": "default",
        "environment": "sandbox",
        "publicIdentifier": "publicIdentifier",
        "credentialVersion": 1
      },
      "checksCount": 1,
      "result": {
        "failureCode": "declined",
        "providerResultCode": "providerResultCode",
        "providerMessage": "providerMessage",
        "authorizationCode": "authorizationCode",
        "instrument": {
          "type": null,
          "brand": null,
          "last4": null,
          "maskedId": null
        },
        "initiatedAt": "2026-10-01T09:30:00.000Z",
        "redirectedAt": "2026-10-01T09:30:00.000Z",
        "authorizedAt": "2026-10-01T09:30:00.000Z",
        "completedAt": "2026-10-01T09:30:00.000Z",
        "durations": {
          "initMs": 1,
          "payerMs": 1,
          "totalMs": 1
        }
      },
      "createdAt": "2026-10-01T09:30:00.000Z",
      "raw": {
        "rawInit": {},
        "rawStatus": {},
        "rawCallback": {}
      }
    }
  ],
  "webhooks": {
    "deliveries": [
      {
        "id": "id",
        "endpointId": "endpointId",
        "paymentId": "665f1c2e8b3a4d0012ab34cd",
        "eventId": "eventId",
        "eventType": "payment.succeeded",
        "url": "url",
        "status": "pending",
        "attempts": 1,
        "lastStatusCode": 1,
        "lastError": "lastError",
        "lastAttemptAt": "2026-10-01T09:30:00.000Z",
        "deliveredAt": "2026-10-01T09:30:00.000Z",
        "lastOutcome": "delivered",
        "nextRetryAt": "2026-10-01T09:30:00.000Z",
        "manualTries": 1,
        "createdAt": "2026-10-01T09:30:00.000Z"
      }
    ],
    "tries": [
      {
        "id": "id",
        "deliveryId": "deliveryId",
        "endpointId": "endpointId",
        "eventId": "eventId",
        "eventType": "payment.succeeded",
        "url": "url",
        "tryNumber": 1,
        "trigger": "automatic",
        "requestedBy": "requestedBy",
        "requestHeaders": {},
        "requestBody": "requestBody",
        "startedAt": "2026-10-01T09:30:00.000Z",
        "durationMs": 1,
        "outcome": "delivered",
        "statusCode": 1,
        "responseHeaders": {},
        "responseExcerpt": "responseExcerpt",
        "errorMessage": "errorMessage",
        "nextRetryAt": "2026-10-01T09:30:00.000Z"
      }
    ]
  },
  "items": [
    {
      "id": "id",
      "seq": "seq",
      "kind": "payment_event",
      "type": "attempt_status_changed",
      "category": "payment",
      "occurredAt": "2026-10-01T09:30:00.000Z",
      "attemptId": "attemptId",
      "actor": {
        "type": "system",
        "id": "id"
      },
      "source": "merchant_api",
      "fromStatus": "fromStatus",
      "toStatus": "toStatus",
      "details": {},
      "attemptEvent": {
        "id": "id",
        "type": "transition",
        "fromStatus": "created",
        "toStatus": "created",
        "source": "init",
        "details": {},
        "createdAt": "2026-10-01T09:30:00.000Z"
      },
      "webhookTry": {
        "id": "id",
        "deliveryId": "deliveryId",
        "endpointId": "endpointId",
        "eventId": "eventId",
        "eventType": "payment.succeeded",
        "url": "url",
        "tryNumber": 1,
        "trigger": "automatic",
        "requestedBy": "requestedBy",
        "requestHeaders": {},
        "requestBody": "requestBody",
        "startedAt": "2026-10-01T09:30:00.000Z",
        "durationMs": 1,
        "outcome": "delivered",
        "statusCode": 1,
        "responseHeaders": {},
        "responseExcerpt": "responseExcerpt",
        "errorMessage": "errorMessage",
        "nextRetryAt": "2026-10-01T09:30:00.000Z"
      }
    }
  ],
  "nextCursor": "nextCursor",
  "eventTypesVersion": 1
}

Attempts of a payment, newest first, each with its timeline

GET/payments/{reference}/attemptsClé API

Paramètres

referencestringpathobligatoire
cursoranyquery
limitintegerquery
- max: 200
- default: 50
organisationIdanyquery
Optional with a session

Réponses

200
- itemsAttemptDto[]obligatoire
  - idstring (uuid)obligatoire
  - paymentIdstring (uuid)obligatoire
  - providerstringobligatoire
    - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
  - statusstringobligatoire
    - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
  - externalRefstring | nullobligatoire
  - amountnumberobligatoire
  - currencystringobligatoire
  - providerFeenumber | nullobligatoire
  - affiliationAttemptAffiliationDtoobligatoire
    - affiliationIdstring (uuid)obligatoire
    - labelstringobligatoire
    - environmentstringobligatoire
      - enum: "sandbox", "production"
    - publicIdentifierstring | nullobligatoire
      Never a secret
    - credentialVersionnumberobligatoire
  - nextCheckAtstring (date-time) | nullobligatoire
  - checksCountnumberobligatoire
  - resultAttemptResultDtoobligatoire
    - failureCodestring | nullobligatoire
      - enum: "declined", "insufficient_funds", "limit_exceeded", "card_expired", "invalid_instrument", "authentication_failed", "fraud_suspected", "canceled_by_payer", "session_expired", "payment_expired", "provider_unavailable", "invalid_request", "merchant_auth_failed", "unknown_reference", "unknown"
    - providerResultCodestring | nullobligatoire
      The provider own code
    - providerMessagestring | nullobligatoire
      The provider message, redacted
    - authorizationCodestring | nullobligatoire
    - instrumentany | nullobligatoire
    - initiatedAtstring (date-time) | nullobligatoire
    - redirectedAtstring (date-time) | nullobligatoire
    - authorizedAtstring (date-time) | nullobligatoire
    - completedAtstring (date-time) | nullobligatoire
    - durationsAttemptDurationsDtoobligatoire
      - initMsnumber | nullobligatoire
        initiated_at to redirected_at
      - payerMsnumber | nullobligatoire
        redirected_at to completed_at
      - totalMsnumber | nullobligatoire
        initiated_at to completed_at
  - eventsAttemptEventDto[]obligatoire
    Timeline, oldest first
    - idstring (uuid)obligatoire
    - typestringobligatoire
    - fromStatusstring | nullobligatoire
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - toStatusstring | nullobligatoire
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - sourcestringobligatoire
      - enum: "init", "callback", "poll", "manual"
    - detailsobjectobligatoire
      Redacted
    - createdAtstring (date-time)obligatoire
  - createdAtstring (date-time)obligatoire
  - updatedAtstring (date-time)obligatoire
- nextCursorstring | nullobligatoire
404payment_not_found

Exemples de code

curl -X GET "$KONNECT_API_URL/payments/reference/attempts" \
  -H "x-api-key: $KONNECT_API_KEY"

Exemple : 200

{
  "items": [
    {
      "id": "id",
      "paymentId": "665f1c2e8b3a4d0012ab34cd",
      "provider": "clictopay",
      "status": "created",
      "externalRef": "externalRef",
      "amount": 1,
      "currency": "currency",
      "providerFee": 1,
      "affiliation": {
        "affiliationId": "affiliationId",
        "label": "default",
        "environment": "sandbox",
        "publicIdentifier": "publicIdentifier",
        "credentialVersion": 1
      },
      "nextCheckAt": "2026-10-01T09:30:00.000Z",
      "checksCount": 1,
      "result": {
        "failureCode": "declined",
        "providerResultCode": "providerResultCode",
        "providerMessage": "providerMessage",
        "authorizationCode": "authorizationCode",
        "instrument": {
          "type": null,
          "brand": null,
          "last4": null,
          "maskedId": null
        },
        "initiatedAt": "2026-10-01T09:30:00.000Z",
        "redirectedAt": "2026-10-01T09:30:00.000Z",
        "authorizedAt": "2026-10-01T09:30:00.000Z",
        "completedAt": "2026-10-01T09:30:00.000Z",
        "durations": {
          "initMs": 1,
          "payerMs": 1,
          "totalMs": 1
        }
      },
      "events": [
        {
          "id": "id",
          "type": "transition",
          "fromStatus": "created",
          "toStatus": "created",
          "source": "init",
          "details": {},
          "createdAt": "2026-10-01T09:30:00.000Z"
        }
      ],
      "createdAt": "2026-10-01T09:30:00.000Z",
      "updatedAt": "2026-10-01T09:30:00.000Z"
    }
  ],
  "nextCursor": "nextCursor"
}