# Process recurring payments

{% hint style="info" %}
See [Authentication](https://app.gitbook.com/s/j9heLdoDRsfnChUQohvj/api-core-standards#authentication) when you call the Recurring Payments Service API endpoints to process recurring payments for your customers.
{% endhint %}

The following steps explain how to process recurring payments:

{% stepper %}
{% step %}
**Create a new customer**

1. Add the following fields to the request body when calling the [Recurring Payments Services API](https://docs.xplorpay.com/api-references/payments/cards/recurring-payments-service) endpoint.

{% code lineNumbers="true" %}

```json
{
    "first-name": "Clark",
    "last-name": "Kent",
    "email": "test@test.com",
    "billing-address": {
        "street": "1938 DeSota Rd",
        "city": "Smallville",
        "state": "Kansas",
        "zip": "12345",
        "phone": "5555555555"
    }
}
```

{% endcode %}

The following table describes the fields from the request body:

<table><thead><tr><th width="160.33331298828125" valign="top">Name</th><th width="116.66668701171875" valign="top">Data type</th><th width="120.66668701171875">Required?</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>first-name</code></td><td valign="top">String</td><td>Required</td><td valign="top">The customer's first name.</td></tr><tr><td valign="top"><code>last-name</code></td><td valign="top">String</td><td>Required</td><td valign="top">The customer's last name.</td></tr><tr><td valign="top"><code>email</code></td><td valign="top">String</td><td>Required</td><td valign="top">The customer's email address.</td></tr><tr><td valign="top"><code>billing-address</code></td><td valign="top">Object</td><td>Required</td><td valign="top">The customer's billing address details.</td></tr><tr><td valign="top"><code>billing-address.street</code><br></td><td valign="top">String</td><td>Required</td><td valign="top">The street address of the customer.</td></tr><tr><td valign="top"><code>billing-address.city</code></td><td valign="top">String</td><td>Required</td><td valign="top">The city of the customer's billing address.</td></tr><tr><td valign="top"><code>billing-address.state</code></td><td valign="top">String</td><td>Required</td><td valign="top">The state or region of the customer's billing address.</td></tr><tr><td valign="top"><code>billing-address.zip</code></td><td valign="top">String</td><td>Required</td><td valign="top">The ZIP or postal code of the customer's billing address.</td></tr><tr><td valign="top"><code>billing-address.phone</code></td><td valign="top">String</td><td>Required</td><td valign="top">The customer's phone number.</td></tr></tbody></table>

2. Use **POST** method to call the `rest/v2/customers` endpoint.

The API returns the following response:

{% code lineNumbers="true" %}

```json
{
    "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": "test@test.com",
            "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"
    }
}
```

{% endcode %}

The API response includes the following fields:

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

{% endstep %}

{% step %}
**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](https://docs.xplorpay.com/api-references/payments/cards/recurring-payments-service) endpoint.

{% hint style="warning" %}
The `customer key` field in the request body is ***required*** to get a token for customer. For example, `cust_99b2bf69-2bb6-4a03-8a84-489bec69f78e`
{% endhint %}

{% code lineNumbers="true" %}

```json
{
    "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"
}
```

{% endcode %}

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

The API returns the following response:

{% code lineNumbers="true" %}

```json
{
    "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": "david.fitzpatrick@xplortechnologies.com",
            "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"
    }
}
```

{% endcode %}

The API response includes the following fields:

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

{% step %}
**Create a payment plan**

1. Add the following fields in the request body when calling the [Recurring Payments Services API](https://docs.xplorpay.com/api-references/payments/cards/recurring-payments-service) endpoint.

{% code lineNumbers="true" %}

```json
{
    "customer-key": "cust_27d8fd09-d092-4809-869f-337eb64839b5",
    "customer-name": "Token Test",
    "email-address": "david.fitzpatrick@xplortechnologies.com",
    "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"
}
```

{% endcode %}

The following table describes the fields from the request body:

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

2. Use the **POST** method to call the `rest/v2/payment-plans` endpoint.

The API returns the following response:

{% code lineNumbers="true" %}

```json
{
    "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": "david.fitzpatrick@xplortechnologies.com",
            "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"
    }
}
```

{% endcode %}

The API response includes the following fields:

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