Apidocs

Recurring Payments API

End Point URLs

Environment	Base URL
UAT	https://api.ipospays.tech/v1
Pre-Prod	https://papi.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
  "scope": "Recurring"                  // Required: Use "Recurring" in your API requests
}

apiKey: Provided by iPOSpays. Contact support@dejavoo.io or your Dejavoo representative if you haven’t received it.
secretKey: Provided with the apiKey
scope: Must be set to "Recurring"

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.

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
consumer_id *	String	Unique identifier of the consumer whose tokens are being retrieved.

Example Request

{
  "consumer_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

Creates or modifies a recurring subscription for a customer using a tokenized payment method.

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

Request Body

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).

Example Request

{
  "customer_id": "LMN7JCZ61GGICDW",
  "recurring_frequency": "WEEKLY",
  "amount": 1000,
  "currency": "USD",
  "tpn": "282925835395",
  "end_criteria": "NEVER",
  "start_date": "2025-11-11",
  "preferred_day": "FRIDAY",
  "card_token": "BFD123DA6F5D7743E8D9418BE599A01F28A71B677407F8D5"
  // Note: Instead of card_token, you may pass ach_token for ACH-based recurring payments.
}

Success Response Parameters

Field	Type	Description
status_code *	Number	HTTP-style status code (e.g., 200 for success).
message *	String	Descriptive message summarizing the result (e.g., 'subscription added successfully').
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 newly created subscription details.
data.subscription_id *	String	Unique identifier for the newly created recurring subscription.
data.customer_id *	String	Unique identifier of the customer associated with the subscription.
data.recurring_frequency *	String	The frequency set for the recurring payment.

Example Request (Editing an Existing Subscription)

{
  "subscription_id": "V7XJKGG7FJ6HL9B",
  "recurring_frequency": "MONTHLY",
  "amount": 2500,
  "currency": "USD",
  "tpn": "282925835395",
  "end_criteria": "COUNT",
  "end_value": 12,
  "start_date": "2025-12-01",
  "card_token": "BFD123DA6F5D7743E8D9418BE599A01F28A71B677407F8D5"
  // Note: Instead of card_token, you may pass ach_token for ACH-based recurring payments.
}

Example Success Response

{
  "data": {
    "subscription_id": "V7XJKGG7FJ6HL9B",
    "customer_id": "LMN7JCZ61GGICDW",
    "recurring_frequency": "WEEKLY"
  },
  "message": "subscription added successfully",
  "response_code": "SUCCESS",
  "status_code": 200,
  "request_id": "TEST-20251112011500-LQJL3G",
  "timestamp": "2025-11-12T06:15:00.271Z"
}

Error Response Parameters

Used when validation errors occur (e.g., missing fields, invalid formats).

Field	Type	Description
status_code *	Number	HTTP-style status code (e.g., 412 for Precondition Failed).
request_id *	String	Unique request identifier for tracking purposes.
timestamp *	String	ISO 8601 timestamp indicating when the response was generated.
errors *	Array of Objects	Contains an array of validation errors.
errors[].field *	String	The name of the field that failed validation.
errors[].messages *	Array of Strings	A list of descriptive error messages for the field.

Example Error Response

{
  "errors": [
    {
      "field": "end_criteria",
      "messages": [
        "End criteria is required."
      ]
    },
    {
      "field": "start_date",
      "messages": [
        "Start date cannot be today or in the past. Please choose a future date."
      ]
    }
  ],
  "status_code": 412,
  "request_id": "TEST-20251112012935-X04_2R",
  "timestamp": "2025-11-12T06:29:35.513Z"
}

Get Recurring Transactions API

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

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

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.

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

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 CANCEL.').
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.

Error Response Code & Messages

For a complete list of error codes and their explanations, please visit our Error Codes Reference Page.

Error Codes & Messages

Recurring Payments iPOSpays WooCommerce Extension