Retrieve Agreement

Request to retrieve the details stored in the gateway of an agreement between the merchant and a cardholder.

GET https://ap-gateway.mastercard.com/api/rest/version/100 / merchant / {merchantId} / agreement / {agreementId}

Authentication Copied to clipboard

This operation requires authentication via one of the following methods:


  • Certificate authentication.
  • Basic HTTP authentication as described at w3.org. Provide 'merchant.<your gateway merchant ID>' in the userid portion and your API password in the password portion.

Request Copied to clipboard

URL Parameters Copied to clipboard

{merchantId} Copied to clipboard Alphanumeric + additional characters REQUIRED

The unique identifier issued to you by your payment provider.


This identifier can be up to 12 characters in length.


Data may consist of the characters 0-9, a-z, A-Z, '-', '_'

Min length: 1 Max length: 40
{agreementId} Copied to clipboard String REQUIRED

Your identifier for the agreement you have with the payer to process payments.


Data can consist of any characters

Min length: 1 Max length: 100

Fields Copied to clipboard

To view the optional fields, please toggle on the "Show optional fields" setting.

correlationId Copied to clipboard String OPTIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100

Response Copied to clipboard

Fields Copied to clipboard

agreement Copied to clipboard CONDITIONAL

A commercial agreement you have with the payer that allows you to store and use their payment details for later payments.

For example, an agreement to a series of recurring payments (a mobile phone subscription), an agreement to take payment for a purchase by a series of installments (hire purchase), an agreement to make additional payments when required (account top up), or to fulfil a standard industry practice (no show penalty charge).

Do not provide this parameter group if you are storing the payment details for subsequent payer-initiated payments only.

See Credential on File, Cardholder, and Merchant Initiated Transactions for details.

agreement.amountVariability Copied to clipboard Enumeration CONDITIONAL

Indicates if all the payments within the agreement use the same amount or if the amount differs between the payments.

The field must be provided for recurring payment agreements.

Value must be a member of the following list. The values are case sensitive.

FIXED

All payments in the recurring payment agreement have the same amount. Examples include magazine subscriptions or gym memberships.

VARIABLE

The amount for the payments within the recurring payment agreement differs between payments. Examples include usage-based charges like utility or phone bills.

agreement.customData Copied to clipboard String CONDITIONAL

Additional information requested for the agreement which cannot be passed using other available data fields.

This field must not contain sensitive data.

Data can consist of any characters, but sensitive data will be rejected

Min length: 1 Max length: 2048
agreement.expiryDate Copied to clipboard Date CONDITIONAL

Date at which your agreement with the payer to process payments expires.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

agreement.id Copied to clipboard String CONDITIONAL

Your identifier for the agreement you have with the payer to process payments.

When you collect cards from your payers and store them for later use, you must provide an agreement ID when you use the stored values for:

  • Recurring payments: you have an agreement with the payer that authorizes you to automatically debit their account at agreed intervals for fixed or variable amounts. For example, gym membership, phone bills, or magazine subscriptions.
  • Installment payments: you have an agreement with the payer that authorizes you to process multiple payments over an agreed period of time for a single purchase. For example, the payer purchases an item for $1000 and pays for it in four monthly installments.
  • Unscheduled: you have an agreement with the payer that authorizes you to process future payments when required. For example, the payer authorizes you to process an account top-up transaction for a transit card when the account balance drops below a certain threshold.
  • Industry Practice: you have an agreement with the payer that authorizes you to initiate additional transactions to fulfil a standard business practice related to an original payment initiated by the payer. For example, a delayed charge for use of the hotel mini bar after the payer has checked out or a no show penalty charge when the payer fails to show for a booking.
When you first establish an agreement with the payer you should also specify the type of agreement in agreement.type.

Data can consist of any characters

Min length: 1 Max length: 100
agreement.maximumAmountPerPayment Copied to clipboard Decimal CONDITIONAL

The maximum amount for a single payment in the series as agreed with the payer under your agreement with them.

The amount must be provided in the currency of the order.

Data is a decimal number.

Max value: 99999999999999 Min value: 0 Max post-decimal digits: 3
agreement.minimumAmountPerPayment Copied to clipboard Decimal CONDITIONAL

The minimum amount for a single payment in the series as agreed with the payer under your agreement with them.

The amount must be provided in the currency of the order.

Data is a decimal number.

Max value: 99999999999999 Min value: 0 Max post-decimal digits: 3
agreement.minimumDaysBetweenPayments Copied to clipboard Integer CONDITIONAL

The minimum number of days between payments agreed with the payer under your agreement with them.

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

Min value: 1 Max value: 9999
agreement.numberOfPayments Copied to clipboard Integer CONDITIONAL

The number of merchant-initiated payments within the recurring payment agreement.

JSON number data type, restricted to being positive or zero. In addition, the represented number may have no fractional part.

Min value: 1 Max value: 999
agreement.paymentFrequency Copied to clipboard Enumeration CONDITIONAL

The frequency of the payments within the series as agreed with the payer under your agreement with them.

Value must be a member of the following list. The values are case sensitive.

AD_HOC

The agreement if for payments on an ah-hoc basis.

DAILY

The agreement if for a daily payment.

FORTNIGHTLY

The agreement if for a fortnightly payment.

MONTHLY

The agreement if for a monthly payment.

OTHER

The agreement is for payments according to a schedule other than the ones listed in the other enumeration values for this field.

QUARTERLY

The agreement if for a quarterly payment.

TWICE_YEARLY

The agreement if for a payment twice a year.

WEEKLY

The agreement if for a weekly payment.

YEARLY

The agreement if for a yearly payment.

agreement.retailer Copied to clipboard CONDITIONAL

For an installment agreement where the payer purchased goods and/or services from a retailer but entered an installment agreement to pay for this purchase with you, you must provide details about the retailer.

agreement.retailer.abbreviatedTradingName Copied to clipboard String CONDITIONAL

Provide an abbreviation of the retailer's trading name that can be used by the issuer to indicate the retailer on the payer's statement.

Data can consist of any characters

Min length: 1 Max length: 10
agreement.retailer.merchantCategoryCode Copied to clipboard String CONDITIONAL

A 4-digit code used to classify the retailer's business by the type of goods or services it offers.

Data can consist of any characters

Min length: 1 Max length: 4
agreement.retailer.tradingName Copied to clipboard String CONDITIONAL

The retailer's trading name.

Data can consist of any characters

Min length: 1 Max length: 100
agreement.startDate Copied to clipboard Date CONDITIONAL

This is the effective start date for the payment agreement.

Cannot be in the past.

Data must comply with ISO 8601 extended date format, yyyy-mm-dd

agreement.type Copied to clipboard Enumeration CONDITIONAL

The type of commercial agreement that the payer has with you.

Specify the agreement type when you have provided a value for agreement.id and this payment is the first in a series of payments. The default value is OTHER.

The gateway will use the value you specify for subsequent payments in the series.

Value must be a member of the following list. The values are case sensitive.

INSTALLMENT

An agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.

OTHER

An agreement where you want to link related payments for any purpose other than processing recurring, installment, or unscheduled payments. For example, split tender payments.

RECURRING

An agreement where the payer authorizes you to process repeat payments for bills or invoices at agreed intervals (for example, weekly, monthly). The amount might be fixed or variable.

UNSCHEDULED

An agreement where the payer authorizes you to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.

agreement.status Copied to clipboard Enumeration ALWAYS PROVIDED

The status of the agreement (ACTIVE or CANCELLED) as per the issuer or a third-party provider that maintains the agreements.

The gateway obtains/refreshes the status of the agreement when.

You submit a request to the gateway to authorize or cancel an agreement (the gateway passes this information to the regulator/third-party provider)
OR

Your acquirer updates the gateway when the payer has directly cancelled the agreement with their issuing bank.
For all other integrations, the value will be set to UNKNOWN_IN_VERSION.

Value must be a member of the following list. The values are case sensitive.

ACTIVE

The agreement has been registered and is active.

CANCELLED

The agreement is no longer active. It has been cancelled by either you or the payer.

UNKNOWN_IN_VERSION

The status of the agreement is UNKNOWN_IN_VERSION.

correlationId Copied to clipboard String CONDITIONAL

A transient identifier for the request, that can be used to match the response to the request.

The value provided is not validated, does not persist in the gateway, and is returned as provided in the response to the request.

Data can consist of any characters

Min length: 1 Max length: 100
result Copied to clipboard Enumeration ALWAYS PROVIDED

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

FAILURE

The operation was declined or rejected by the gateway, acquirer or issuer

PENDING

The operation is currently in progress or pending processing

SUCCESS

The operation was successfully processed

UNKNOWN

The result of the operation is unknown

Errors Copied to clipboard

error Copied to clipboard

Information on possible error conditions that may occur while processing an operation using the API.

error.cause Copied to clipboard Enumeration

Broadly categorizes the cause of the error.

For example, errors may occur due to invalid requests or internal system failures.

Value must be a member of the following list. The values are case sensitive.

INVALID_REQUEST

The request was rejected because it did not conform to the API protocol.

REQUEST_REJECTED

The request was rejected due to security reasons such as firewall rules, expired certificate, etc.

SERVER_BUSY

The server did not have enough resources to process the request at the moment.

SERVER_FAILED

There was an internal system failure.

error.explanation Copied to clipboard String

Textual description of the error based on the cause.

This field is returned only if the cause is INVALID_REQUEST or SERVER_BUSY.

Data can consist of any characters

Min length: 1 Max length: 1000
error.field Copied to clipboard String

Indicates the name of the field that failed validation.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Data can consist of any characters

Min length: 1 Max length: 100
error.supportCode Copied to clipboard String

Indicates the code that helps the support team to quickly identify the exact cause of the error.

This field is returned only if the cause is SERVER_FAILED or REQUEST_REJECTED.

Data can consist of any characters

Min length: 1 Max length: 100
error.validationType Copied to clipboard Enumeration

Indicates the type of field validation error.

This field is returned only if the cause is INVALID_REQUEST and a field level validation error was encountered.

Value must be a member of the following list. The values are case sensitive.

INVALID

The request contained a field with a value that did not pass validation.

MISSING

The request was missing a mandatory field.

UNSUPPORTED

The request contained a field that is unsupported.

result Copied to clipboard Enumeration

A system-generated high level overall result of the operation.

Value must be a member of the following list. The values are case sensitive.

ERROR

The operation resulted in an error and hence cannot be processed.