payments

Version 0.1.06 operations

Payments of the organisation, newest first, keyset paginated

GET/paymentsAPI key

Parameters

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

Responses

200
- itemsPaymentDto[]required
  - idstring (uuid)required
  - referencestringrequired
    24 hexadecimal characters
  - statusstringrequired
    - enum: "pending", "succeeded", "failed", "expired", "canceled"
  - amountnumberrequired
  - currencystringrequired
  - descriptionstring | nullrequired
  - orderIdstring | nullrequired
  - payerPayerDtorequired
    - firstNamestring
    - lastNamestring
    - emailstring
      Receives the receipt
    - phonestring
  - acceptedProvidersstring[]required
  - providerstring | nullrequired
    Provider of the succeeded attempt, or of the last attempt opened
  - organisationIdstring (uuid)required
  - paymentAccountIdstring (uuid)required
  - channelstringrequired
    - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
  - successUrlstring | nullrequired
  - failUrlstring | nullrequired
  - webhookUrlstring | nullrequired
  - expiresAtstring (date-time)required
  - metadataobjectrequired
  - payUrlstringrequired
    Hosted checkout page of this payment
  - succeededAttemptIdstring (uuid) | nullrequired
  - attemptsCountnumberrequired
  - paymentLinkIdstring (uuid) | nullrequired
    The payment link the payer started from (channel link), null otherwise
  - resultany
    Result summary (API responses only, not in webhook bodies)
  - createdAtstring (date-time)required
  - updatedAtstring (date-time)required
- nextCursorstring | nullrequired

Code samples

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

Example: 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/paymentsAPI key

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.

Parameters

Idempotency-Keystringheader

Request body 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
amountnumberrequired
Integer minor units (millimes for TND)
currencystringrequired
- 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"

Responses

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

Code samples

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

Example: request body

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

Example: 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}API key

Parameters

referencestringpathrequired

Responses

200
- idstring (uuid)required
- referencestringrequired
  24 hexadecimal characters
- statusstringrequired
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
- amountnumberrequired
- currencystringrequired
- descriptionstring | nullrequired
- orderIdstring | nullrequired
- payerPayerDtorequired
  - firstNamestring
  - lastNamestring
  - emailstring
    Receives the receipt
  - phonestring
- acceptedProvidersstring[]required
- providerstring | nullrequired
  Provider of the succeeded attempt, or of the last attempt opened
- organisationIdstring (uuid)required
- paymentAccountIdstring (uuid)required
- channelstringrequired
  - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
- successUrlstring | nullrequired
- failUrlstring | nullrequired
- webhookUrlstring | nullrequired
- expiresAtstring (date-time)required
- metadataobjectrequired
- payUrlstringrequired
  Hosted checkout page of this payment
- succeededAttemptIdstring (uuid) | nullrequired
- attemptsCountnumberrequired
- paymentLinkIdstring (uuid) | nullrequired
  The payment link the payer started from (channel link), null otherwise
- resultany
  Result summary (API responses only, not in webhook bodies)
- createdAtstring (date-time)required
- updatedAtstring (date-time)required
404payment_not_found

Code samples

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

Example: 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}/cancelAPI key

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.

Parameters

referencestringpathrequired

Request body application/json

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

Responses

200
- idstring (uuid)required
- referencestringrequired
  24 hexadecimal characters
- statusstringrequired
  - enum: "pending", "succeeded", "failed", "expired", "canceled"
- amountnumberrequired
- currencystringrequired
- descriptionstring | nullrequired
- orderIdstring | nullrequired
- payerPayerDtorequired
  - firstNamestring
  - lastNamestring
  - emailstring
    Receives the receipt
  - phonestring
- acceptedProvidersstring[]required
- providerstring | nullrequired
  Provider of the succeeded attempt, or of the last attempt opened
- organisationIdstring (uuid)required
- paymentAccountIdstring (uuid)required
- channelstringrequired
  - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
- successUrlstring | nullrequired
- failUrlstring | nullrequired
- webhookUrlstring | nullrequired
- expiresAtstring (date-time)required
- metadataobjectrequired
- payUrlstringrequired
  Hosted checkout page of this payment
- succeededAttemptIdstring (uuid) | nullrequired
- attemptsCountnumberrequired
- paymentLinkIdstring (uuid) | nullrequired
  The payment link the payer started from (channel link), null otherwise
- resultany
  Result summary (API responses only, not in webhook bodies)
- createdAtstring (date-time)required
- updatedAtstring (date-time)required
409payment_not_pending

Code samples

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

Example: request body

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

Example: 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}/timelineAPI key

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).

Parameters

referencestringpathrequired
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

Responses

200
- paymentPaymentDtorequired
  - idstring (uuid)required
  - referencestringrequired
    24 hexadecimal characters
  - statusstringrequired
    - enum: "pending", "succeeded", "failed", "expired", "canceled"
  - amountnumberrequired
  - currencystringrequired
  - descriptionstring | nullrequired
  - orderIdstring | nullrequired
  - payerPayerDtorequired
    - firstNamestring
    - lastNamestring
    - emailstring
      Receives the receipt
    - phonestring
  - acceptedProvidersstring[]required
  - providerstring | nullrequired
    Provider of the succeeded attempt, or of the last attempt opened
  - organisationIdstring (uuid)required
  - paymentAccountIdstring (uuid)required
  - channelstringrequired
    - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
  - successUrlstring | nullrequired
  - failUrlstring | nullrequired
  - webhookUrlstring | nullrequired
  - expiresAtstring (date-time)required
  - metadataobjectrequired
  - payUrlstringrequired
    Hosted checkout page of this payment
  - succeededAttemptIdstring (uuid) | nullrequired
  - attemptsCountnumberrequired
  - paymentLinkIdstring (uuid) | nullrequired
    The payment link the payer started from (channel link), null otherwise
  - resultany
    Result summary (API responses only, not in webhook bodies)
  - createdAtstring (date-time)required
  - updatedAtstring (date-time)required
- attemptsTimelineAttemptDto[]required
  Oldest first
  - idstring (uuid)required
  - numbernumberrequired
    1 for the first attempt of the payment
  - providerstringrequired
  - statusstringrequired
  - externalRefstring | nullrequired
  - amountnumberrequired
  - providerFeenumber | nullrequired
  - affiliationAttemptAffiliationDtorequired
    - affiliationIdstring (uuid)required
    - labelstringrequired
    - environmentstringrequired
      - enum: "sandbox", "production"
    - publicIdentifierstring | nullrequired
      Never a secret
    - credentialVersionnumberrequired
  - checksCountnumberrequired
  - resultAttemptResultDtorequired
    - failureCodestring | nullrequired
      - 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 | nullrequired
      The provider own code
    - providerMessagestring | nullrequired
      The provider message, redacted
    - authorizationCodestring | nullrequired
    - instrumentany | nullrequired
    - initiatedAtstring (date-time) | nullrequired
    - redirectedAtstring (date-time) | nullrequired
    - authorizedAtstring (date-time) | nullrequired
    - completedAtstring (date-time) | nullrequired
    - durationsAttemptDurationsDtorequired
      - initMsnumber | nullrequired
        initiated_at to redirected_at
      - payerMsnumber | nullrequired
        redirected_at to completed_at
      - totalMsnumber | nullrequired
        initiated_at to completed_at
  - createdAtstring (date-time)required
  - rawany
    Admin view only
- webhooksTimelineWebhooksDtorequired
  - deliveriesWebhookDeliveryDto[]required
    - idstring (uuid)required
    - endpointIdstring (uuid)required
    - paymentIdstring (uuid)required
    - eventIdstring (uuid)required
    - eventTypestringrequired
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringrequired
    - statusstringrequired
      - enum: "pending", "delivered", "failed"
    - attemptsnumberrequired
    - lastStatusCodenumber | nullrequired
    - lastErrorstring | nullrequired
    - lastAttemptAtstring (date-time) | nullrequired
    - deliveredAtstring (date-time) | nullrequired
    - lastOutcomestring | nullrequired
      - 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) | nullrequired
    - manualTriesnumberrequired
    - createdAtstring (date-time)required
  - triesWebhookTryDto[]required
    Every HTTP try, oldest first
    - idstring (uuid)required
    - deliveryIdstring (uuid)required
    - endpointIdstring (uuid)required
    - eventIdstring (uuid)required
    - eventTypestringrequired
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringrequired
    - tryNumbernumberrequired
    - triggerstringrequired
      - enum: "automatic", "manual"
    - requestedBystring (uuid) | nullrequired
    - requestHeadersobjectrequired
    - requestBodystringrequired
      The body as sent, byte for byte
    - startedAtstring (date-time)required
    - durationMsnumberrequired
    - outcomestringrequired
      - 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 | nullrequired
    - responseHeadersobject | nullrequired
    - responseExcerptstring | nullrequired
      First 2 KB, redacted
    - errorMessagestring | nullrequired
    - nextRetryAtstring (date-time) | nullrequired
- itemsTimelineItemDto[]required
  Oldest first
  - idstring (uuid)required
  - seqstringrequired
    Timeline order, shared by the three source tables
  - kindstringrequired
    - enum: "payment_event", "attempt_event"
  - typestringrequired
  - categorystringrequired
    - enum: "payment", "checkout", "attempt", "notification", "email", "anomaly", "refund", "reconciliation"
  - occurredAtstring (date-time)required
  - attemptIdstring (uuid) | nullrequired
  - actorTimelineActorDtorequired
    - typestringrequired
      - enum: "system", "merchant_user", "api_key", "payer", "provider", "admin"
    - idstring | nullrequired
      User or API key id
  - sourcestringrequired
    - enum: "merchant_api", "dashboard", "checkout", "provider_callback", "poller", "outbox_worker", "admin_console", "system", "init", "callback", "poll", "manual"
  - fromStatusstring | nullrequired
  - toStatusstring | nullrequired
  - detailsobjectrequired
    Redacted
  - attemptEventAttemptEventDto
    - idstring (uuid)required
    - typestringrequired
    - fromStatusstring | nullrequired
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - toStatusstring | nullrequired
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - sourcestringrequired
      - enum: "init", "callback", "poll", "manual"
    - detailsobjectrequired
      Redacted
    - createdAtstring (date-time)required
  - webhookTryWebhookTryDto
    - idstring (uuid)required
    - deliveryIdstring (uuid)required
    - endpointIdstring (uuid)required
    - eventIdstring (uuid)required
    - eventTypestringrequired
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringrequired
    - tryNumbernumberrequired
    - triggerstringrequired
      - enum: "automatic", "manual"
    - requestedBystring (uuid) | nullrequired
    - requestHeadersobjectrequired
    - requestBodystringrequired
      The body as sent, byte for byte
    - startedAtstring (date-time)required
    - durationMsnumberrequired
    - outcomestringrequired
      - 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 | nullrequired
    - responseHeadersobject | nullrequired
    - responseExcerptstring | nullrequired
      First 2 KB, redacted
    - errorMessagestring | nullrequired
    - nextRetryAtstring (date-time) | nullrequired
- nextCursorstring | nullrequired
- eventTypesVersionnumberrequired
  PAYMENT_EVENT_TYPES_VERSION of packages/domain
404payment_not_found

Code samples

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

Example: 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}/attemptsAPI key

Parameters

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

Responses

200
- itemsAttemptDto[]required
  - idstring (uuid)required
  - paymentIdstring (uuid)required
  - providerstringrequired
    - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
  - statusstringrequired
    - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
  - externalRefstring | nullrequired
  - amountnumberrequired
  - currencystringrequired
  - providerFeenumber | nullrequired
  - affiliationAttemptAffiliationDtorequired
    - affiliationIdstring (uuid)required
    - labelstringrequired
    - environmentstringrequired
      - enum: "sandbox", "production"
    - publicIdentifierstring | nullrequired
      Never a secret
    - credentialVersionnumberrequired
  - nextCheckAtstring (date-time) | nullrequired
  - checksCountnumberrequired
  - resultAttemptResultDtorequired
    - failureCodestring | nullrequired
      - 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 | nullrequired
      The provider own code
    - providerMessagestring | nullrequired
      The provider message, redacted
    - authorizationCodestring | nullrequired
    - instrumentany | nullrequired
    - initiatedAtstring (date-time) | nullrequired
    - redirectedAtstring (date-time) | nullrequired
    - authorizedAtstring (date-time) | nullrequired
    - completedAtstring (date-time) | nullrequired
    - durationsAttemptDurationsDtorequired
      - initMsnumber | nullrequired
        initiated_at to redirected_at
      - payerMsnumber | nullrequired
        redirected_at to completed_at
      - totalMsnumber | nullrequired
        initiated_at to completed_at
  - eventsAttemptEventDto[]required
    Timeline, oldest first
    - idstring (uuid)required
    - typestringrequired
    - fromStatusstring | nullrequired
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - toStatusstring | nullrequired
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - sourcestringrequired
      - enum: "init", "callback", "poll", "manual"
    - detailsobjectrequired
      Redacted
    - createdAtstring (date-time)required
  - createdAtstring (date-time)required
  - updatedAtstring (date-time)required
- nextCursorstring | nullrequired
404payment_not_found

Code samples

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

Example: 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"
}