Apidocs

Recurring Payments API

End Point URLs

Environment	Base URL
UAT	https://api.ipospays.tech/v1
Pre-Prod	https://api.ipospays.tech/v1
Production	https://api.ipospays.com/v1

Authentication

Authentication is handled through a dedicated token generation API. Follow the steps below to obtain your token:

Step 1: Access the Authentication Token API

Refer to the official documentation to understand the request structure and response handling:

iPOSpays Authentication Token API

Step 2: Prepare Your API Credentials

Before making a request, ensure you have the required credentials issued by iPOSpays. These credentials include:

{
  "apiKey": "your_api_key_here",        // Required: Your assigned API key from iPOSpays
  "secretKey": "your_secret_key_here",  // Required: Your assigned secret key from iPOSpays
}

apiKey: Must be generated from the iPOSpays portal
secretKey: Provided with the API key on iPOSpays

Refer to the iPOSpays Authentication Token API to learn how to generate the API Key and Secret Key

Step 3: Use the Token

Once the API call is successful, a valid authentication token will be returned in the response. Include this token in the header of your subsequent API requests.

Header	Type	Description
token	string	Security token required for authenticating API requests.

Get Payment Tokens API

Retrieves all tokenized payment instruments (Cards and Bank accounts) associated with a specific customer identifier.

Endpoint Details

Parameter	Value
URL Path	/subscription/get-cards
Full URL (UAT)	https://api.ipospays.tech/v1/subscription/get-cards
Method	POST
Authentication	Required (via token header)

Request Body (JSON)

The payload requires the unique customer identifier.

Field	Type	Description
customer_id *	String	Unique identifier of the consumer whose tokens are being retrieved.

Example Request

{
  "customer_id": "LMN7JCZ61GGICDW"
}

Response Parameters

The API returns a JSON object containing an array of payment tokens.

Field	Type	Description
status_code *	Number	HTTP-style status code (e.g., 200 for success).
message *	String	Descriptive message summarizing the result.
response_code *	String	A short string code that indicates the status of the response.
request_id *	String	Unique request identifier for tracking purposes.
timestamp *	String	ISO 8601 timestamp indicating when the response was generated.
tokens[] *	Array	Array of tokenized payment instruments.
tokens[].token *	String	Unique payment token.
tokens[].type *	String	Type of payment: "CARD" or "ACH".
tokens[].brand	String	Card brand (e.g., "VISA", "MASTERCARD"). Present only if type = "CARD".
tokens[].sec_code	String	ACH Standard Entry Class (SEC) code (e.g., "TEL", "PPD", "CCD", "WEB"). Present only if type = "ACH".
tokens[].last4 *	String	Last four digits of the card or ACH account number.

Example Response

{
  "status_code": 200,
  "message": "Cards fetched successfully",
  "response_code": "success",
  "request_id": "REQ-123456789",
  "timestamp": "2025-11-11T09:53:41.892Z",
  "tokens": [
    {
      "token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
      "type": "CARD",
      "brand": "VISA",
      "last4": "1234"
    },
    {
      "token": "8AF62C31DE1B37C89AF62C31DE1B37C8998F41E2CC95D2C3",
      "type": "ACH",
      "sec_code": "PPD",
      "last4": "7890"
    }
  ]
}

Setup Recurring API

This API allows you to create and manage automated recurring payment schedules for both card and ACH payment methods.

Using this API, you can configure recurring billing frequencies such as weekly, monthly, quarterly, annually, or fully custom intervals. It also supports flexible end conditions, including subscriptions that never expire, subscriptions that stop after a specific number of payments, or subscriptions that end on a defined date.

This endpoint supports:

Card and ACH recurring payments
Weekly, monthly, quarterly, annual, and custom billing schedules
Fixed payment count or end-date termination
ACH SEC code configuration
Updating existing subscriptions using subscription_id

All requests must be authenticated using a valid token header.

Endpoint

Parameter	Value
URL Path	/subscription/setup
Full URL (UAT)	https://api.ipospays.tech/v1/subscription/setup
Method	POST
Authentication	Required (via token header)

Parameter Reference

Field	Type	Description
customer_id	String	Unique identifier of the customer. Required for new setup; optional/not used for editing via subscription_id.
subscription_id	String	Required only for editing an existing subscription.
recurring_frequency *	String	The frequency of the recurring payment. Allowed values: WEEKLY, BI_WEEKLY, MONTHLY, BI_MONTHLY, QUARTERLY, BI_ANNUALLY, ANNUALLY, CUSTOM.
amount *	Number	The recurring payment amount (in cents/smallest unit). Range: 1 to 999999 cents.
currency *	String	The currency code (e.g., "USD").
tpn *	String	TPN number.
end_criteria *	String	Defines when the recurring payment should stop. Allowed values: NEVER, COUNT, DATE.
start_date	String	The date of the first recurring payment. Required for all frequencies except BI_MONTHLY and BI_ANNUALLY.
end_value	Number	Required only if end_criteria is DATE or COUNT. If DATE, value is (YYYY-MM-DD). If COUNT, value is a number (1 to 100).
preferred_day	String	Preferred day of the week (e.g., 'FRIDAY'). Values are MONDAY to SATURDAY. Required if recurring_frequency is WEEKLY or BI_WEEKLY.
card_token	String	Required for card recurring. Must provide card_token.
ach_token	String	Required for ACH recurring. Must provide ach_token.
reference_id	String	Reference ID for the recurring payment (1–12 alphanumeric characters, or empty)
sec_code	String	Allowed for ACH only. Accepted values: PPD, WEB, CCD, TEL. If a sec_code isn’t provided, the system auto-assigns in this order: PPD → WEB → CCD → TEL. Example: if both WEB and CCD tokens are available, system uses WEB.
day_1	Number	Required only for bi-monthly and bi-annual frequencies. If BI_MONTHLY, value is 1–31 (day of month). If BI_ANNUALLY, value is a date (YYYY-MM-DD).
day_2	Number	Required only for bi-monthly and bi-annual frequencies. If BI_MONTHLY, value is 1–31. If BI_ANNUALLY, value is a date (YYYY-MM-DD).
custom_interval_days	Number	Required when recurring_frequency is CUSTOM. Defines the custom billing interval in days.

The following examples cover the most commonly used recurring payment configurations.

Weekly · Card · Never Ends

Description

Charges the customer's card every week.
preferred_day determines the day the payment is processed.
end_criteria = NEVER keeps the subscription active until manually cancelled.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "card_token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
  "recurring_frequency": "WEEKLY",
  "end_criteria": "NEVER",
  "start_date": "2026-12-03",
  "preferred_day": "THURSDAY"
}

Weekly · ACH · With SEC Code & Reference ID

Description

Charges a bank account every week using ACH.
sec_code defines the ACH transaction type.
reference_id can be used for internal merchant tracking.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "ach_token": "05944FB3E1DA4663868455AF630F45BE",
  "recurring_frequency": "WEEKLY",
  "end_criteria": "NEVER",
  "start_date": "2026-12-03",
  "preferred_day": "TUESDAY",
  "sec_code": "WEB",
  "reference_id": "INV2025001"
}

Bi-Weekly · Card · Never Ends

Description

Charges the customer every two weeks.
Commonly used for payroll-aligned billing schedules.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "card_token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
  "recurring_frequency": "BI_WEEKLY",
  "end_criteria": "NEVER",
  "start_date": "2026-12-03",
  "preferred_day": "THURSDAY"
}

Bi-Weekly · ACH · Ends by Count

Description

Processes ACH payments every two weeks.
Stops automatically after the specified number of payments.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "ach_token": "05944FB3E1DA4663868455AF630F45BE",
  "recurring_frequency": "BI_WEEKLY",
  "end_criteria": "COUNT",
  "end_value": 26,
  "start_date": "2026-12-03",
  "preferred_day": "THURSDAY",
  "sec_code": "PPD"
}

Monthly · Card · Never Ends

Description

Standard monthly recurring card payment.
Charges occur monthly based on the start_date.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "card_token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
  "recurring_frequency": "MONTHLY",
  "end_criteria": "NEVER",
  "start_date": "2026-12-03"
}

Monthly · ACH · Never Ends

Description

Monthly ACH debit from a customer bank account.
Commonly used for utilities, insurance, or subscription billing.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "ach_token": "05944FB3E1DA4663868455AF630F45BE",
  "recurring_frequency": "MONTHLY",
  "end_criteria": "NEVER",
  "start_date": "2026-12-03",
  "sec_code": "CCD"
}

Bi-Monthly · Card · Never Ends

Description

Charges twice per month on two specific dates.
day_1 and day_2 represent calendar days of the month.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "card_token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
  "recurring_frequency": "BI_MONTHLY",
  "end_criteria": "NEVER",
  "day_1": 1,
  "day_2": 15
}

Bi-Monthly · ACH · Ends by Count

Description

ACH debit scheduled twice every month.
Stops automatically after the specified payment count.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "ach_token": "05944FB3E1DA4663868455AF630F45BE",
  "recurring_frequency": "BI_MONTHLY",
  "end_criteria": "COUNT",
  "end_value": 24,
  "day_1": 1,
  "day_2": 15,
  "sec_code": "PPD"
}

Quarterly · Card · Never Ends

Description

Charges once every three months.
Suitable for quarterly software or service billing.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "card_token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
  "recurring_frequency": "QUARTERLY",
  "end_criteria": "NEVER",
  "start_date": "2026-12-03"
}

Quarterly · ACH · Ends by Date

Description

ACH payments processed every quarter.
Subscription automatically stops on the specified end date.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "ach_token": "05944FB3E1DA4663868455AF630F45BE",
  "recurring_frequency": "QUARTERLY",
  "end_criteria": "DATE",
  "end_value": "2027-11-11",
  "start_date": "2026-12-03",
  "sec_code": "PPD"
}

Bi-Annually · Card · Never Ends

Description

Charges twice per year on two specific dates.
day_1 and day_2 must be full dates in YYYY-MM-DD format.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "card_token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
  "recurring_frequency": "BI_ANNUALLY",
  "end_criteria": "NEVER",
  "day_1": "2026-06-01",
  "day_2": "2027-12-01"
}

Bi-Annually · ACH · Ends by Count

Description

ACH payments scheduled twice per year.
Stops after the configured number of payments.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "ach_token": "05944FB3E1DA4663868455AF630F45BE",
  "recurring_frequency": "BI_ANNUALLY",
  "end_criteria": "COUNT",
  "end_value": 4,
  "day_1": "2026-06-01",
  "day_2": "2027-12-01",
  "sec_code": "PPD"
}

Annually · Card · Never Ends

Description

Processes one payment every year.
Charges recur annually based on the start_date.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "card_token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
  "recurring_frequency": "ANNUALLY",
  "end_criteria": "NEVER",
  "start_date": "2026-12-03"
}

Annually · ACH · Ends by Date

Description

Annual ACH payment schedule with a fixed expiration date.
Useful for multi-year service agreements.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "ach_token": "05944FB3E1DA4663868455AF630F45BE",
  "recurring_frequency": "ANNUALLY",
  "end_criteria": "DATE",
  "end_value": "2027-11-11",
  "start_date": "2026-12-03"
}

Custom Frequency · Card · Never Ends

Description

Allows custom billing intervals not covered by standard frequencies.
custom_interval_days defines the interval between charges.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "card_token": "7CB5968FACE5A7127CB5968FACE5A7124572FEB954D4A017",
  "recurring_frequency": "CUSTOM",
  "end_criteria": "NEVER",
  "custom_interval_days": 45,
  "start_date": "2026-12-03"
}

Custom Frequency · ACH · Never Ends

Description

ACH recurring payments using a custom interval.
Useful for negotiated or non-standard billing cycles.

Payload

{
  "customer_id": "LMN7JCZ61GGICDW",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "ach_token": "05944FB3E1DA4663868455AF630F45BE",
  "recurring_frequency": "CUSTOM",
  "end_criteria": "NEVER",
  "start_date": "2026-12-03",
  "custom_interval_days": 45
}

Get Recurring Transactions API

Retrieves a list of all executed transactions under a specified recurring subscription.

Endpoint Details

Parameter	Value
URL Path	/subscription/transactions
Full URL (UAT)	https://api.ipospays.tech/v1/subscription/transactions
Method	POST
Authentication	Required (via token header)

Request Body (JSON)

Field	Type	Description
subscription_id *	String	Unique identifier of the subscription to retrieve transactions.

Example Request

{
  "subscription_id": "LMN7JCZ61GGICDW"
}

Response Parameters

Field	Type	Description
status_code *	Number	HTTP-style status code (e.g., 200 for success).
message *	String	Descriptive message summarizing the result.
response_code *	String	A short string code that indicates the status of the response.
request_id *	String	Unique request identifier for tracking purposes.
timestamp *	String	ISO 8601 timestamp indicating when the response was generated.
data *	Object	Container for the subscription and transaction details.
data.subscription_id *	String	Unique identifier for the recurring subscription.
data.tpn *	String	TPN number associated with the subscription.
data.status *	String	Current status of the subscription (e.g., 'ACTIVE', 'CANCEL').
data.amount *	Number	The recurring payment amount (in cents/smallest unit).
data.currency *	String	The currency code (e.g., 'USD').
data.recurring_frequency *	String	The frequency of the recurring payment.
data.next_payment_date *	String (YYYY-MM-DD)	The date of the next scheduled payment.
data.end_criteria *	String	Defines when the recurring payment should stop (e.g., 'NEVER', 'COUNT', 'DATE').
data.end_value	String/Number	Required only if end_criteria is DATE or COUNT.
data.type *	String	Type of payment method used ('CARD' or 'ACH').
data.reference_id	String	Reference ID for the recurring payment.
data.transactions *	Array of Objects	List of transactions executed under this subscription.
data.transactions[].transaction_id *	String	Unique identifier for the specific transaction.
data.transactions[].amount *	Number	Amount of the specific transaction.
data.transactions[].last4 *	String	Last four digits of the payment method used for the transaction.
data.transactions[].payment_date *	String (YYYY-MM-DD)	Date the transaction occurred.
data.transactions[].tpn *	String	TPN number for the transaction.
data.transactions[].status *	String	Status of the transaction (e.g., 'SUCCESS', 'FAILED').

Example Response

{
  "data": {
    "transactions": [
      {
        "transaction_id": "51088655988483539520250927060054",
        "amount": 1.11,
        "last4": "4242",
        "payment_date": "2025-09-27",
        "tpn": "282925835395",
        "status": "SUCCESS"
      }
    ],
    "subscription_id": "KJOT4DMXNILODKR",
    "tpn": "282925835395",
    "status": "ACTIVE",
    "amount": 1.11,
    "currency": "USD",
    "recurring_frequency": "ANNUALLY",
    "next_payment_date": "2026-09-27",
    "end_criteria": "COUNT",
    "end_value": 2,
    "type": "CARD",
    "reference_id": "111111111111"
  },
  "message": "transactions",
  "response_code": "success",
  "status_code": 200,
  "request_id": "TEST-20251112013220-2HO5ZL",
  "timestamp": "2025-11-12T06:32:20.540Z"
}

Active/Cancel Recurring API

Allows partners to change the status of an existing recurring subscription between ACTIVE and CANCEL.

Endpoint Details

Parameter	Value
URL Path	/subscription/status
Full URL (UAT)	https://api.ipospays.tech/v1/subscription/status
Method	POST
Authentication	Required (via token header)

Request Body (JSON)

Field	Type	Description
subscription_id *	String	Unique identifier of the subscription.
status *	String	New status of the subscription. Allowed values: ACTIVE or CANCEL.

Example Request

{
  "subscription_id": "LMN7JCZ61GGICDW",
  "status": "ACTIVE"
}

Response Parameters

Field	Type	Description
status_code *	Number	HTTP-style status code (e.g., 200 for success/no change).
message *	String	Descriptive message summarizing the result (e.g., 'Subscription status updated to CANCELLED.').
response_code *	String	A short string code that indicates the status of the response.
request_id *	String	Unique request identifier for tracking purposes.
timestamp *	String	ISO 8601 timestamp indicating when the response was generated.

Example Response

{
  "message": "Subscription status updated to CANCELLED.",
  "response_code": "SUCCESS",
  "status_code": 200,
  "request_id": "TEST-20251124070000-X5L9J",
  "timestamp": "2025-11-24T12:00:00.000Z"
}

Error Handling

Standard HTTP-style status codes and descriptive messages are used to communicate the result of an API request. Detailed error information is provided in the response body for validation failures (Status Code 412).

Code	Meaning	Description
200	Success	Request completed successfully.
400	Bad Request	Missing or invalid input parameters in the request (e.g., malformed JSON).
401	Unauthorized	Invalid, missing, or expired authentication token.
404	Not Found	No matching records found for the consumer ID/subscription ID, or the requested endpoint is unavailable.
412	Precondition Failed	The request failed due to validation errors (e.g., missing required fields, invalid date format, see Error Response Parameters in Setup Recurring API).
500	Internal Server Error	An unexpected server error occurred during processing.

API Response Message Reference

Error Codes & Messages

Recurring Payments iPOSpays WooCommerce Extension