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
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.
PayPal Payment Provider Contract UUID
Agreement description
Indicates whether to show the shipping address but prevent the customer from editing it.
Indicates whether to skip the collection of the shipping address from the customer during the agreement sign-up phase.
An array of legally accepted customer country codes
The ID of the experience profile to apply during the agreement approval UI flow.
The type of financial instrument (FI) that the merchant wants to promote.
The URL where the customer is redirected after the customer approves the payment
The URL where the customer is redirected after the customer cancels the payment
Successful
PayPal approval URL
Billing token
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
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.
The ID of the agreement token for which to show details.
PayPal Payment Provider Contract UUID
Successful
The state of the agreement.
The description of the agreement.
The description of the agreement.
Indicates whether to skip the collection of the shipping address from the customer during the agreement sign-up phase.
Indicates whether to show the shipping address but prevent the customer from editing it.
The ID of the experience profile to apply during the agreement approval UI flow.
The type of financial instrument (FI) that the merchant wants to promote.
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
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.
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.
PayPal agreement token
PayPal Payment Provider Contract UUID
Successful
The ID of the agreement.
The state of the agreement.
The description of the agreement.
The date and time when the agreement was created.
The date and time when the agreement was updated.
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
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.
PayPal billing agreement id
PayPal Payment Provider Contract UUID
Successful
The ID of the agreement.
The state of the agreement.
The description of the agreement.
The date and time when the agreement was created.
The date and time when the agreement was updated.
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
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.
PayPal billing agreement id
PayPal Payment Provider Contract UUID
Successful
Bad Request
Unauthorized
Forbidden
Not Found
Internal Server Error
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"
}textWas this helpful?