Reconcile payments, audit calls

The five endpoints

All five share the same base URL, the same authentication model, and the same response envelope. Every request is a POST with a JSON body.

Environments

Authentication

There are two ways to authenticate. Both keys are configured under Account Security → API secret key in the SecureFlow merchant portal.

• X-API-KEY header — a static key. Simple to set up, no rotation required. Fine for internal scripts and server-to-server integrations where you control the environment.
• ACCESS-TOKEN header — a short-lived token issued via the Enhanced API Security licence. Expires after one hour; you rotate it with a refresh token. Use this if you need stricter key hygiene or regular rotation.

Getting an access token (Enhanced API Security)

Three steps:

1. In the merchant portal, go to API secret key → Generate Tokens. This issues a client_id, client_secret, and a refresh_token.
2. Exchange them at POST /api/authorize by sending client_id and client_secret as form fields. The response includes an access_token (valid for one hour) and a new refresh_token.
3. Before the token expires, call POST /api/refresh_token with the same fields plus refresh_token. You'll get a fresh pair back.

// POST /api/authorize — response
{
  "httpStatus": true,
  "refresh_token": "M+ixxr3jST3uPlVFQmbCpiDr+ea12WLyQvRQUjSEK1w=",
  "access_token": "kQ3bwoO+k2ol6YL9dcD9QSON2GhrMuGSjf8OigtY3jo=",
  "expire_time": "2024-03-15 14:05:57",
  "status": { "statusCode": 200, "statusDescription": "success" }
}

Treat access_token as ephemeral and rotate it before expire_time. A 400 with the message "Access token expired, please generate again using refresh token" means you left it too late.

Response envelope

Every endpoint wraps its result in the same shape:

{
  "httpStatus": true,
  "reference_id": "your-echoed-ref",
  "status": {
    "statusCode": 200,
    "statusDescription": "success"
  },
  "data": [ ... ]
}

httpStatus is true on success, false on error. reference_id echoes whatever you sent in the request, so you can correlate calls in your own logs. data is always an array — empty on no results.

Error codes

All five endpoints return the same error shapes. The most common ones you'll see:

Payment history — POST /api/payment_taken

Returns paginated payment transaction records. All parameters are optional — call with none to get the most recent transactions.

Each record in the data array includes:

• unique_id — Paytia transaction identifier
• cdr_id — linked call record (if the payment came from a phone call)
• txn_type — transaction type, e.g. Charge immediately
• first_name, last_name, company_name
• agent_name — the agent who handled the call
• card_last_four_digit, card_brand
• reference_no, account_number
• datetime — in DD-MM-YYYY HH:MM:SS format
• currency, net, tax, total_sell_price
• transaction_charge, processing_charge, paytia_brand_fee
• status — success, failed, or pending
• acquirer_message — the gateway's response message
• gateway_nickname — which gateway processed it
• metadata, custom_metadata_fields

// Sample request
{
  "reference_id": "ref-recon-001",
  "start_date": "2026-06-01",
  "end_date": "2026-06-30",
  "status": "success",
  "limit_per_page": 100,
  "page": 1
}

CDR logs — POST /api/manage_cdr_logs

Returns Call Detail Record logs. If you don't supply date parameters, the default window is the last seven days to today.

Each CDR record includes:

• cdr_id — unique call identifier (used by the three detail endpoints below)
• agent_id
• originator — customer or agent-side
• merchant_email
• call_from, call_to_paytia, call_to — E.164 numbers
• start_time, end_time
• ringing, answer_talking, total_duration — in HH:MM:SS

CDR detail — POST /api/view_cdr_log

Fetches the full leg-level detail for a single call, identified by cdr_id. You'll typically call this after finding the record you want via /api/manage_cdr_logs.

The response data contains inbound and outbound leg fields. Fields prefixed in* describe the inbound leg — DDI (inddi), CLI (incli), state (instate), and timestamps (intimes, intimee, intimea). Fields prefixed out* describe the outbound leg. The state and hang* fields describe call-setup progress and hang-up cause.

// Sample request
{
  "reference_id": "ref-debug-001",
  "cdr_id": "i-0b943301f1597b410-49662"
}

API trace — POST /api/view_api_details_cdr

Returns the exact request/response pair that Paytia exchanged with the merchant endpoint during a call. Useful for debugging unexpected IVR behaviour or replaying a scenario to understand what was sent and received.

The response includes:

• uri — the merchant endpoint Paytia called
• method — HTTP method used
• request_params — the serialised request Paytia sent
• response — what the merchant endpoint returned
• actual_response — the final response value
• time — timestamp of the API call

Pair this with /api/view_cdr_log to get the full picture: the call legs plus the API exchange that drove the payment decision.

Webhook delivery logs — POST /api/webhook_request_data

Shows exactly what Paytia posted to your webhook_url for a given call, and how your endpoint responded. If a webhook is showing as failed in your logs, this is the first place to look.

The response data shows:

• webhook_response — the full JSON payload Paytia sent to your endpoint
• http_code — the HTTP status your endpoint returned (0 means no response received)
• description — brief and tooltip descriptions of the outcome
• status — success or failed
• date_time — when the delivery was attempted

Pair this with /api/payment_taken when you need an end-to-end audit: pull the transaction record to confirm what was charged, then pull the webhook log to confirm what your system was told.

For general webhook integration — subscribing, payload format, retry behaviour — see the Webhooks reference.

Support

Postman collections for all five endpoints are available on request. Write to techsupport@paytia.com.