Skip to main content

Agreements

Agreements enable merchants to perform subsequent transactions without requiring cardholder authentication for each transaction. This feature is particularly useful for:

  • Recurring payments
  • Subscriptions
  • Scenarios where the cardholder has consented to multiple charges

Types of Agreements​

There are four primary types of agreements:

  1. Unscheduled

    • Allows charging the cardholder at irregular intervals
    • Suitable for variable billing cycles or on-demand services

  2. Recurring

    • Enables charging the cardholder at regular intervals
    • Ideal for fixed subscription models or periodic billing

  3. Registered

    • Permits charging the cardholder without a specific schedule
    • Useful for storing payment information for future use

  4. Installment

    • Facilitates charging the cardholder in multiple installments
    • Perfect for large purchases split into smaller payments over time

Agreement Characteristics​

Agreements can be further categorized based on their transaction limits:

  • Fixed: Has a predetermined number of transactions
  • Variable: Has an unspecified number of transactions

Each agreement includes two key fields that control its usage:

  • max_use: Determines the maximum number of times the agreement can be used
  • expiry_date: Specifies the date when the agreement expires

Creating an Agreement​

To create an agreement, follow these steps:

  1. Prepare the new_agreement object with the following details:

    • Agreement type (Unscheduled, Recurring, Registered, or Installment)
    • Max use
    • Expiry date
    • Other relevant fields specific to your use case

  2. Include the new_agreement object in the order creation request

Example of a new_agreement object :

{
  "new_agreement": {
    "type": "unscheduled",
    "id": "string",
    "expiry": "2024-07-29",
    "max_use": 0,
    "variability": "variable"
  }
}

Using an Existing Agreement​

For subsequent transactions using an existing agreement:

  1. Retrieve the agreement_id from your records
  2. Include the agreement_id in the order creation request

Best Practices​

  • Implement a system to track agreement usage and expiration
  • Provide an easy way for cardholders to cancel or modify their agreements
  • Ensure compliance with relevant regulations and card network rules