Setting Recurring Payments

See Authentication | Xplor Pay Documentation before calling the recurring payments service APIs to set recurring payments for customers.

The following steps explain how to set recurring payments:

1

Creating a customer

1. Add the following fields to the request body when calling the recurring payments services API endpoint.

{
    "first-name": "Clark",
    "last-name": "Kent",
    "email": "[email protected]",
    "billing-address": {
        "street": "1938 DeSota Rd",
        "city": "Smallville",
        "state": "Kansas",
        "zip": "12345",
        "phone": "5555555555"
    }
}

The following table describes the fields from the request body:

Name	Data type	Required?	Description
first-name	String	Required	The customer's first name.
last-name	String	Required	The customer's last name.
email	String	Required	The customer's email address.
billing-address	Object	Required	The customer's billing address details.
billing-address.street	String	Required	The street address of the customer.
billing-address.city	String	Required	The city of the customer's billing address.
billing-address.state	String	Required	The state or region of the customer's billing address.
billing-address.zip	String	Required	The ZIP or postal code of the customer's billing address.
billing-address.phone	String	Required	The customer's phone number.

1. Use POST method to call the rest/v2/customers endpoint.

The API returns the following response:

{
    "code": "201",
    "status": "success",
    "exchange-id": "ID-clearent-rps-1-34dd8e73-7540-4efc-b22c-70e3e53d07ba",
    "links": [
        {
            "rel": "self",
            "href": "https://gateway-sb.clearent.net/rest/v2/customers/cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e"
        }
    ],
    "payload": {
        "customer": {
            "email": "[email protected]",
            "customer-key": "cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e",
            "first-name": "Clark",
            "last-name": "Kent",
            "billing-address": {
                "street": "1938 DeSota Rd",
                "city": "Smallville",
                "state": "Kansas",
                "zip": "12345",
                "phone": "5555555555"
            },
            "links": {
                "link": [
                    {
                        "rel": "self",
                        "href": "https://gateway-sb.clearent.net/rest/v2/customers/cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e"
                    },
                    {
                        "rel": "payment-plans",
                        "href": "https://gateway-sb.clearent.net/rest/v2/payment-plans?customer-key=cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e"
                    }
                ]
            }
        },
        "payloadType": "customer"
    }
}

The API response includes the following fields:

Name	Data type	Description
code	String	The HTTP status code returned by the API.
status	String	Indicates the result of the request.
exchange-id	String	A unique identifier for tracking the API request.
links	Array	Contains link objects related to the created customer resource.
links[].rel	String	The relationship of the created customer. For examples self.
links[].href	String (URI)	The URI to access the created customer.
payload.payloadType	String	Indicates the type of payload returned. For examples, customer.
payload.customer.email	String	The customer's email address.
payload.customer.customer-key	String	A unique identifier for the customer. Use this key to manage tokens and payment plans for the customer. For example, cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e.
payload.customer.first-name	String	The customer's first name.
payload.customer.last-name	String	The customer's last name.
payload.customer.billing-address.street	String	The street address of the customer.
payload.customer.billing-address.city	String	The city of the customer's billing address.
payload.customer.billing-address.state	String	The state or region of the customer's billing address.
payload.customer.billing-address.zip	String	The ZIP or postal code of the customer's billing address.
payload.customer.billing-address.phone	String	The customer's phone number.
payload.customer.links.link[].rel	String	The relationship of the linked resource. For examples, self, payment-plans.
payload.customer.links.link[].href	String (URI)	The URI to access the created customer.

2

Get a token for a customer

1. Add the customer key to the customer key field in the request body when calling the recurring payments services API endpoint.

The customer key field in the request body is required to get a token for customer. For example, cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e

{
    "avs-address": "123 example street",
    "avs-zip": "123445",
    "card-type": "VISA",
    "customer-key": "cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e",
    "default": true,
    "description": "Big Money Card",
    "exp-date": "0932",
    "last-four-digits": "5678",
    "token-id": "1100001322954675439"
}

1. Use the GET method to call the rest/v2/customers/{customerKey}/tokens endpoint.

The API returns the following response:

{
    "code": "201",
    "status": "SUCCESS",
    "exchange-id": "ID-clearent-rps-1-264d0e54-ea7e-4416-846b-65e84d5db042",
    "links": [
        {
            "rel": "self",
            "href": "https://gateway-sb.clearent.net/rest/v2/payment-plans/plan_62f36450-1918-41ff-a019-4ed8155fad69"
        }
    ],
    "payload": {
        "payment-plan": {
            "frequency": "MONTHLY",
            "plan-key": "plan_62f36450-1918-41ff-a019-4ed8155fad69",
            "customer-key": "cust_27d8fd09-d092-4809-869f-337eb64839b5",
            "customer-name": "Light Yagami",
            "email-address": "[email protected]",
            "email-receipt": "false",
            "token-id": "1100001322954675439",
            "frequency-day": "3",
            "payment-amount": "13.37",
            "start-date": "2025-08-10",
            "end-date": "2025-12-31",
            "status": "ACTIVE",
            "status-date": "2025-06-04",
            "frequency-month": "5",
            "frequency-week": "1",
            "links": {
                "link": [
                    {
                        "rel": "self",
                        "href": "https://gateway-sb.clearent.net/rest/v2/payment-plans/plan_62f36450-1918-41ff-a019-4ed8155fad69"
                    },
                    {
                        "rel": "customers",
                        "href": "https://gateway-sb.clearent.net/rest/v2/customers/cust_27d8fd09-d092-4809-869f-337eb64839b5"
                    },
                    {
                        "rel": "tokens",
                        "href": "https://gateway-sb.clearent.net/rest/v2/tokens/1100001322954675439"
                    }
                ]
            }
        },
        "payloadType": "payment-plan"
    }
}

The API response includes the following fields:

Name	Data type	Description
code	String	The HTTP status code returned by the API.
status	String	Indicates the result of the request.
exchange-id	String	A unique identifier for tracking the API request.
links	Array	Contains link objects related to the created customer resource.
links[].rel	String	The relationship of the created customer. For examples self.
links[].href	String (URI)	The URI to access the created customer.
payload.payloadType	String	Indicates the type of payload returned. For examples, customer.
payment-plan.frequency	String	The frequency of the payment plan. For example, MONTHLY.
payment-plan.plan-key	String	A unique identifier for the payment plan.
payment-plan.customer-key	String	A unique identifier for the customer.
payment-plan.customer-name	String	The full name of the customer.
payment-plan.email-address	String	The customer's email address.
payment-plan.email-receipt	String	Indicates whether email receipts are enabled. For example, true or false.
payment-plan.token-id	String	The token ID associated with the payment plan.
payment-plan.frequency-day	String	The day of the month the payment is scheduled.
payment-plan.payment-amount	String	The amount to be charged for each payment.
payment-plan.start-date	String (Date)	The start date of the payment plan.
payment-plan.end-date	String (Date)	The end date of the payment plan.
payment-plan.status	String	The current status of the payment plan. For example, ACTIVE.
payment-plan.status-date	String (Date)	The date when the current status was set.
payment-plan.frequency-month	String	The number of months between payments (if applicable).
payment-plan.frequency-week	String	The number of weeks between payments (if applicable).
payment-plan.links.link[].rel	String	The relationship of the linked resource. For examples, self, customers, tokens.
payment-plan.links.link[].href	String (URI)	The URI to access the linked resource.

3

Create a payment plan

1. Add the following fields in the request body when calling the recurring payments services API endpoint.

{
    "customer-key": "cust_27d8fd09-d092-4809-869f-337eb64839b5",
    "customer-name": "Token Test",
    "email-address": "[email protected]",
    "email-receipt": "false",
    "start-date": "2025-08-10",
    "end-date": "2025-12-31",
    "frequency": "MONTHLY",
    "frequency-day": "3",
    "frequency-month": "5",
    "payment-amount": "13.37",
    "token-id": "1100001322954675439"
}

The following table describes the fields from the request body:

Name	Data type	Required?	Description
customer-key	String	Required	A unique identifier for the customer associated with the payment plan. For example: cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e.
customer-name	String	Required	The full name of the customer.
email-address	String	Required	The customer's email address.
email-receipt	String	Required	Specifies whether to send an email receipt to the customer. Set to true to send an email receipt. Set to false to skip sending an email receipt.
start-date	String (Date)	Required	The start date of the payment plan in YYYY-MM-DD format.
end-date	String (Date)	Required	The end date of the payment plan in YYYY-MM-DD format.
frequency	String	Required	The frequency of the payment. Use WEEKLY, MONTHLY, or YEARLY.
frequency-day	String	Required	The day of the month the payment is scheduled.
frequency-month	String	Required	The number of months between payments (used for custom frequencies).
payment-amount	String	Required	The amount to be charged for each payment.
token-id	String	Required	The token ID used to process the payment.

1. Use the POST method to call the rest/v2/payment-plans endpoint.

The API returns the following response:

{
    "code": "201",
    "status": "SUCCESS",
    "exchange-id": "ID-clearent-rps-1-264d0e54-ea7e-4416-846b-65e84d5db042",
    "links": [
        {
            "rel": "self",
            "href": "https://gateway-sb.clearent.net/rest/v2/payment-plans/plan_62f36450-1918-41ff-a019-4ed8155fad69"
        }
    ],
    "payload": {
        "payment-plan": {
            "frequency": "MONTHLY",
            "plan-key": "plan_62f36450-1918-41ff-a019-4ed8155fad69",
            "customer-key": "cust_27d8fd09-d092-4809-869f-337eb64839b5",
            "customer-name": "Light Yagami",
            "email-address": "[email protected]",
            "email-receipt": "false",
            "token-id": "1100001322954675439",
            "frequency-day": "3",
            "payment-amount": "13.37",
            "start-date": "2025-08-10",
            "end-date": "2025-12-31",
            "status": "ACTIVE",
            "status-date": "2025-06-04",
            "frequency-month": "5",
            "frequency-week": "1",
            "links": {
                "link": [
                    {
                        "rel": "self",
                        "href": "https://gateway-sb.clearent.net/rest/v2/payment-plans/plan_62f36450-1918-41ff-a019-4ed8155fad69"
                    },
                    {
                        "rel": "customers",
                        "href": "https://gateway-sb.clearent.net/rest/v2/customers/cust_27d8fd09-d092-4809-869f-337eb64839b5"
                    },
                    {
                        "rel": "tokens",
                        "href": "https://gateway-sb.clearent.net/rest/v2/tokens/1100001322954675439"
                    }
                ]
            }
        },
        "payloadType": "payment-plan"
    }
}

The API response includes the following fields:

Name	Data type	Description
code	String	The HTTP status code returned by the API.
status	String	Indicates the result of the request.
exchange-id	String	A unique identifier for tracking the API request.
links	Array	Contains link objects related to the created payment plan.
links[].rel	String	Describes the relationship of the linked resource. For example, self.
links[].href	String (URI)	The URI to access the linked resource.
payload.payloadType	String	Indicates the type of payload returned. For example, payment-plan.
payment-plan.frequency	String	The frequency of the payment plan. For example, MONTHLY.
payment-plan.plan-key	String	A unique identifier for the payment plan.
payment-plan.customer-key	String	A unique identifier for the customer.
payment-plan.customer-name	String	The full name of the customer.
payment-plan.email-address	String	The customer's email address.
payment-plan.email-receipt	String	Indicates whether email receipts are enabled. For examples, true or false.
payment-plan.token-id	String	The token ID used to process the payment.
payment-plan.frequency-day	String	The day of the month the payment is scheduled.
payment-plan.payment-amount	String	The amount to be charged for each payment.
payment-plan.start-date	String (Date)	The start date of the payment plan in YYYY-MM-DD format.
payment-plan.end-date	String (Date)	The end date of the payment plan in YYYY-MM-DD format.
payment-plan.status	String	The current status of the payment plan. For examples, ACTIVE.
payment-plan.status-date	String (Date)	The date when the current status was set.
payment-plan.frequency-month	String	The number of months between payments (if applicable).
payment-plan.frequency-week	String	The number of weeks between payments (if applicable).
payment-plan.links.link[].rel	String	Describes the relationship of the linked resource. For examples, self, customers, tokens.
payment-plan.links.link[].href	String (URI)	The URI to access the linked resource.