Payment Plans

Get Payment Plan Details

get

Retrieve detailed information for a specific payment plan identified by the unique payment plan key.

Path parameters

paymentPlanKeystringRequired

Unique identifier of the payment plan.

Header parameters

api-keystringRequired

An access API key issued to you by Xplor Pay.

Responses

200

Payload

payloadTypestringOptional

Type of payload returned in the response.

Example: customers

401

Unauthorized

403

Forbidden

404

Not Found

get

/rest/v2/payment-plans/{paymentPlanKey}

GET /rest/v2/payment-plans/{paymentPlanKey} HTTP/1.1
api-key: text
Accept: */*

{
  "customers": {
    "customer": [
      {
        "email": "[email protected]",
        "phone": "444-444-4444",
        "comments": "my fav customer",
        "metadata": "any additional properties [ \"any additional property\": \"value\"]",
        "customer-key": "custID-88839992-223838-023333",
        "first-name": "John",
        "last-name": "Doe",
        "billing-address": {
          "company": "Test Company",
          "street": "123 Example Street",
          "street2": "Suite 700",
          "city": "St Louis",
          "state": "MO",
          "zip": "85284",
          "country": "United States",
          "phone": "3148889999",
          "first-name": "John",
          "last-name": "Doe"
        },
        "shipping-address": {
          "company": "Test Company",
          "street": "123 Example Street",
          "street2": "Suite 700",
          "city": "St Louis",
          "state": "MO",
          "zip": "85284",
          "country": "United States",
          "phone": "3148889999",
          "first-name": "John",
          "last-name": "Doe"
        },
        "links": {
          "link": [
            {
              "rel": "transaction",
              "href": "/rest/v2/transactions?id=846512",
              "id": "846512"
            }
          ]
        }
      }
    ]
  },
  "payloadType": "customers"
}

Update Payment Plan

put

Update the existing payment plan details identified by the specified payment plan key.

Path parameters

paymentPlanKeystringRequired

Unique identifier of the payment plan.

Header parameters

api-keystringRequired

An access API key issued to you by Xplor Pay.

Body

Represents a recurring payment plan definition.

frequencystring · enumRequired

Frequency at which the payment plan runs.

Example: MONTHLYPossible values:

plan-keystringOptional

Unique identifier of the pricing or payment plan.

Example: plan_8383-38833-3333

plan-namestringOptional

Display name of the payment plan.

Example: Test plan

customer-keystringRequired

Unique identifier of the customer for whom the payment plan is created.

Example: cust_3bf809d2-b74d-4354-bbf9-a4af6328e6e0

customer-namestringOptional

Name of the customer associated with the payment plan.

Example: John Doe

email-addressstringOptional

The customer's email address.

Example: [email protected]

email-receiptstringOptional

Indicates whether an email receipt is sent when a payment is processed. If true, a valid email-address must exist on the customer or be provided in the payment plan request.

Example: false

token-idstringRequired

Identifier of the payment token used for the card or ACH to process payments for the plan.

Example: 11000393985851111

frequency-daystringOptional

Day on which the payment is processed. For monthly and yearly plans this is the day of the month; for weekly plans, day of week (1-7).

Example: 3

payment-amountstringRequired

Amount charged to the card for each payment cycle of the plan.

Example: 200.0

ach-payment-typestringOptional

Specifies the ACH payment type used for the plan.

Example: CCD

start-datestringRequired

Specifies the date on which the payment plan becomes effective. If the specified date does not align with the frequency-day, the first payment occurs on the next frequency occurrence.

Example: 2019-05-10

end-datestringRequired

Date on which the payment plan ends. Maximum of 10 years per plan.

Example: 2021-08-10

statusstring · enumOptional

Current status of the payment plan.

Example: ACTIVEPossible values:

status-datestringOptional

Date on which the current plan status was updated.

Example: 09/19/2016

frequency-monthstringOptional

Specifies the month of the year when the payment plan is executed. For example, 1 - January, 2 - February, and so on through 12 - December.

Example: 5

frequency-weekstringOptional

Specifies the week number within the selected month when the payment plan is executed. Required when frequency is set to WEEKLY.

Example: 3

Responses

200

Payload

payloadTypestringOptional

Type of payload returned in the response.

Example: customers

401

Unauthorized

403

Forbidden

404

Not Found

put

/rest/v2/payment-plans/{paymentPlanKey}

PUT /rest/v2/payment-plans/{paymentPlanKey} HTTP/1.1
api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 604

{
  "frequency": "MONTHLY",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "plan-key": "plan_8383-38833-3333",
  "plan-name": "Test plan",
  "customer-key": "cust_3bf809d2-b74d-4354-bbf9-a4af6328e6e0",
  "customer-name": "John Doe",
  "email-address": "[email protected]",
  "email-receipt": "false",
  "token-id": "11000393985851111",
  "frequency-day": "3",
  "payment-amount": "200.0",
  "ach-payment-type": "CCD",
  "start-date": "2019-05-10",
  "end-date": "2021-08-10",
  "status": "ACTIVE",
  "status-date": "09/19/2016",
  "frequency-month": "5",
  "frequency-week": "3",
  "links": {
    "link": [
      {
        "rel": "transaction",
        "href": "/rest/v2/transactions?id=846512",
        "id": "846512"
      }
    ]
  }
}

{
  "customers": {
    "customer": [
      {
        "email": "[email protected]",
        "phone": "444-444-4444",
        "comments": "my fav customer",
        "metadata": "any additional properties [ \"any additional property\": \"value\"]",
        "customer-key": "custID-88839992-223838-023333",
        "first-name": "John",
        "last-name": "Doe",
        "billing-address": {
          "company": "Test Company",
          "street": "123 Example Street",
          "street2": "Suite 700",
          "city": "St Louis",
          "state": "MO",
          "zip": "85284",
          "country": "United States",
          "phone": "3148889999",
          "first-name": "John",
          "last-name": "Doe"
        },
        "shipping-address": {
          "company": "Test Company",
          "street": "123 Example Street",
          "street2": "Suite 700",
          "city": "St Louis",
          "state": "MO",
          "zip": "85284",
          "country": "United States",
          "phone": "3148889999",
          "first-name": "John",
          "last-name": "Doe"
        },
        "links": {
          "link": [
            {
              "rel": "transaction",
              "href": "/rest/v2/transactions?id=846512",
              "id": "846512"
            }
          ]
        }
      }
    ]
  },
  "payloadType": "customers"
}

Search Payment Plans

get

Retrieve a list of payment plans for the specified search and filter criteria.

Query parameters

plan-namestringOptional

Filters payment plans by the plan name.

plan-keystringOptional

Filters results by the unique identifier of the payment plan.

customer-keystringOptional

Filters payment plans by the unique identifier of the associated customer.

customer-namestringOptional

Filters payment plans by the customer name.

token-idstringOptional

Filters payment plans by the token associated with the plan.

payment-amountnumberOptional

Filters payment plans by the payment amount.

statusstring · enumOptional

Filters payment plans by their current status.

Possible values:

pageintegerOptional

Specifies the page number of results to return when pagination is applied.

page-sizeintegerOptional

Specifies the number of results to return per page.

isDescendingbooleanOptional

Specifies the sort order of the results. Set to true for descending order. Default is true.

order-bystring · enumOptional

Specifies the field used to sort the results.

Possible values:

Header parameters

api-keystringRequired

An access API key issued to you by Xplor Pay.

Responses

200

payload

payloadTypestringOptional

Type of payload returned in the response.

Example: payment-plans

401

Unauthorized

403

Forbidden

404

Not Found

get

/rest/v2/payment-plans

GET /rest/v2/payment-plans HTTP/1.1
api-key: text
Accept: */*

{
  "payment-plans": {
    "payment-plan": [
      {
        "frequency": "MONTHLY",
        "metadata": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "plan-key": "plan_8383-38833-3333",
        "plan-name": "Test plan",
        "customer-key": "cust_3bf809d2-b74d-4354-bbf9-a4af6328e6e0",
        "customer-name": "John Doe",
        "email-address": "[email protected]",
        "email-receipt": "false",
        "token-id": "11000393985851111",
        "frequency-day": "3",
        "payment-amount": "200.0",
        "ach-payment-type": "CCD",
        "start-date": "2019-05-10",
        "end-date": "2021-08-10",
        "status": "ACTIVE",
        "status-date": "09/19/2016",
        "frequency-month": "5",
        "frequency-week": "3",
        "links": {
          "link": [
            {
              "rel": "transaction",
              "href": "/rest/v2/transactions?id=846512",
              "id": "846512"
            }
          ]
        }
      }
    ]
  },
  "payloadType": "payment-plans"
}

Create Payment Plan

post

Create a new payment plan for a customer using the specified plan details.

Header parameters

api-keystringRequired

An access API key issued to you by Xplor Pay.

Body

Represents a recurring payment plan definition.

frequencystring · enumRequired

Frequency at which the payment plan runs.

Example: MONTHLYPossible values:

plan-keystringOptional

Unique identifier of the pricing or payment plan.

Example: plan_8383-38833-3333

plan-namestringOptional

Display name of the payment plan.

Example: Test plan

customer-keystringRequired

Unique identifier of the customer for whom the payment plan is created.

Example: cust_3bf809d2-b74d-4354-bbf9-a4af6328e6e0

customer-namestringOptional

Name of the customer associated with the payment plan.

Example: John Doe

email-addressstringOptional

The customer's email address.

Example: [email protected]

email-receiptstringOptional

Indicates whether an email receipt is sent when a payment is processed. If true, a valid email-address must exist on the customer or be provided in the payment plan request.

Example: false

token-idstringRequired

Identifier of the payment token used for the card or ACH to process payments for the plan.

Example: 11000393985851111

frequency-daystringOptional

Day on which the payment is processed. For monthly and yearly plans this is the day of the month; for weekly plans, day of week (1-7).

Example: 3

payment-amountstringRequired

Amount charged to the card for each payment cycle of the plan.

Example: 200.0

ach-payment-typestringOptional

Specifies the ACH payment type used for the plan.

Example: CCD

start-datestringRequired

Specifies the date on which the payment plan becomes effective. If the specified date does not align with the frequency-day, the first payment occurs on the next frequency occurrence.

Example: 2019-05-10

end-datestringRequired

Date on which the payment plan ends. Maximum of 10 years per plan.

Example: 2021-08-10

statusstring · enumOptional

Current status of the payment plan.

Example: ACTIVEPossible values:

status-datestringOptional

Date on which the current plan status was updated.

Example: 09/19/2016

frequency-monthstringOptional

Specifies the month of the year when the payment plan is executed. For example, 1 - January, 2 - February, and so on through 12 - December.

Example: 5

frequency-weekstringOptional

Specifies the week number within the selected month when the payment plan is executed. Required when frequency is set to WEEKLY.

Example: 3

Responses

200

Payload

payloadTypestringOptional

Type of payload returned in the response.

Example: customers

401

Unauthorized

403

Forbidden

404

Not Found

post

/rest/v2/payment-plans

POST /rest/v2/payment-plans HTTP/1.1
api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 604

{
  "frequency": "MONTHLY",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "plan-key": "plan_8383-38833-3333",
  "plan-name": "Test plan",
  "customer-key": "cust_3bf809d2-b74d-4354-bbf9-a4af6328e6e0",
  "customer-name": "John Doe",
  "email-address": "[email protected]",
  "email-receipt": "false",
  "token-id": "11000393985851111",
  "frequency-day": "3",
  "payment-amount": "200.0",
  "ach-payment-type": "CCD",
  "start-date": "2019-05-10",
  "end-date": "2021-08-10",
  "status": "ACTIVE",
  "status-date": "09/19/2016",
  "frequency-month": "5",
  "frequency-week": "3",
  "links": {
    "link": [
      {
        "rel": "transaction",
        "href": "/rest/v2/transactions?id=846512",
        "id": "846512"
      }
    ]
  }
}

{
  "customers": {
    "customer": [
      {
        "email": "[email protected]",
        "phone": "444-444-4444",
        "comments": "my fav customer",
        "metadata": "any additional properties [ \"any additional property\": \"value\"]",
        "customer-key": "custID-88839992-223838-023333",
        "first-name": "John",
        "last-name": "Doe",
        "billing-address": {
          "company": "Test Company",
          "street": "123 Example Street",
          "street2": "Suite 700",
          "city": "St Louis",
          "state": "MO",
          "zip": "85284",
          "country": "United States",
          "phone": "3148889999",
          "first-name": "John",
          "last-name": "Doe"
        },
        "shipping-address": {
          "company": "Test Company",
          "street": "123 Example Street",
          "street2": "Suite 700",
          "city": "St Louis",
          "state": "MO",
          "zip": "85284",
          "country": "United States",
          "phone": "3148889999",
          "first-name": "John",
          "last-name": "Doe"
        },
        "links": {
          "link": [
            {
              "rel": "transaction",
              "href": "/rest/v2/transactions?id=846512",
              "id": "846512"
            }
          ]
        }
      }
    ]
  },
  "payloadType": "customers"
}

Get Payment Plan Expected Runs

get

Retrieve the scheduled payment run dates for a payment plan identified by the specified payment plan key.

Path parameters

paymentPlanKeystringRequired

Unique identifier of the payment plan.

Query parameters

startstring · dateRequired

Specifies the start date of the date range used to calculate expected payment runs. Format: YYYY-MM-DD.

endstring · dateRequired

Specifies the end date of the date range used to calculate expected payment runs. Format: YYYY-MM-DD.

Header parameters

api-keystringRequired

An access API key issued to you by Xplor Pay.

Responses

200

payload

payloadTypestringOptional

Type of payload returned in the response.

Example: expected-runs

401

Unauthorized

403

Forbidden

404

Not Found

get

/rest/v2/payment-plans/{paymentPlanKey}/expected-runs

GET /rest/v2/payment-plans/{paymentPlanKey}/expected-runs?start=2026-02-19&end=2026-02-19 HTTP/1.1
api-key: text
Accept: */*

{
  "expected-runs": {
    "expectedRun": [
      {
        "amount": 100,
        "plan-detail-key": "10009993322221111",
        "fire-time": "2026-02-19T00:03:03.518Z"
      }
    ]
  },
  "payloadType": "expected-runs"
}

Delete Payment Plan

delete

Delete an existing payment plan identified by the specified plan key.

Path parameters

planKeystringRequired

Unique identifier of the payment plan.

Header parameters

api-keystringRequired

An access API key issued to you by Xplor Pay.

Responses

401

Unauthorized

403

Forbidden

404

Not Found

delete

/rest/v2/payment-plans/{planKey}

DELETE /rest/v2/payment-plans/{planKey} HTTP/1.1
api-key: text
Accept: */*

{
  "error": {
    "error-message": "text",
    "result-code": "1",
    "time-stamp": "2025-10-23T03:06:37.237Z"
  },
  "payloadType": "error"
}

PreviousRecurring Payments Service NextCustomer Token

Last updated 11 hours ago

Was this helpful?

hashtagGet Payment Plan Details

hashtagUpdate Payment Plan

hashtagSearch Payment Plans

hashtagCreate Payment Plan

hashtagGet Payment Plan Expected Runs

hashtagDelete Payment Plan

Get Payment Plan Details

Update Payment Plan

Search Payment Plans

Create Payment Plan

Get Payment Plan Expected Runs

Delete Payment Plan