---
title: "Retrieve Failed Agreements"
method: POST
path: "/gateway/failedAgreement.json"
tags: ["Telr Agreement APIs"]
---

# Retrieve Failed Agreements

`POST /gateway/failedAgreement.json`

Retrieves agreements in FAILED status whose most recent failure event falls within the given date range. Maximum date range: 31 days. A duplicate-request lock prevents concurrent requests for the same store and auth key.

## Request body

- object
  - `FailedAgreement` object, required
    - `storeid` string, required — Your Store ID.
    - `authkey` string, required — Authentication key. Found in Merchant Admin → Integrations → Hosted Payment Page → Configuration → Authentication Key.
    - `Fromdate` string, date, required — Start date for filtering. Format: YYYY-MM-DD.
    - `Todate` string, date, required — End date for filtering. Format: YYYY-MM-DD. Range cannot exceed 31 days.

## Response `200`

Successful response with failed agreements data or error information.

- union
  - object
    - `FailedAgreementResponse` object
      - `Code` integer
      - `Status` string
      - `data` FailedAgreementItem[]
        - `DeclineTranRef` string — Transaction reference of the last failed/declined attempt.
        - `AgreementID` integer — Unique identifier for the agreement.
        - `StoreID` integer — Store ID.
        - `AgreementCreatedDate` string, date — Date the agreement was created.
        - `CurrencyCode` string — ISO 4217 currency code.
        - `InitialPayment` string — Initial payment amount in major currency units (minor units ÷ 100).
        - `RegularPayment` string — Regular recurring amount in major currency units.
        - `FinalPayment` string — Final payment amount in major currency units.
        - `TotalNoOfInstallments` integer — Maximum number of recurring payments configured.
        - `BillingPeriod` string — Billing period code: M=monthly, W=weekly, S=semi-weekly, T=twice-monthly.
        - `BillingInterval` integer — Number of billing period units between payments.
        - `CartDescription` string — Agreement-level cart description.
        - `CartId` string — Agreement-level cart identifier.
        - `CustomerId` string — Merchant-supplied customer identifier.
        - `PaymentMethod` string — Payment method: Card, Invoice, or Not Applicable.
        - `CardExpiryMonth` integer — Card expiry month (1–12).
        - `CardExpiryYear` integer — Card expiry year (4-digit).
        - `CardExpiryDate` string — Card expiry formatted as MM/YYYY (note: includes trailing space).
        - `BillForname` string — Billing first name.
        - `BillSurname` string — Billing surname.
        - `BillAddress1` string — Billing address line 1.
        - `BillAddress2` string — Billing address line 2.
        - `BillAddress3` string — Billing address line 3.
        - `BillCity` string — Billing city.
        - `BillRegion` string — Billing region or state.
        - `BillCountry` string — Billing country code.
        - `BillZipCode` string — Billing postal code.
        - `BillEmail` string, email — Billing email address.
        - `BillTelephone` string — Billing telephone number.
        - `LastSuccessDate` string, date — Date of the last successful payment.
        - `AgreementFailedDate` string, date — Date the agreement entered FAILED status.
        - `AgreementStatus` string — Current agreement status: Running, Completed, Failed, Overdue, Canceled, or Not Applicable.
        - `TransactionDescription` string — Description from the last failed transaction.
        - `Amount` string — Last attempted transaction amount in major currency units.
        - `ReasonForFailure` string — Acquirer message describing the failure reason.
        - `LastDefaultCategory` string — Days-overdue category: N=before due, A=0–31 days, B=32–90 days, C=>90 days.
        - `AcquirerText` string — Acquirer secondary response text.
        - `AcquirerMessage` string — Acquirer response message.
        - `FailedCategory` string — System failure category: System Failed or Category1 failed.
        - `BinNumber` string — First 6 digits of the card (BIN).
        - `CardIssuingCountry` string — Country name of the card-issuing bank.
        - `PaymentType` string — Card scheme or payment type (e.g. Visa, Mastercard, SADAD, STC Bank).
        - `PaymentInfo` string — Masked card number (e.g. 411111****1111) or non-card payment reference.
  - ErrorResponse
    - `code` integer — Error code
    - `status` string — Request status
    - `reason` string — Error reason
    - `errors` string[]

---

[API](https://skmtc.dev/telr/apis/remote-json-api-1-0.md) · [All operations](https://skmtc.dev/telr/apis/remote-json-api-1-0/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/telr/remote-json-api-1-0/revisions/7a1969c709ba/schema)