---
title: "Create a Payment Agreement"
method: POST
path: "/v1/payment-agreements"
tags: ["Payment Agreements"]
---

# Create a Payment Agreement

`POST /v1/payment-agreements`

## Headers

- `Merchant-Id` string, required

## Request body

- AgreementRequest
  - `paymentMethod` string, required — The payment method which should be used to process the payment charge.
  - `paymentMedium` 'ECOMMERCE' | 'MOTO' | 'POS' — The payment medium.
  - `description` string — The description of the agreement
  - `merchantPaymentAgreementReference` string — The merchant payment agreement reference.
  - `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
  - `amountType` 'MAX' | 'EXACT' | 'VARIABLE' — Defines if the provided 'amount' is a maximum value or an exact value.
  - `instrumentId` string — The identifier of an existing payment instrument. Instruments are used for account on file payments.
  - `instrument` union — The payment instrument
    - BancontactAccountInstrument
      - `type` 'BANCONTACT_ACCOUNT', required — The BANCONTACT_ACCOUNT payment instrument type.
      - `details` BancontactAccount, required
        - `bin` string
        - `last4Digits` string
        - `expiryMonth` integer
        - `expiryYear` integer
        - `panAlias` string
    - BankAccountInstrument
      - `type` 'BANK_ACCOUNT', required — The BANK_ACCOUNT payment instrument type
      - `details` BankAccountDetails, required
        - `accountNumber` string — The account number.
        - `holderName` string — The account holder name.
        - `iban` string — The IBAN.
        - `swiftCode` string — The SWIFT code.
        - `bankName` string — The bank name.
        - `bankCode` string — The bank code.
        - `debitMandateId` string — The reference id for a mandate that allows debit charges on the bank account.
    - CardNetworkTokenInstrument
      - `type` 'CARD_NETWORK_TOKEN', required — The CARD_NETWORK_TOKEN payment instrument type
      - `details` CardNetworkTokenDetails, required
        - `brand` string
        - `holderName` string
        - `expiryMonth` integer
        - `expiryYear` integer
        - `tokenNumber` string
        - `eci` string
        - `cryptogram` string
    - MockInstrument
      - `type` 'MOCK', required — The MOCK payment instrument type
      - `details` object — The MOCK payment details
    - PassthroughWalletInstrument
      - `type` 'PASSTHROUGH_WALLET', required — The PASSTHROUGH_WALLET payment instrument type.
      - `details` PassthroughWallet, required
        - `fingerprint` string
        - `paymentReference` string
        - `displayIdentifier` string
        - `country` string
        - `fundingType` 'CREDIT' | 'DEBIT'
    - UpiAutopayInstrument
      - `type` 'UPI_AUTOPAY', required — The UPI_AUTOPAY payment instrument type
    - RawCardInstrument
      - `type` 'RAW_CARD', required — The `RAW_CARD` payment instrument type.
      - `details` object, required — The card details
        - `brand` string — The card brand.<br>The value must be provided in uppercase.
        - `number` string, required — The primary account number (PAN) of the card used for the payment.
        - `cvv` string — Card Verification Value used to authenticate the card during a payment.
        - `holderName` string, required — The full name of the cardholder as it appears on the card.
        - `expiryMonth` string, int32, required — The two-digit expiration month of the card.
        - `expiryYear` string, int32, required — The four-digit expiration year of the card.
      - `validate` object — If included, PPRO will try to validate the instrument with a nominal-amount authorization. If validation fails, the instrument creation request will fail
        - `currency` string, required — ISO 4217 3-letter currency code.
        - `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.
  - `paymentSessionId` string — The identifier of the associated payment-session. Payment-sessions are created by the drop-in UI.
  - `consumer` Consumer, required
    - `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
  - `webhooksUrl` string — The URL to which the agreement state changes will be notified
  - `initialPaymentCharge` PaymentCharge
    - `initiator` 'MERCHANT' | 'CONSUMER' — The charge initiator
    - `scheduleType` 'SCHEDULED' | 'SCHEDULED_RETRY' | 'UNSCHEDULED' | 'RECURRING' — Indicates the type of payment charge being processed. Use UNSCHEDULED for a one-off charge not tied to a schedule. Use SCHEDULED for charge that is part of a recurring schedule. Use SCHEDULED_RETRY for a retry attempt of a previously failed scheduled payment. The RECURRING enum is planned for deprecation and should not be used in new implementations.
    - `paymentDescriptor` string — The transaction descriptor (arbitrary string). May be presented to the consumer.
    - `amount` Money, required — 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
    - `autoCapture` boolean — Indicates whether the payment charge should be automatically captured after a successful authorization.
    - `order` Order
      - `orderItems` OrderItem[] — The list of order items.
        - `sku` string — The order item SKU.
        - `category` string — The order item category.
        - `name` string, required — The order item name.
        - `quantity` integer, required — The order item quantity.
        - `amount` integer, required — The amount to pay for each individual item in the payment charge currency's smallest unit.
      - `shippingAddress` 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
      - `industryData` AirlineIndustryData[] — The list of industry specific data.
        - `type` 'AIRLINE', required — The AIRLINE industry data type.
        - `details` AirlineDetails, required
          - `pnr` string — The passenger number record
          - `numberOfPassengers` integer — The number of passengers
          - `airlineCode` string — The airline code
          - `passengerEmail` string — The passenger email
          - `passengerPhone` string — The passenger phone number
          - `passengerName` string — The passenger name
          - `carrierCode` string — The airline carrier code
          - `tripSegments` AirlineTripSegment[] — The trip segment details
            - `fareBasisCode` string — The fare basis code
            - `departureAirportCode` string — The departure airport code
            - `destinationAirportCode` string — The destination airport code
            - `flightNumber` string — The flight number
            - `departureDate` string, date — The departure date
            - `flightCarrierCode` string — The flight carrier code
            - `segmentId` string — The trip segment ID
      - `orderReferenceNumber` string — The merchant's internal order reference (if different from merchantPaymentChargeReference)
      - `totalTaxAmount` integer — The total tax value paid by the consumer for the order (in same currency units as specified by amount.currency)
      - `installmentPlan` InstallmentPlan
        - `numberOfInstallments` integer, required — The number of installments the consumer will split the payment into.
    - `merchantPaymentChargeReference` string — The merchant payment charge reference. Aka, Transaction Reference.
    - `webhooksUrl` string — The URL to which the payment charge state changes will be notified
    - `authenticationSettings` union[] — The authorization authentication settings.
      - union
        - object
          - `type` 'REDIRECT', required — The REDIRECT authentication type settings.
          - `settings` RedirectAuthenticationSettingsDetails — The REDIRECT authentication settings
            - `returnUrl` string — The URL to which the consumer is redirected after completing an action, such as a payment or authentication flow
        - object
          - `type` 'EXTERNAL_3DS', required — The `EXTERNAL_3DS` authentication type.
          - `settings` ExternalThreeDs
            - `authenticationStatus` 'SUCCESS' | 'ATTEMPT_ACKNOWLEDGED' | 'FAILED' | 'AUTHENTICATION_UNAVAILABLE' — The 3DS authentication status code.
            - `authenticationStatusReason` 'CARD_AUTHENTICATION_FAILED' | 'UNKNOWN_DEVICE' | 'UNSUPPORTED_DEVICE' | 'EXCEEDS_AUTHENTICATION_FREQUENCY_LIMIT' | 'EXPIRED_CARD' | 'INVALID_CARD_NUMBER' | 'INVALID_TRANSACTION' | 'NO_CARD_RECORD' | 'SECURITY_FAILURE' | 'STOLEN_CARD' | 'SUSPECTED_FRAUD' | 'TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER' | 'CARDHOLDER_NOT_ENROLLED_IN_SERVICE' | 'TRANSACTION_TIMED_OUT_AT_THE_ACS' | 'LOW_CONFIDENCE' | 'MEDIUM_CONFIDENCE' | 'HIGH_CONFIDENCE' | 'VERY_HIGH_CONFIDENCE' | 'EXCEEDS_ACS_MAXIMUM_CHALLENGES' | 'NON_PAYMENT_TRANSACTION_NOT_SUPPORTED' | 'THREE_RI_TRANSACTION_NOT_SUPPORTED' — The 3DS authentication status reason.
            - `authenticationValue` string — The 3DS authentication CAVV.
            - `authenticationAlgorithm` string — The 3DS authentication CAVV algorithm used.
            - `authenticationMode` 'SCA' | 'FRICTIONLESS' — The 3DS authentication mode.
            - `eci` string — The 3DS authentication ECI.
            - `version` string — The 3DS authentication version.
            - `externalId` string — The 3DS authentication transaction identifier.
            - `externalAcsId` string — The 3DS universally unique transaction identifier assigned by the ACS to identify a single transaction. Canonical format as defined in IETF RFC 4122.
            - `score` string — The 3DS score.
            - `challenge` Challenge
              - …
        - object
          - `type` '3DS', required — The `3DS` authentication type.
          - `settings` ThreeDsAuthenticationSettingsDetails
            - `returnUrl` string — The URL to which the consumer is redirected after completing the 3D Secure authentication flow.
            - `preference` 'CHALLENGE' | 'FRICTIONLESS' — The preferred 3D Secure authentication flow.
        - object
          - `type` 'SCAN_CODE', required — The SCAN_CODE authentication type.
          - `settings` ScanCodeAuthenticationSettingsDetails
            - `scanBy` string, date-time — Custom expiry date in ISO 8601 format.
        - object
          - `type` 'APP_NOTIFICATION', required — The APP_NOTIFICATION authentication type.
          - `settings` AppNotificationAuthenticationSettingsDetails
            - `instrumentProviderIdentity` string — App identifier, for instance email, phone number
        - object
          - `type` 'MULTI_FACTOR', required — The MULTI_FACTOR authentication type.
          - `settings` MultiFactorAuthenticationSettingsDetails
            - `verificationCode` string — Code generated to authenticate the user.
    - `consumer` ConsumerUpdate
      - `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.
      - `client` Client
        - `ip` string — The IP address of the client
        - `userAgent` string — The user agent of the client device
    - `labels` object — Custom labels associated with the payment agreement charge.
  - `authenticationSettings` union[] — The authorization authentication settings.
    - union
      - object
        - `type` 'REDIRECT', required — The REDIRECT authentication type settings.
        - `settings` RedirectAuthenticationSettingsDetails — The REDIRECT authentication settings
          - `returnUrl` string — The URL to which the consumer is redirected after completing an action, such as a payment or authentication flow
      - object
        - `type` 'EXTERNAL_3DS', required — The `EXTERNAL_3DS` authentication type.
        - `settings` ExternalThreeDs
          - `authenticationStatus` 'SUCCESS' | 'ATTEMPT_ACKNOWLEDGED' | 'FAILED' | 'AUTHENTICATION_UNAVAILABLE' — The 3DS authentication status code.
          - `authenticationStatusReason` 'CARD_AUTHENTICATION_FAILED' | 'UNKNOWN_DEVICE' | 'UNSUPPORTED_DEVICE' | 'EXCEEDS_AUTHENTICATION_FREQUENCY_LIMIT' | 'EXPIRED_CARD' | 'INVALID_CARD_NUMBER' | 'INVALID_TRANSACTION' | 'NO_CARD_RECORD' | 'SECURITY_FAILURE' | 'STOLEN_CARD' | 'SUSPECTED_FRAUD' | 'TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER' | 'CARDHOLDER_NOT_ENROLLED_IN_SERVICE' | 'TRANSACTION_TIMED_OUT_AT_THE_ACS' | 'LOW_CONFIDENCE' | 'MEDIUM_CONFIDENCE' | 'HIGH_CONFIDENCE' | 'VERY_HIGH_CONFIDENCE' | 'EXCEEDS_ACS_MAXIMUM_CHALLENGES' | 'NON_PAYMENT_TRANSACTION_NOT_SUPPORTED' | 'THREE_RI_TRANSACTION_NOT_SUPPORTED' — The 3DS authentication status reason.
          - `authenticationValue` string — The 3DS authentication CAVV.
          - `authenticationAlgorithm` string — The 3DS authentication CAVV algorithm used.
          - `authenticationMode` 'SCA' | 'FRICTIONLESS' — The 3DS authentication mode.
          - `eci` string — The 3DS authentication ECI.
          - `version` string — The 3DS authentication version.
          - `externalId` string — The 3DS authentication transaction identifier.
          - `externalAcsId` string — The 3DS universally unique transaction identifier assigned by the ACS to identify a single transaction. Canonical format as defined in IETF RFC 4122.
          - `score` string — The 3DS score.
          - `challenge` Challenge
            - `preference` 'NO_PREFERENCE' | 'NO_CHALLENGE_REQUESTED' | 'CHALLENGE_REQUESTED' | 'CHALLENGE_MANDATED' | 'DATA_ONLY' — The 3DS authentication challenge initialization preference.
            - `outcome` 'CHALLENGE' | 'FRICTIONLESS' | 'DATA_ONLY' — The 3DS authentication challenge outcome.
            - `exemptionReason` 'LOW_VALUE' | 'LOW_RISK' | 'TRUSTED_BENEFICIARY' | 'FIXED_RECURRING' — The 3DS authentication challenge exemption reason.
            - `cancellationReason` 'CARDHOLDER_CANCELLED' | 'REQUESTOR_CANCELLED' | 'TRANSACTION_ABANDONED' | 'TRANSACTION_TIMEOUT_ACS_OTHER' | 'TRANSACTION_TIMEOUT_ACS_CREQ_NOT_RECEIVED' | 'TRANSACTION_ERROR' | 'UNKNOWN' — The 3DS challenge cancellation indicator.Mandatory for CB transactions.
      - object
        - `type` '3DS', required — The `3DS` authentication type.
        - `settings` ThreeDsAuthenticationSettingsDetails
          - `returnUrl` string — The URL to which the consumer is redirected after completing the 3D Secure authentication flow.
          - `preference` 'CHALLENGE' | 'FRICTIONLESS' — The preferred 3D Secure authentication flow.
      - object
        - `type` 'SCAN_CODE', required — The SCAN_CODE authentication type.
        - `settings` ScanCodeAuthenticationSettingsDetails
          - `scanBy` string, date-time — Custom expiry date in ISO 8601 format.
      - object
        - `type` 'APP_NOTIFICATION', required — The APP_NOTIFICATION authentication type.
        - `settings` AppNotificationAuthenticationSettingsDetails
          - `instrumentProviderIdentity` string — App identifier, for instance email, phone number
      - object
        - `type` 'MULTI_FACTOR', required — The MULTI_FACTOR authentication type.
        - `settings` MultiFactorAuthenticationSettingsDetails
          - `verificationCode` string — Code generated to authenticate the user.
  - `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.
  - `labels` object — Custom labels associated with the payment agreement.

## 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)