---
title: "Retrieve a Payment Agreement"
method: GET
path: "/v1/payment-agreements/{agreement-id}"
tags: ["Payment Agreements"]
---

# Retrieve a Payment Agreement

`GET /v1/payment-agreements/{agreement-id}`

## Path parameters

- `agreement-id` string, required

## Headers

- `Merchant-Id` string, required

## Response `200`

OK

- AgreementResponse
  - `id` string — The payment agreement ID
  - `status` 'INITIALIZING' | 'AUTHENTICATION_PENDING' | 'AUTHORIZATION_PROCESSING' | 'ACTIVE' | 'REVOKED_BY_CONSUMER' | 'REVOKED_BY_MERCHANT' | 'REVOKED_BY_PROVIDER' | 'FAILED' — The payment agreement status
  - `failure` ProcessingFailure
    - `failureType` 'INTERNAL_ERROR' | 'INTERNAL_DECLINE' | 'PROVIDER_ERROR' | 'PROVIDER_DECLINE' — The failure type.
    - `failureCode` string — The failure code.
    - `providerFailureCode` string — The payment provider failure code.
    - `failureMessage` string — The failure message.
    - `isRetryable` boolean — Indicates whether the merchant should create a fresh new attempt, where initiating a fresh new attempt at a later time may potentially result in a successful outcome.
    - `additionalData` AdditionalData
      - `merchantAdviceCode` string — Merchant Advice Code (MAC) returned by the payment network on decline, indicating whether and when the payment may be retried.
      - `merchantAdviceCodeText` string — Human-readable explanation of the Merchant Advice Code (MAC).
  - `description` string — The description of the agreement
  - `merchantPaymentAgreementReference` string — The merchant payment agreement reference
  - `paymentMethod` string — The payment method which was used to process the payment charge.
  - `frequency` Frequency
    - `type` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY' | 'UNSCHEDULED', required — The type of frequency between consecutive payment charges.
    - `interval` integer — The interval between consecutive payment charges. The unit of the interval depends on the frequency type. For example, if type is MONTHLY and interval is 3, it means every 3 months.
  - `startDate` string, date-time — The start date of the agreement
  - `endDate` string, date-time — The end date of the agreement
  - `amount` Money — The operation amount
    - `value` integer, required — The monetary value to be charged or processed, expressed in the smallest currency unit (e.g., cents for EUR).
    - `currency` string, required — The three-letter ISO 4217 currency code representing the currency in which the amount is denominated
  - `instrumentId` string — The ID of the payment instrument associated with the agreement.
  - `instrumentUpdated` boolean — Indicates that the Payment Instrument has been updated during processing. Query Payment Instruments to retrieve the new details.
  - `amountType` 'MAX' | 'EXACT' | 'VARIABLE' — Defines if the provided 'amount' is a maximum value or an exact value.
  - `consumer` Consumer
    - `name` string — The consumer name.
    - `email` string — The consumer email.
    - `phone` string — The consumer phone number.
    - `country` string — 2-letter ISO code of the country where the payment instrument or account has been issued or established (for example GB, US, DE).
    - `locale` string — The locale describing the preferred language of the consumer
    - `taxIdentification` string — The consumer's tax identification number, like CUIT in Argentina, CPF in Brazil, RUT in Chile, NIF in Spain or Portugal, Numéro fiscal in France, and Codice Fiscale in Italy, or the equivalent tax identifier applicable in the consumer's country.
    - `merchantConsumerReference` string — The merchant provided consumer reference.
    - `billingAddress` Address
      - `street` string, required
      - `city` string, required
      - `region` string
      - `postalCode` string — Required for countries that use postal codes. This field can be omitted for the following country codes: AO,AI,AG,AW,BS,BZ,BJ,BM,BO,BQ,BW,CF,TD,KM,CG,CD,CK,CI,CW,DJ,DM,TL,GQ,ER,FJ,TF,GA,GM,GY,GD,HK,HM,IO,MO,MH,MS,NR,NU,NF,PW,PA,WS,KN,LC,VC,ST,SC,SL,SX,SB,SS,GS,SH,TC,TK,TO,TV,UG,AE,VA,VU,YE,ZW
      - `country` string, required — ISO 3166-1 alpha-2 Country Code
    - `client` Client
      - `ip` string — The IP address of the client
      - `userAgent` string — The user agent of the client device
  - `authenticationMethods` union[] — The available authentication methods for the authorization.
    - union
      - AppIntentAuthenticationMethod
        - `type` 'APP_INTENT', required — The APP_INTENT authentication type.
        - `details` AppIntentAuthenticationDetails
          - `mobileIntentUri` string — Intent URI to be used for app-to-app mobile flows.
      - AppNotificationAuthenticationMethod
        - `type` string, required
      - MultiFactorAuthenticationMethod
        - `type` string, required
      - RedirectAuthenticationMethod
        - `type` 'REDIRECT', required — The REDIRECT authentication type.
        - `details` RedirectAuthenticationDetails
          - `requestUrl` string — The URL where the consumer should be redirected in order to authenticate the payment.
          - `requestMethod` 'GET' | 'POST' — The redirect HTTP method.
      - ScanCodeAuthenticationMethod
        - `type` 'SCAN_CODE', required — The SCAN_CODE authentication type.
        - `details` ScanCodeAuthenticationDetails
          - `codeType` 'QR' | 'UPC' | 'ITF' | 'CODE128' | 'PAYMENT_REFERENCE' — The type of the scan or of the code payload.
          - `codeImage` string — The pre-generated scan code image for the ease of integration.
          - `codePayload` string — The payload for the scan code or for the reference to construct the image or the UX on the partners side.
          - `codeDocument` string — The URL of the pdf/html pay slip document.
          - `codeProviderEntityId` string — The identifier of the code provider entity.
          - `scanBy` string, date-time — The custom expiry timestamp (ISO 8601 format) before which the consumer is expected to complete the payment.
      - ThreeDsAuthenticationMethod
        - `type` '3DS', required — The `3DS` authentication type.
        - `details` ThreeDsAuthenticationDetails
          - `requestUrl` string — The URL where the consumer should be redirected in order to complete the 3D Secure authentication.
          - `requestMethod` 'GET' | 'POST' — The redirect HTTP method.
  - `history` HistoryEntryResponse[] — History of changes regarding the agreement status
    - `id` string — The history entry ID
    - `status` 'INITIALIZING' | 'AUTHENTICATION_PENDING' | 'AUTHORIZATION_PROCESSING' | 'ACTIVE' | 'REVOKED_BY_CONSUMER' | 'REVOKED_BY_MERCHANT' | 'REVOKED_BY_PROVIDER' | 'FAILED' — The history entry status
    - `failure` ProcessingFailure
      - `failureType` 'INTERNAL_ERROR' | 'INTERNAL_DECLINE' | 'PROVIDER_ERROR' | 'PROVIDER_DECLINE' — The failure type.
      - `failureCode` string — The failure code.
      - `providerFailureCode` string — The payment provider failure code.
      - `failureMessage` string — The failure message.
      - `isRetryable` boolean — Indicates whether the merchant should create a fresh new attempt, where initiating a fresh new attempt at a later time may potentially result in a successful outcome.
      - `additionalData` AdditionalData
        - `merchantAdviceCode` string — Merchant Advice Code (MAC) returned by the payment network on decline, indicating whether and when the payment may be retried.
        - `merchantAdviceCodeText` string — Human-readable explanation of the Merchant Advice Code (MAC).
    - `createdAt` string, date-time — The history entry timestamp
  - `revocations` RevocationResponse[] — Agreement revocation attempts
    - `id` string — The revocation ID
    - `revocationStatus` 'REVOKED_BY_CONSUMER' | 'REVOKED_BY_PROVIDER' | 'REVOKED_BY_MERCHANT' | 'REVOCATION_FAILED' — The revocation status
    - `failure` ProcessingFailure
      - `failureType` 'INTERNAL_ERROR' | 'INTERNAL_DECLINE' | 'PROVIDER_ERROR' | 'PROVIDER_DECLINE' — The failure type.
      - `failureCode` string — The failure code.
      - `providerFailureCode` string — The payment provider failure code.
      - `failureMessage` string — The failure message.
      - `isRetryable` boolean — Indicates whether the merchant should create a fresh new attempt, where initiating a fresh new attempt at a later time may potentially result in a successful outcome.
      - `additionalData` AdditionalData
        - `merchantAdviceCode` string — Merchant Advice Code (MAC) returned by the payment network on decline, indicating whether and when the payment may be retried.
        - `merchantAdviceCodeText` string — Human-readable explanation of the Merchant Advice Code (MAC).
    - `createdAt` string, date-time — The revocation timestamp
  - `initialPaymentChargeId` string — The payment charge ID of the initial charge generated by this agreement
  - `initialSchemeAuthorizationReference` string — The initial scheme authorization reference, eg. for cards network transaction identifier (NTI)
  - `initialTransactionLinkReference` string — Transaction Link Reference or Id (ex: Mastercard TLID) is a unique identifier for a transaction, used by some card networks for transaction chain linking, this is in addition to Network Transaction Identifiers. Provide the initial TLID when creating the subsequent Merchant-Initiated-Transactions.
  - `createdAt` string, date-time — The agreement creation timestamp in ISO 8601 format.
  - `updatedAt` string, date-time — The agreement update timestamp in ISO 8601 format.
  - `labels` object — Custom labels associated with this payment agreement.

## Other responses

- `504` — Call to the upstream dependency timed out.

---

[API](https://skmtc.net/ppro/apis/payment-charges.md) · [All operations](https://skmtc.net/ppro/apis/payment-charges/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ppro/payment-charges/versions/112e8bb4c815/schema)