Payment agreement

A payment agreement serves as a container object that groups and manages multiple payment charges. It is specifically designed to support recurring payments, particularly merchant-initiated transactions (MIT), where payments occur on a predefined schedule. Learn more about recurring payments.

By using payment agreements, you benefit from:

Subscription lineage; being able to refer to the history or trail of a consumer's subscription over time
Proof of initial authentication and mandate agreement
Reduced complexities such as not having to identify the initial scheme authorization reference
Future enhancements to recurring payments will only be possible through payment agreements:
- Scheduling
- Smart retries
- Automated agreement management

❗️
Some payment methods require payment agreements to support recurring payment flows. We strongly recommend implementing support for payment agreements to make it easier to scale as you add more payment methods.

You create payment agreements using the Create a Payment Agreement call. Some payment methods require additional data fields to create a valid agreement. Be sure to consult the documentation for your specific payment method to see the full list of required fields.

Initial payment charge

When creating an agreement, you can optionally include an initialPaymentCharge object. This will immediately create the first payment charge under that agreement during the agreement setup.

This is necessary for some payment methods where the consumer can only accept a recurring agreement with the merchant after the first payment has been made.

📘
Even if the initial payment charge has a status of FAILED, the payment agreement can still be successfully authenticated and marked as ACTIVE.
• In such cases, the agreement can and should be used to reattempt the payment.
• The shipment of goods or provision of services should only occur after a successful payment charge notification.

Payment agreement lifecycle

INITIALIZING The initial status when a payment agreement is created.
From this status the payment agreement can move to AUTHENTICATION_PENDING or ACTIVE.

AUTHENTICATION_PENDING This status applies to agreements that require consumer authentication. You'll receive a list of standard authenticationMethods[] that can be used to authenticate the consumer.
From this status the payment agreement can move to ACTIVE or FAILED.

ACTIVE The payment agreement is active and can immediately be used to create subsequent payment charges.
From this status the payment agreement can move to REVOKED_BY_CONSUMER, REVOKED_BY_MERCHANT or REVOKED_BY_PROVIDER.

FAILED The authentication was rejected by the scheme or network. This is a final status, and a new payment instrument must be created if you wish to proceed.

REVOKED_BY_CONSUMER The payment agreement was revoked by the consumer. This is a final status, it cannot be reversed and the payment agreement can no longer be used.

REVOKED_BY_MERCHANT The payment agreement was revoked by the merchant either through the Revoke a Payment Agreement call or PPRO Dashboard. This is a final status, it cannot be reversed and the payment agreement can no longer be used.

REVOKED_BY_PROVIDER The payment agreement was revoked by the scheme or network. This is a final status, it cannot be reversed and the payment agreement can no longer be used.

Entity relationship model

See the diagram below for an overview of the relationship between a payment agreement and our other core API objects:

Each payment agreement has one payment instrument and can contain multiple payment charges.

A payment instrument can be related to multiple payment agreements. For example, a consumer may link their PayPal account with Microsoft and can be charged for Office 365 and Xbox subscriptions.