Ctrlk
RegisterLogin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Subscriptions

Subscriptions represent a subscriber's enrolment in a Billing Plan. They manage the recurring billing lifecycle from creation through active billing, suspension, revision, and cancellation.

A subscription requires an active billing plan. Ensure the plan is created and activated before creating subscriptions. See Billing Plans.

Create Subscription

Enrols a subscriber in a billing plan. Returns a subscription ID used in all subsequent lifecycle operations.

Use x-vfi-api-idempotencyKey to prevent duplicate subscriptions from being created on network retries.

Create subscription

post
/subscriptions
Authorizations
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
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

planIdstring · min: 3 · max: 50Required

The ID of the plan

startTimestring · dateOptional

The date and time when the subscription started

quantityintegerOptional

The quantity of the product in the subscription

customIdstring · min: 1 · max: 127Optional

The custom id for the subscription. Can be invoice id

Pattern: ^[ -~]+
Responses
201

Created

application/json
idstringRequired

The PayPal-generated ID for the subscription.

statusstringRequired

The status of the subscription.

planIdstring · min: 3 · max: 50Required

The ID of the plan

statusUpdateTimestring · dateRequired

Status update time.

planOverriddenbooleanRequired

Indicates whether the subscription has overridden any plan attributes.

quantitystringOptional

The quantity of the product in the subscription.

startTimestring · dateOptional

The quantity of the product in the subscription.

createdAtstring · dateOptional

The quantity of the product in the subscription.

approvalUrlstringRequired

PayPal approval URL

post/subscriptions
POST /oidc/paypal-ecom/subscriptions HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 737

{
  "paymentProviderContract": "text",
  "planId": "text",
  "startTime": "2026-01-01",
  "quantity": 1,
  "shippingAmount": {
    "value": 100,
    "currencyCode": "EUR"
  },
  "subscriber": {
    "name": {
      "givenName": "text",
      "surname": "text"
    },
    "payerId": "text",
    "emailAddress": "text",
    "phone": {
      "phoneType": "FAX",
      "phoneNumber": {
        "nationalNumber": "text"
      }
    },
    "shippingAddress": {
      "name": {
        "fullName": "text"
      },
      "address": {
        "country": "text",
        "postalCode": "text",
        "countrySubdivision": "text",
        "city": "text",
        "addressLine2": "text",
        "addressLine1": "text"
      }
    }
  },
  "customId": "text",
  "applicationContext": {
    "brandName": "text",
    "locale": "text",
    "shippingPreference": "GET_FROM_FILE",
    "userAction": "CONTINUE",
    "paymentMethod": {
      "payerSelected": "text",
      "payeePreferred": "UNRESTRICTED"
    },
    "returnUrl": "text",
    "cancelUrl": "text"
  }
}
{
  "id": "text",
  "status": "text",
  "planId": "text",
  "statusUpdateTime": "2026-01-01",
  "planOverridden": true,
  "quantity": "text",
  "startTime": "2026-01-01",
  "shippingAmount": {
    "value": 100,
    "currencyCode": "EUR"
  },
  "subscriber": {
    "name": {
      "givenName": "text",
      "surname": "text"
    },
    "payerId": "text",
    "emailAddress": "text",
    "phone": {
      "phoneType": "FAX",
      "phoneNumber": {
        "nationalNumber": "text"
      }
    },
    "shippingAddress": {
      "name": {
        "fullName": "text"
      },
      "address": {
        "country": "text",
        "postalCode": "text",
        "countrySubdivision": "text",
        "city": "text",
        "addressLine2": "text",
        "addressLine1": "text"
      }
    }
  },
  "applicationContext": {
    "brandName": "text",
    "locale": "text",
    "shippingPreference": "GET_FROM_FILE",
    "userAction": "CONTINUE",
    "paymentMethod": {
      "payerSelected": "text",
      "payeePreferred": "UNRESTRICTED"
    },
    "returnUrl": "text",
    "cancelUrl": "text"
  },
  "createdAt": "2026-01-01",
  "approvalUrl": "text"
}

Subscription Details

Retrieves the current details and status of a subscription, including billing info, subscriber details, and outstanding balance.

Subscription Details

get
/subscriptions/{id}
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Query parameters
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses
200

Successful

application/json
idstringOptional

ID of the subscription

statusstring · enumOptional

The status of the subscription

Possible values:
planIdstring · min: 3 · max: 50Required

The ID of the plan

planOverriddenbooleanOptional

Indicates whether the subscription has overridden any plan attributes

statusUpdateTimestring · dateOptional

The date and time when the subscription status updated last time

statusChangeNotestringOptional

The reason or notes for the status of the subscription

startTimestring · dateOptional

The date and time when the subscription started

quantityintegerOptional

The quantity of the product in the subscription

customIdstring · min: 1 · max: 127Optional

The custom id for the subscription. Can be invoice id

Pattern: ^[ -~]+
createdAtstring · dateOptional

The date and time when the subscription created

updatedAtstring · dateOptional

The date and time when the subscription updated last time

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

{
  "id": "text",
  "status": "APPROVAL_PENDING",
  "planId": "text",
  "planOverridden": true,
  "statusUpdateTime": "2026-01-01",
  "statusChangeNote": "text",
  "startTime": "2026-01-01",
  "quantity": 1,
  "customId": "text",
  "shippingAmount": {
    "value": 100,
    "currencyCode": "EUR"
  },
  "subscriber": {
    "name": {
      "givenName": "text",
      "surname": "text"
    },
    "payerId": "text",
    "emailAddress": "text",
    "phone": {
      "phoneType": "FAX",
      "phoneNumber": {
        "nationalNumber": "text"
      }
    },
    "shippingAddress": {
      "name": {
        "fullName": "text"
      },
      "address": {
        "country": "text",
        "postalCode": "text",
        "countrySubdivision": "text",
        "city": "text",
        "addressLine2": "text",
        "addressLine1": "text"
      }
    }
  },
  "billingInfo": {
    "outstandingBalance": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "cycleExecutions": [
      {
        "tenureType": "REGULAR",
        "sequence": 1,
        "cyclesCompleted": 1,
        "cyclesRemaining": 1,
        "currentPricingSchemeVersion": 1,
        "totalCycles": 1
      }
    ],
    "lastPayment": {
      "status": "text",
      "amount": {
        "value": 100,
        "currencyCode": "EUR"
      },
      "time": "2026-01-01"
    },
    "nextBillingTime": "text",
    "finalPaymentTime": "text",
    "failedPaymentsCount": 1,
    "lastFailedPayment": {
      "amount": {
        "value": 100,
        "currencyCode": "EUR"
      },
      "time": "2026-01-01",
      "reasonCode": "CURRENCY_MISMATCH",
      "nextPaymentRetryTime": "2026-01-01"
    }
  },
  "createdAt": "2026-01-01",
  "updatedAt": "2026-01-01"
}

Update Subscription

Updates mutable fields on an active subscription, such as billing cycle pricing, subscriber shipping address, outstanding balance, or taxes. Returns 204 No Content on success.

Update subscription

patch
/subscriptions/{id}
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Body
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses
204

No Content

patch/subscriptions/{id}
PATCH /oidc/paypal-ecom/subscriptions/{id} HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 1014

{
  "paymentProviderContract": "text",
  "startTime": {
    "op": "replace",
    "value": "2026-01-01"
  },
  "customId": {
    "op": "add",
    "value": "text"
  },
  "planPaymentPreferencesAutoBillOutstanding": {
    "op": "replace",
    "value": true
  },
  "planBillingCyclesPricingSchemeFixedPrice": {
    "op": "add",
    "value": {
      "value": 100,
      "currencyCode": "EUR"
    },
    "sequence": 1
  },
  "planBillingCyclesTotalCycles": {
    "op": "replace",
    "value": 1,
    "sequence": 1
  },
  "planBillingCyclesPricingSchemeTiers": {
    "op": "replace",
    "value": [
      {
        "startingQuantity": 1,
        "endingQuantity": 1,
        "amount": {
          "value": 100,
          "currencyCode": "EUR"
        }
      }
    ],
    "sequence": 1
  },
  "planTaxesPercentage": {
    "op": "add",
    "value": 1
  },
  "planTaxesInclusive": {
    "op": "add",
    "value": true
  },
  "subscriberShippingAddress": {
    "op": "add",
    "value": {
      "name": {
        "fullName": "text"
      },
      "address": {
        "country": "text",
        "postalCode": "text",
        "countrySubdivision": "text",
        "city": "text",
        "addressLine2": "text",
        "addressLine1": "text"
      }
    }
  },
  "billingInfoOutstandingBalance": {
    "op": "replace",
    "value": {
      "value": 100,
      "currencyCode": "EUR"
    }
  },
  "shippingAmount": {
    "op": "add",
    "value": {
      "value": 100,
      "currencyCode": "EUR"
    }
  }
}
No content

Revise Subscription

Revises a subscription to move the subscriber to a different plan or change plan-level configuration. Returns a redirect URL for the subscriber to confirm the revision if required.

Revise subscription

post
/subscriptions/{id}/revise
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Body
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

planIdstring · min: 3 · max: 50Optional

The ID of the plan

effectiveTimestring · dateOptional

The date and time when this change is effective

quantityintegerOptional

The quantity of the product or service in the subscription

Responses
200

Successful

application/json
stringOptional
post/subscriptions/{id}/revise
POST /oidc/paypal-ecom/subscriptions/{id}/revise HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 556

{
  "paymentProviderContract": "text",
  "planId": "text",
  "effectiveTime": "2026-01-01",
  "quantity": 1,
  "shippingAmount": {
    "value": 100,
    "currencyCode": "EUR"
  },
  "shippingAddress": {
    "name": {
      "fullName": "text"
    },
    "address": {
      "country": "text",
      "postalCode": "text",
      "countrySubdivision": "text",
      "city": "text",
      "addressLine2": "text",
      "addressLine1": "text"
    }
  },
  "applicationContext": {
    "brandName": "text",
    "locale": "text",
    "shippingPreference": "GET_FROM_FILE",
    "userAction": "CONTINUE",
    "paymentMethod": {
      "payerSelected": "text",
      "payeePreferred": "UNRESTRICTED"
    },
    "returnUrl": "text",
    "cancelUrl": "text"
  }
}
text

Capture Authorized Payment

Captures an outstanding authorised payment on a subscription. Returns 202 Accepted — the capture is processed asynchronously.

Use x-vfi-api-idempotencyKey to prevent duplicate captures. The 202 Accepted response means the request was queued, not that capture is complete.

Capture authorized payment on subscription

post
/subscriptions/{id}/capture
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
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
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

reasonstringRequired

The reason or note for the subscription charge.

Responses
202

Accepted

post/subscriptions/{id}/capture
POST /oidc/paypal-ecom/subscriptions/{id}/capture HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 94

{
  "paymentProviderContract": "text",
  "reason": "text",
  "amount": {
    "currencyCode": "EUR",
    "value": 100
  }
}
202

Accepted

No content

Activate Subscription

Reactivates a suspended subscription, resuming the billing cycle.

Activate subscription

post
/subscriptions/{id}/activate
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Body
reasonstringOptional

The reason for activation of a subscription

paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

Responses
204

No Content

post/subscriptions/{id}/activate
POST /oidc/paypal-ecom/subscriptions/{id}/activate HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 50

{
  "reason": "text",
  "paymentProviderContract": "text"
}
No content

Suspend Subscription

Pauses a subscription temporarily. The subscription enters a suspended state and billing stops until it is reactivated.

Suspend subscription

post
/subscriptions/{id}/suspend
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Body
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

reasonstringOptional

The reason for suspenson of the subscription.

Responses
204

No Content

post/subscriptions/{id}/suspend
POST /oidc/paypal-ecom/subscriptions/{id}/suspend HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 50

{
  "paymentProviderContract": "text",
  "reason": "text"
}
No content

Cancel Subscription

Permanently cancels a subscription. The subscriber will no longer be billed.

Cancellation is irreversible. A cancelled subscription cannot be reactivated. A new subscription must be created if the subscriber wishes to re-enrol.

Cancel subscription

post
/subscriptions/{id}/cancel
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
idstringRequired
Body
paymentProviderContractstringRequired

PayPal Payment Provider Contract UUID

reasonstringOptional

The reason for the cancellation of a subscription.

Responses
204

No Content

post/subscriptions/{id}/cancel
POST /oidc/paypal-ecom/subscriptions/{id}/cancel HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: */*
Accept: */*
Content-Length: 94

{
  "paymentProviderContract": "text",
  "reason": "text",
  "amount": {
    "value": 100,
    "currencyCode": "EUR"
  }
}
No content

Subscription Lifecycle States

ACTIVE

The subscription is in good standing and billing is proceeding normally. This is the expected state after creation or reactivation.

SUSPENDED

Billing has been paused. Use POST /subscriptions/{id}/activate to resume.

CANCELLED

The subscription has been permanently terminated. No further billing will occur. A new subscription must be created to re-enrol the subscriber.

PreviousBilling Plans
NextRisk Context

Last updated

Was this helpful?