AutoPay API
Create an AutoPay mandate request and send your customer to TPI Pay's hosted checkout to authorize recurring payments.
How it works
Make the API request from your backend, then redirect the customer to the returned checkout URL. The customer completes mandate authorization on the hosted checkout. Keep the transaction ID and payment ID so you can reconcile the mandate with your records.
| Step | Action | What to do |
|---|---|---|
| 1 | Create an AutoPay mandate request. | Send a unique transaction_id and customer details. |
| 2 | Redirect the customer. | When success is true, use data.checkout_url from the response. |
| 3 | Customer authorizes the mandate. | UPI authorization starts automatically and displays a QR/UPI app link; no separate authorize button is needed. For Card AutoPay, open Enter card details, enter the card data, then submit the authorize button inside that accordion. |
| 4 | Reconcile the result. | Store data.payment_id and data.transaction_id; do not treat the initial pending state as an authorization success. |
Base URL and authentication
Use the versioned merchant API endpoint. The request must come from an IP address allowed for your merchant account.
| Header | Required | Description |
|---|---|---|
X-API-KEY | Yes | Your active merchant API key. |
Authorization | Yes | Your merchant API secret. You may alternatively send the secret in X-API-SECRET. An optional Bearer prefix is also accepted. |
Content-Type | Yes | Set to application/json. |
Accept | Recommended | Set to application/json to receive JSON error responses. |
environment in the JSON body as live or test. It must match the environment assigned to your API key; use the matching key and secret for that environment. The request field cannot switch a Test credential to Live or vice versa.Create an AutoPay mandate
All fields marked required must be included in the JSON request body, matching the required AutoPay information collected in the agent portal. The server calculates the installment from the EMI fields; do not send a client-supplied amount. Use a new transaction ID for every request. The selected environment must match your API credentials.
| Field | Type | Required | Validation / description |
|---|---|---|---|
transaction_id | string | Yes | Your unique reference for this request; maximum 255 characters. It must not have been used for another payment/mandate under your merchant account. Reuse returns 409. |
amount | number | Do not send | The installment is calculated from principal_amount, interest, duration, and frequency. A client-supplied amount is prohibited; send the EMI inputs instead. |
principal_amount | number | Yes | Principal in INR; greater than 0 and no more than 100000000. |
interest_type | string | Yes | percentage or flat. |
interest_value | number | Yes | Percentage value (maximum 1000) or flat interest amount (maximum 100000000). |
duration_months | integer | Yes | Plan duration from 1 to 1200 months. Yearly frequency requires at least 12 months. |
frequency | string | Yes | DAILY, WEEKLY, MONTHLY, or YEARLY. |
start_date | date | Yes | Start date in YYYY-MM-DD format; today or a future date. |
plan_name | string | No | Optional plan label; maximum 255 characters. |
gateway | string | No | Optional gateway slug such as payu or cashfree. It must be active and assigned to this merchant for the API-key environment; otherwise the request is rejected. |
customer_name | string | Yes | Customer's name; maximum 255 characters. |
customer_email | string | Yes | Customer's email address; must be valid and no longer than 255 characters. |
customer_phone | string | Yes | Customer's phone number; maximum 20 characters. Send as a string to preserve leading zeroes or country prefix. |
description | string | No | Optional description; maximum 1000 characters. Defaults to Autopay mandate subscription when omitted. |
payment_method | string | No | Allowed values are UPI or CARD; defaults to UPI. UPI is the recommended method. Card mandate support depends on the configured gateway; PayU card AutoPay is currently not implemented. |
success_url | URL | No | Your customer return URL after verified mandate authorization. TPI Pay appends transaction_id. |
failure_url | URL | No | Your customer return URL after a failed authorization. TPI Pay appends transaction_id. |
cancel_url | URL | No | Your customer return URL after a cancelled authorization. TPI Pay appends transaction_id. |
webhook_url | URL | No | Your server endpoint for terminal payment status events. If omitted, AutoPay uses the active webhook configured in your agent dashboard for the request environment. For a request URL, TPI Pay sends payment.success, payment.failed, or payment.cancelled, signed in X-Signature. Dashboard-configured webhooks use payment.status, X-Webhook-Signature, and X-Webhook-Event, matching the dashboard test webhook format. |
environment | string | Yes | Must be live or test, and must match the environment assigned to the API key and secret in the request headers. A mismatch returns HTTP 422 with ENVIRONMENT_MISMATCH. |
Copy-paste cURL
Replace the API credentials and example customer/order values with your own. The server calculates the EMI using the required plan inputs; do not include a client-supplied amount. Keep this request on your server.
curl --request POST 'https://staging.login.tpipay.ai/api/v1/autopay/mandate' \
--header 'X-API-KEY: your-merchant-api-key' \
--header 'Authorization: your-merchant-api-secret' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"transaction_id": "AUTOPAY-20261015-0001",
"principal_amount": 1200.00,
"interest_type": "percentage",
"interest_value": 10.00,
"duration_months": 12,
"frequency": "MONTHLY",
"start_date": "2026-11-15",
"plan_name": "12 month membership",
"customer_name": "Raj Sharma",
"customer_email": "raj@example.com",
"customer_phone": "9876543210",
"description": "Monthly membership",
"payment_method": "UPI",
"gateway": "cashfree",
"success_url": "https://merchant.example/autopay/success",
"failure_url": "https://merchant.example/autopay/failure",
"cancel_url": "https://merchant.example/autopay/cancel",
"webhook_url": "https://merchant.example/api/payment-webhook",
"environment": "live"
}'
Response and next steps
A successful request returns the created payment, a hosted checkout link, and the server-calculated EMI schedule. The same plan breakdown is shown on the hosted forwarding checkout. The returned gateway response is provider-specific and may vary by environment and payment method.
{
"success": true,
"message": "Autopay mandate created successfully.",
"data": {
"payment_id": 12345,
"transaction_id": "AUTOPAY-20261015-0001",
"amount": "110.00",
"status": "pending",
"environment": "live",
"gateway": "cashfree",
"payment_method": "UPI",
"checkout_url": "https://your-tpipay-domain.example/autopay/forwarding-checkout/example-token",
"status_url": "https://your-tpipay-domain.example/api/v1/status/AUTOPAY-20261015-0001",
"success_url": "https://merchant.example/autopay/success",
"failure_url": "https://merchant.example/autopay/failure",
"cancel_url": "https://merchant.example/autopay/cancel",
"webhook_url": "https://merchant.example/api/payment-webhook",
"emi": {
"principal_amount": "1200.00",
"interest_type": "percentage",
"interest_value": "10.00",
"frequency": "MONTHLY",
"duration_months": 12,
"total_cycles": 12,
"interest_amount": "120.00",
"total_payable_amount": "1320.00",
"installment_amount": "110.00",
"start_date": "2026-11-15",
"end_date": "2027-11-15"
}
}
}
| Response field | Description |
|---|---|
success | Indicates whether a checkout can be opened or the payment is already successful. Check this value and data.status; HTTP 200 alone does not confirm customer authorization. Gateway initiation failures return a non-2xx error response. |
data.payment_id | TPI Pay payment record ID. Save it for reconciliation/support. |
data.transaction_id | Your transaction reference, echoed back for matching the response to your order. |
data.amount | Calculated installment amount formatted as a decimal string with two places. |
data.gateway | Gateway selected from the merchant's active credentials for the authenticated environment. |
data.emi | Server-calculated schedule: principal_amount, interest_type, interest_value, frequency, duration_months, total_cycles, interest_amount, total_payable_amount, installment_amount, start_date, and end_date. The hosted forwarding checkout shows the matching calculation. |
data.status | Current payment state at the time the request completes. It may be pending; wait for authorization and verify the final state before fulfilling an order. |
data.environment | Environment resolved from the authenticated API credential. |
data.payment_method | Payment method selected for the mandate. |
data.checkout_url | Hosted checkout URL. Redirect the customer here to continue mandate authorization. |
data.status_url | Authenticated merchant status endpoint for this transaction. Poll it from your backend using the same API credentials. |
data.success_url, data.failure_url, data.cancel_url | The customer return URLs saved from the request. The appropriate URL is used only after the mandate result is verified; transaction_id is appended. |
data.webhook_url | The effective merchant webhook URL: request-level URL if supplied, otherwise the active agent-dashboard URL for this environment. Terminal AutoPay status transitions trigger a signed merchant webhook event. |
success is true, use the returned checkout_url as the normal customer journey. If the response is non-2xx, do not redirect the customer; use its error_code and message and contact TPI Pay support with the transaction ID if needed. A created mandate request is not the same as an authorized mandate: verify its final status before marking the customer's recurring payment setup complete.Check payment status
Use the shared authenticated merchant payment-status API for AutoPay too; no separate public AutoPay status endpoint is required. The response includes both payment status and AutoPay subscription_status, plus the saved merchant return/webhook URLs.
Copy-paste cURL
curl --request GET 'https://staging.login.tpipay.ai/api/v1/status/AUTOPAY-20261015-0001' \ --header 'X-API-KEY: your-merchant-api-key' \ --header 'Authorization: your-merchant-api-secret' \ --header 'Accept: application/json'
{
"success": true,
"data": {
"transaction_id": "AUTOPAY-20261015-0001",
"payment_id": 12345,
"currency": "INR",
"amount": "110.00",
"status": "pending",
"subscription_status": "pending",
"success_url": "https://merchant.example/autopay/success",
"failure_url": "https://merchant.example/autopay/failure",
"cancel_url": "https://merchant.example/autopay/cancel",
"webhook_url": "https://merchant.example/api/payment-webhook",
"bank_ref_num": null,
"payment_method": "UPI",
"paid_at": null
}
}
status is the payment state and subscription_status is the mandate state; pending is not successful authorization. Keep polling from your backend and fulfill only after the mandate is active. The merchant webhook_url is distinct from the gateway's TPI Pay webhook endpoint.Errors and troubleshooting
Check the HTTP status and JSON body. Validation errors use Laravel's standard message and errors response fields.
| HTTP status | Error / meaning | What to check |
|---|---|---|
| 401 | Missing or invalid API key/secret. | Confirm the active merchant credentials and send them in the documented headers. |
| 403 | Merchant access denied, account inactive, or request IP not allowlisted. | Confirm the account is active, the API key belongs to a merchant-enabled account, and the calling server IP is allowed. |
| 409 | DUPLICATE_TRANSACTION_ID. | Use a unique transaction ID. For a retry after a timeout, reconcile the original request before creating a new transaction. |
| 404 | Payment not found on the status endpoint. | Confirm the transaction ID and that the API credentials use the same environment as the original request. |
| 422 | One or more fields failed validation. | Read errors for the fields to correct; check the required EMI/customer fields, installment limit, allowed payment methods, and field lengths. Do not send amount. |
| 422 | GATEWAY_NOT_CONFIGURED: the explicitly requested gateway is not active or assigned to this merchant. | Choose an assigned gateway or omit gateway to use the merchant's default gateway. |
| 422 | ENVIRONMENT_MISMATCH: body environment does not match the API credential environment. | Use live with a Live API key/secret, or test with Test credentials. |
| 503 | AUTOPAY_GATEWAY_NOT_CONFIGURED: no active gateway is assigned for this merchant and API-key environment. | Contact TPI Pay support to enable a gateway for your merchant in the matching test/live environment. |
| 500 | AUTOPAY_CREATION_FAILED: an unexpected server error prevented mandate creation. | Check the transaction ID before retrying and contact TPI Pay support if the problem persists. |
| 502 | AUTOPAY_INITIATION_FAILED or a gateway-specific error: the mandate request was created, but the gateway did not provide a usable authorization URL. | Do not redirect the customer; contact TPI Pay support with the transaction ID before retrying. |
{
"message": "The principal amount field is required.",
"errors": {
"principal_amount": [
"The principal amount field is required."
]
}
}
