Skip to main content

Retrieve Agreement

GET 
/v1/agreements/:id

Retrieve a single agreement, including every order submitted against it (brief view of each order).

Required permission: agreements_read.

Request​

Path Parameters

    id uuidrequired

    Agreement UUID (internal database ID, not the merchant-chosen agreement_id).

Responses​

The agreement with nested orders.

Schema

    id stringrequired

    Merchant-chosen agreement identifier (the id supplied in new_agreement.id at creation). Use this value as agreement_id on follow-up transactions.

    type stringrequired

    Possible values: [unscheduled, recurring, registered, installment]

    first_order_id uuid

    ID of the order that established this agreement.

    max_use integernullable
    variability stringrequired

    Possible values: [fixed, variable]

    expiry datenullable
    active booleanrequired

    false once the agreement has been disabled via PUT /v1/agreements/:id/disable. Disabled agreements reject new transactions.

    created_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

    updated_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

    orders

    object[]

    required

    All orders submitted against this agreement (brief view of each).

  • Array [

    • id uuidrequired

    A 36-character UUIDv7 identifier. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

    merchant

    object

    required

    Brief representation of the merchant that owns the resource.

    id uuidrequired

    A 36-character UUIDv7 identifier. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

    name stringrequired

    Merchant display name (English).

    merchant_id stringrequired

    Stable, human-readable merchant identifier assigned by the acquirer. Often used as the merchant's principal reference in scheme reports.

    arabic_name string

    Merchant display name in Arabic, when configured.

    currency Currency (string)required

    Possible values: Value must match regular expression ^[A-Z]{3}$

    ISO 4217 three-letter currency code in uppercase.

    The currency must match the currency configured for the merchant's scheme-level terminals. Once an order is created, its currency is immutable: every subsequent capture, void, refund and extension is denominated in the same currency.

    amount Amount (integer)required

    Possible values: <= 100000000

    A non-negative integer representing a monetary value in the smallest currency unit for the associated currency (minor units).

    Examples:

    • 1.00 SAR is sent as 100
    • 1.00 KWD is sent as 1000
    • 1 JPY is sent as 1

    For most order-creating endpoints the minimum is 100 (one full major unit). Endpoints that support zero-value operations (such as /v1/orders/verify and /v1/orders/:id/extend) allow 0.

    captured_amount integerrequired
    refunded_amount integerrequired
    voided_amount integerrequired
    description string
    created_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

    updated_at date-timerequired

    ISO 8601 UTC timestamp with time zone designator.

    source

    object

    required

    Polymorphic payment source. The type discriminator resolves to either a Card or a DevicePayToken (Apple / Google / Samsung Pay).

    oneOf

    Card payment source. Sensitive fields (full PAN, CVV) are never returned; responses expose only BIN (first_digits) and PAN last-four, plus network metadata resolved from the BIN tables.

    type stringrequired

    Possible values: [card]

    issuer stringnullable

    Human-readable issuing bank name, resolved from the BIN.

    card_type stringnullable

    Card product type — CREDIT, DEBIT, CHARGE, etc.

    category stringnullable

    Issuer product tier (e.g. PLATINUM, SIGNATURE, INFINITE). Free-text, sourced from the BIN table.

    country_alpha2 Country (string)

    Possible values: Value must match regular expression ^[A-Z]{2}$

    Country where the card was issued (from BIN).

    scheme Scheme (string)required

    Possible values: [visa, mastercard, mada, amex]

    The card scheme (network) associated with the card. mada is detected from the issuing BIN and takes precedence over Visa / Mastercard co-branding for Saudi-issued cards.

    card_auth_scheme stringnullable

    Scheme that performed 3DS authentication for this card. May differ from scheme for co-branded cards (e.g. mada card authenticated via Visa as the parent scheme).

    first_digits stringrequired

    First six digits of the PAN (the BIN).

    last_digits stringrequired

    Last four digits of the PAN.

    month integerrequired

    Possible values: >= 1 and <= 12

    year integerrequired

    Possible values: >= 2000

  • ]

Loading...