Billing Agreements

Billing Agreements enable recurring payments by creating a stored PayPal payment method on behalf of a payer. Once a billing agreement is in place, it can be referenced in future transactions without requiring the payer to authenticate each time.

The billing agreement lifecycle follows a two-step initiation flow: first generate a token, then convert it to a live agreement after the payer approves.

How It Works

1

Initiate the agreement

Call POST /billingAgreement/initiate with the PayPal contract details. You receive an approval token and a redirect URL.

2

Redirect the payer

Send the payer to the PayPal approval URL so they can consent to the recurring billing arrangement.

3

Create the agreement

After the payer approves, call POST /billingAgreement/create with the token to convert approval into a live billing agreement. Store the returned agreementId for future use.

Store the agreementId from the Create Billing Agreement response. This ID is required to reference the agreement in future transactions and to retrieve or cancel it later.

Initiate Billing Agreement

Initiates a new billing agreement by generating a PayPal approval token and redirect URL. The payer must visit the redirect URL to consent before the agreement can be created.

Initiate billing agreement

post

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingAgreement/initiate

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

*/*

paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

descriptionstringOptional

Agreement description

enableAddressChangebooleanOptional

Indicates whether to show the shipping address but prevent the customer from editing it.

collectShippingAddressbooleanOptional

Indicates whether to skip the collection of the shipping address from the customer during the agreement sign-up phase.

allowedCountriesstring[]Optional

An array of legally accepted customer country codes

experienceIdstringOptional

The ID of the experience profile to apply during the agreement approval UI flow.

externalSelectedFundingInstrumentTypestring · enumOptional

The type of financial instrument (FI) that the merchant wants to promote.

Possible values:

returnUrlstringOptional

The URL where the customer is redirected after the customer approves the payment

cancelUrlstringOptional

The URL where the customer is redirected after the customer cancels the payment

Responses

200

Successful

application/json

approvalUrlstringRequired

PayPal approval URL

billingTokenstringRequired

Billing token

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

/billingAgreement/initiate

HTTPcURLJavaScriptPython

POST /oidc/paypal-ecom/billingAgreement/initiate HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 392

{
  "paymentProviderContract": "text",
  "description": "text",
  "shippingAddress": {
    "country": "text",
    "postalCode": "text",
    "countrySubdivision": "text",
    "city": "text",
    "addressLine2": "text",
    "addressLine1": "text"
  },
  "enableAddressChange": true,
  "collectShippingAddress": true,
  "allowedCountries": [
    "text"
  ],
  "experienceId": "text",
  "externalSelectedFundingInstrumentType": "CREDIT",
  "returnUrl": "text",
  "cancelUrl": "text"
}

{
  "approvalUrl": "text",
  "billingToken": "text"
}

Show Token Details

Retrieves details about a billing agreement token before it is converted to a live agreement. Use this to inspect the token state or payer information after redirect.

Show token details

get

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingAgreement/token/{tokenId}

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

tokenIdstringRequired

The ID of the agreement token for which to show details.

Query parameters

paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses

200

Successful

application/json

tokenIdstringRequired

The state of the agreement.

statusstringOptional

The description of the agreement.

descriptionstringOptional

The description of the agreement.

collectShippingAddressbooleanOptional

Indicates whether to skip the collection of the shipping address from the customer during the agreement sign-up phase.

enableAddressChangebooleanOptional

Indicates whether to show the shipping address but prevent the customer from editing it.

experienceIdstringOptional

The ID of the experience profile to apply during the agreement approval UI flow.

externalSelectedFundingInstrumentTypestring · enumOptional

The type of financial instrument (FI) that the merchant wants to promote.

Possible values:

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/billingAgreement/token/{tokenId}

HTTPcURLJavaScriptPython

GET /oidc/paypal-ecom/billingAgreement/token/{tokenId}?paymentProviderContract=text HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "tokenId": "text",
  "status": "text",
  "description": "text",
  "collectShippingAddress": true,
  "enableAddressChange": true,
  "payerInfo": {
    "email": "text",
    "suffix": "text",
    "firstName": "text",
    "lastName": "text",
    "payerId": "text",
    "phone": "text",
    "billingAddress": {
      "country": "text",
      "postalCode": "text",
      "countrySubdivision": "text",
      "city": "text",
      "addressLine2": "text",
      "addressLine1": "text"
    }
  },
  "redirectUrls": {
    "returnUrl": "text",
    "cancelUrl": "text"
  },
  "experienceId": "text",
  "externalSelectedFundingInstrumentType": "CREDIT"
}

Create Billing Agreement

Converts an approved billing agreement token into a live PayPal billing agreement. Call this after the payer has completed the PayPal approval flow.

Use x-vfi-api-idempotencyKey to prevent duplicate agreement creation on network retries.

Create billing agreement using token

post

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingAgreement/create

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

x-vfi-api-idempotencyKeystringOptional

A value you specify that uniquely identifies the transaction. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the transaction.

Body

*/*

billingTokenstringRequired

PayPal agreement token

paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses

200

Successful

application/json

idstringRequired

The ID of the agreement.

statestringRequired

The state of the agreement.

descriptionstringOptional

The description of the agreement.

createTimestringRequired

The date and time when the agreement was created.

updateTimestringOptional

The date and time when the agreement was updated.

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

/billingAgreement/create

HTTPcURLJavaScriptPython

POST /oidc/paypal-ecom/billingAgreement/create HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 56

{
  "billingToken": "text",
  "paymentProviderContract": "text"
}

{
  "id": "text",
  "state": "text",
  "description": "text",
  "merchant": {
    "payeeInfo": {
      "email": "text"
    }
  },
  "payer": {
    "payerInfo": {
      "email": "text",
      "suffix": "text",
      "firstName": "text",
      "lastName": "text",
      "payerId": "text",
      "phone": "text",
      "billingAddress": {
        "country": "text",
        "postalCode": "text",
        "countrySubdivision": "text",
        "city": "text",
        "addressLine2": "text",
        "addressLine1": "text"
      }
    }
  },
  "plan": {
    "merchantPreferences": {
      "collectShippingAddress": "text",
      "enableAddressChange": "text",
      "experienceId": "text",
      "externalSelectedFundingInstrumentType": "text",
      "allowedCountries": [
        "text"
      ]
    }
  },
  "createTime": "text",
  "updateTime": "text"
}

Get Agreement Details

Retrieves the full details of an existing billing agreement, including status, payer information, and shipping details.

Get agreement details

get

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingAgreement/{agreementId}

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

agreementIdstringRequired

PayPal billing agreement id

Query parameters

paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses

200

Successful

application/json

idstringRequired

The ID of the agreement.

statestringRequired

The state of the agreement.

descriptionstringOptional

The description of the agreement.

createTimestringRequired

The date and time when the agreement was created.

updateTimestringOptional

The date and time when the agreement was updated.

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

/billingAgreement/{agreementId}

HTTPcURLJavaScriptPython

GET /oidc/paypal-ecom/billingAgreement/{agreementId}?paymentProviderContract=text HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "state": "text",
  "description": "text",
  "merchant": {
    "payeeInfo": {
      "email": "text"
    }
  },
  "payer": {
    "payerInfo": {
      "email": "text",
      "suffix": "text",
      "firstName": "text",
      "lastName": "text",
      "payerId": "text",
      "phone": "text",
      "billingAddress": {
        "country": "text",
        "postalCode": "text",
        "countrySubdivision": "text",
        "city": "text",
        "addressLine2": "text",
        "addressLine1": "text"
      }
    }
  },
  "shippingAddress": {
    "fullName": "text",
    "addressLine1": "text",
    "addressLine2": "text",
    "city": "text",
    "countrySubdivision": "text",
    "country": "text",
    "postalCode": "text"
  },
  "plan": {
    "merchantPreferences": {
      "collectShippingAddress": "text",
      "enableAddressChange": "text",
      "experienceId": "text",
      "externalSelectedFundingInstrumentType": "text",
      "allowedCountries": [
        "text"
      ]
    }
  },
  "createTime": "text",
  "updateTime": "text"
}

Cancel Billing Agreement

Cancels an active billing agreement. Once cancelled, the agreement can no longer be used to process payments.

Cancellation is irreversible. If a billing agreement is cancelled, a new one must be initiated and approved by the payer to resume recurring payments.

Cancel agreement details

post

https://emea.gsc.verifone.cloud/oidc/paypal-ecomhttps://us.gsc.verifone.cloud/oidc/paypal-ecomhttps://nz.gsc.verifone.cloud/oidc/paypal-ecomhttps://cst.test-gsc.vfims.com/oidc/paypal-ecomhttps://uscst.gb.gsc.cficloud/oidc/paypal-ecom

/billingAgreement/{agreementId}/cancel

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

agreementIdstringRequired

PayPal billing agreement id

Body

*/*

paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses

200

Successful

application/json

stringOptional

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

/billingAgreement/{agreementId}/cancel

HTTPcURLJavaScriptPython

POST /oidc/paypal-ecom/billingAgreement/{agreementId}/cancel HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 34

{
  "paymentProviderContract": "text"
}

text