API Object: Payment Agreement

A Payment Agreement is a container object facilitating a model where you can easily initiate subsequent payment charges against a consumer account, without the need for consumer interaction. This is important for scenarios such as recurring payments, or any case where merchants want to initiate payments on their own schedule.

📘

(No need to make them re-enter their payment information, complete an additional authentication step, etc.)

How is a Payment Agreement Created?

You create payment agreements using our API POST /v1/payment-agreements, including a few key data points in the request payload, like the paymentMethod. Some payment methods require more data fields than others to construct a valid agreement, so refer to our docs for your specific payment method(s) for the full list.

Agreement States

Once you send this agreement creation request, the agreement will transition to one of the following states:

• ACTIVE: agreement is activated, meaning you can immediately create subsequent charges with it.
• AUTHENTICATION_PENDING: creating an agreement for recurring payments requires an extra consumer authentication step. You'll receive a list of standard authenticationMethods[] that can be used to authenticate the consumer.
• PROVIDER_CONFIRMATION_PENDING: waiting on payment method provider to approve the agreement before it becomes active.

Either way, once you receive a PAYMENT_AGREEMENT_ACTIVE webhook, you'll be able to make subsequent payment charges using the following API call: POST /v1/payment-agreements/{agreement-id}/payment-charges

Link-Only vs Link-And-Pay Agreements

When creating an agreement, you can include an initialPaymentCharge object. This will immediately create the first payment charge under that agreement during the agreement setup - a flow that we refer to as 'Link and Pay'.

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.

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.