Documentation

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.

This is ideal for scenarios such as subscriptions, installment plans, or usage-based billing, allowing merchants to initiate payments without requiring consumer action each time. Learn more about recurring payments.

❗️

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.

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.

Updated 9 days ago