Create a Payment Agreement

Merchant-Idstring required

The merchant identifier.

Request body

paymentMethodstring required

The payment method which should be used to process the payment charge.

paymentMedium'ECOMMERCE' | 'MOTO' | 'POS'

The payment medium.

descriptionstring

The description of the agreement

merchantPaymentAgreementReferencestring

The merchant payment agreement reference.

startDatestring date-time

The start date of the agreement

endDatestring date-time

The end date of the agreement

amountType'MAX' | 'EXACT' | 'VARIABLE'

Defines if the provided 'amount' is a maximum value or an exact value.

instrumentIdstring

The identifier of an existing payment instrument. Instruments are used for account on file payments.

paymentSessionIdstring

The identifier of the associated payment-session. Payment-sessions are created by the drop-in UI.

webhooksUrlstring

The URL to which the agreement state changes will be notified

initialSchemeAuthorizationReferencestring

The initial scheme authorization reference, eg. for cards network transaction identifier (NTI)

initialTransactionLinkReferencestring

Transaction Link Reference or Id (ex: Mastercard TLID) is a unique identifier for a transaction, used by some card networks for transaction chain linking, this is in addition to Network Transaction Identifiers. Provide the initial TLID when creating the subsequent Merchant-Initiated-Transactions.

labelsobject

Custom labels associated with the payment agreement.

Example request

{
  "paymentMethod": "UPI_AUTOPAY",
  "paymentMedium": "ECOMMERCE",
  "merchantPaymentAgreementReference": "5c019979-0751-469e-96e0-b67f1d95c577",
  "frequency": {
    "type": "MONTHLY",
    "interval": 3
  },
  "startDate": "2023-03-26T20:24:27+00:00",
  "endDate": "2023-11-27T09:30:00+00:00",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "instrumentId": "instr_SNaRMvhYNFpXhEhgTVSed",
  "instrument": {
    "details": {
      "accountNumber": "007123456",
      "holderName": "John Doe",
      "iban": "DE75512108001245126199",
      "swiftCode": "DEUTDEFF123",
      "bankName": "My Bank",
      "bankCode": "12341234"
    }
  },
  "paymentSessionId": "sess_hb8BQ2kbhpHRmE29T6ajx",
  "consumer": {
    "name": "John Smith",
    "email": "johnsmith@example.com",
    "phone": "+491521111111",
    "country": "DE",
    "locale": "de-DE",
    "taxIdentification": "0798154336790",
    "merchantConsumerReference": "5c019979-0751-469e-96e0-b67f1d95c577",
    "billingAddress": {
      "street": "123 Main St",
      "city": "Anytown",
      "region": "CA",
      "postalCode": "12345",
      "country": "US"
    },
    "client": {
      "ip": "11.22.22.33",
      "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 8172.45.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.64 Safari/537.36"
    }
  },
  "initialPaymentCharge": {
    "paymentDescriptor": "PPRO - ORDER 1234",
    "amount": {
      "value": 1000,
      "currency": "EUR"
    },
    "order": {
      "orderItems": [
        {
          "sku": "LS123456789",
          "category": "bicycle",
          "name": "White T-Shirt",
          "quantity": 1,
          "amount": 1000
        }
      ],
      "shippingAddress": {
        "street": "123 Main St",
        "city": "Anytown",
        "region": "CA",
        "postalCode": "12345",
        "country": "US"
      },
      "industryData": [
        {
          "details": {
            "pnr": "SKJ2NS01AS",
            "numberOfPassengers": 1,
            "airlineCode": "016",
            "passengerEmail": "john@gmail.com",
            "passengerPhone": "14082319231",
            "passengerName": "John Doe",
            "carrierCode": "016",
            "tripSegments": [
              {
                "fareBasisCode": "YE3MGB",
                "departureAirportCode": "MAN",
                "destinationAirportCode": "SYD",
                "flightNumber": "BA98",
                "departureDate": "2025-01-01",
                "flightCarrierCode": "016",
                "segmentId": "1"
              }
            ]
          }
        }
      ]
    },
    "merchantPaymentChargeReference": "5c019979-0751-469e-96e0-b67f1d95c577",
    "authenticationSettings": [
      {
        "settings": {
          "returnUrl": "https://www.webshop.com/order-results-page"
        }
      }
    ],
    "consumer": {
      "taxIdentification": "798154336790",
      "client": {
        "ip": "11.22.22.33",
        "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 8172.45.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.64 Safari/537.36"
      }
    }
  },
  "authenticationSettings": [
    {
      "settings": {
        "returnUrl": "https://www.webshop.com/order-results-page"
      }
    }
  ],
  "initialSchemeAuthorizationReference": "XPTO",
  "initialTransactionLinkReference": "atf3_8msFoZ6klReRDlQwn"
}

Response

OK

idstring

The payment agreement ID

The payment agreement status

descriptionstring

The description of the agreement

merchantPaymentAgreementReferencestring

The merchant payment agreement reference

paymentMethodstring

The payment method which was used to process the payment charge.

startDatestring date-time

The start date of the agreement

endDatestring date-time

The end date of the agreement

instrumentIdstring

The ID of the payment instrument associated with the agreement.

instrumentUpdatedboolean

Indicates that the Payment Instrument has been updated during processing. Query Payment Instruments to retrieve the new details.

amountType'MAX' | 'EXACT' | 'VARIABLE'

Defines if the provided 'amount' is a maximum value or an exact value.

initialPaymentChargeIdstring

The payment charge ID of the initial charge generated by this agreement

initialSchemeAuthorizationReferencestring

The initial scheme authorization reference, eg. for cards network transaction identifier (NTI)

initialTransactionLinkReferencestring

Transaction Link Reference or Id (ex: Mastercard TLID) is a unique identifier for a transaction, used by some card networks for transaction chain linking, this is in addition to Network Transaction Identifiers. Provide the initial TLID when creating the subsequent Merchant-Initiated-Transactions.

createdAtstring date-time

The agreement creation timestamp in ISO 8601 format.

updatedAtstring date-time

The agreement update timestamp in ISO 8601 format.

labelsobject

Custom labels associated with this payment agreement.

Example response

{
  "id": "agr_pmCQxjxTj35kx6KaSgOJh",
  "status": "ACTIVE",
  "paymentMethod": "UPI_AUTOPAY",
  "frequency": {
    "type": "MONTHLY",
    "interval": 3
  },
  "startDate": "2023-03-26T20:24:27.123Z",
  "endDate": "2023-03-26T20:24:27.123Z",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "consumer": {
    "name": "John Smith",
    "email": "johnsmith@example.com",
    "phone": "+491521111111",
    "country": "DE",
    "locale": "de-DE",
    "taxIdentification": "0798154336790",
    "merchantConsumerReference": "5c019979-0751-469e-96e0-b67f1d95c577",
    "billingAddress": {
      "street": "123 Main St",
      "city": "Anytown",
      "region": "CA",
      "postalCode": "12345",
      "country": "US"
    },
    "client": {
      "ip": "11.22.22.33",
      "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 8172.45.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.64 Safari/537.36"
    }
  },
  "authenticationMethods": [
    {
      "details": {
        "mobileIntentUri": "upiGlobal://pay?tr=123&from_app=true"
      }
    }
  ],
  "history": [
    {
      "id": "ahist_ufJuwjMY21NVK4dkjee3",
      "status": "SUCCEDED",
      "createdAt": "2023-03-26T20:24:27.123Z"
    }
  ],
  "revocations": [
    {
      "id": "rev_ufJuwjMY21NVK4dkjee3",
      "revocationStatus": "REVOKED_BY_MERCHANT",
      "createdAt": "2023-03-26T20:24:27.123Z"
    }
  ],
  "initialSchemeAuthorizationReference": "XPTO",
  "initialTransactionLinkReference": "atf3_8msFoZ6klReRDlQwn",
  "createdAt": "2023-03-26T20:24:27.123Z",
  "updatedAt": "2023-03-26T20:24:27.123Z"
}

v1

Create a Payment Agreement

Headers

Request body

Example request

Response

Example response