🔗 API Integration

Get Payment Details API

This endpoint retrieves detailed information about a specific payment, including its status, transactions, and related wallet information.

Endpoint

GET /payments/:paymentId

Path Parameters

ParameterRequiredTypeDescriptionExample
paymentIdYesstringUnique identifier of the payment5e68ed190a43a43998c6eeba

Response

Example

{
  "payment": {
    "id": "87a4c597cb3c15311bdbd547",
    "status": "pending",
    "amountDue": 2000,
    "reachedAmount": 1000,
    "amount": 1000,
    "token": "TND",
    "convertedAmount": 15000,
    "exchangeRate": 1,
    "expirationDate": "2020-10-15",
    "shortId": "-PJfSz90m",
    "link": "https://api.dev.konnect.network/WSlQUtBF8",
    "webhook": "merchant.tech/api/notification_payment",
    "successUrl": "https://dev.konnect.network/gateway/payment-success",
    "failUrl": "https://dev.konnect.network/gateway/payment-failure",
    "orderId": "123456",
    "type": "immediate",
    "details": "t-shirts payments",
    "acceptedPaymentMethods": ["wallet", "bank_card", "e-DINAR", "flouci"],
    "receiverWallet": {
      // Wallet details here (truncated for brevity)
    },
    "transactions": [
      // Transaction details here (truncated for brevity)
    ]
  }
}

Common Errors

  1. Payment Not Found

    • Status Code: 404
    • Cause: Invalid or non-existent paymentId
    • Solution: Verify the payment ID is correct

  2. Invalid Authentication

    • Status Code: 401
    • Cause: Missing or invalid API key
    • Solution: Ensure valid API key is included in headers

  3. Expired Payment

    • Status: Payment exists but has expired
    • Solution: Check expirationDate field and initialize new payment if needed

Payment Status

You have to rely on the Payment Status, not the transaction status.

The payment status can be determined by checking two fields:

  1. Payment Status (payment.status):

    • completed: Payment was successful
    • pending: Payment has failed or hasn't been attempted yet

  2. Transaction Status (payment.transactions[].status):

    • success: Transaction was successful
    • Other statuses indicate various failure or pending states

Test

Best Practices

  1. Regular Status Checking

    • Implement polling with appropriate intervals
    • Respect rate limits
    • Use webhooks for real-time updates

  2. Transaction Verification

    • Always verify both payment.status and transaction status
    • Check reachedAmount against expected amount for partial payments
    • Validate transaction currency and amount

  3. Error Handling

    • Implement proper error handling for all API responses
    • Log payment IDs and transaction IDs for troubleshooting
    • Monitor failed transactions for patterns

Rate Limits

  • Standard rate limit: 100 requests per minute
  • Implement exponential backoff for polling
  • Consider using webhooks for real-time updates instead of infinite polling
WebhookOverview