TPI Pay
Recurring payments

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.

StepActionWhat to do
1Create an AutoPay mandate request.Send a unique transaction_id and customer details.
2Redirect the customer.When success is true, use data.checkout_url from the response.
3Customer 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.
4Reconcile the result.Store data.payment_id and data.transaction_id; do not treat the initial pending state as an authorization success.
Call this endpoint only from your server. Never put your merchant API secret in browser or mobile-app code.

Base URL and authentication

Use the versioned merchant API endpoint. The request must come from an IP address allowed for your merchant account.

POST https://staging.login.tpipay.ai/api/v1/autopay/mandate
HeaderRequiredDescription
X-API-KEYYesYour active merchant API key.
AuthorizationYesYour merchant API secret. You may alternatively send the secret in X-API-SECRET. An optional Bearer prefix is also accepted.
Content-TypeYesSet to application/json.
AcceptRecommendedSet to application/json to receive JSON error responses.
Include 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.

FieldTypeRequiredValidation / description
transaction_idstringYesYour 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.
amountnumberDo not sendThe installment is calculated from principal_amount, interest, duration, and frequency. A client-supplied amount is prohibited; send the EMI inputs instead.
principal_amountnumberYesPrincipal in INR; greater than 0 and no more than 100000000.
interest_typestringYespercentage or flat.
interest_valuenumberYesPercentage value (maximum 1000) or flat interest amount (maximum 100000000).
duration_monthsintegerYesPlan duration from 1 to 1200 months. Yearly frequency requires at least 12 months.
frequencystringYesDAILY, WEEKLY, MONTHLY, or YEARLY.
start_datedateYesStart date in YYYY-MM-DD format; today or a future date.
plan_namestringNoOptional plan label; maximum 255 characters.
gatewaystringNoOptional 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_namestringYesCustomer's name; maximum 255 characters.
customer_emailstringYesCustomer's email address; must be valid and no longer than 255 characters.
customer_phonestringYesCustomer's phone number; maximum 20 characters. Send as a string to preserve leading zeroes or country prefix.
descriptionstringNoOptional description; maximum 1000 characters. Defaults to Autopay mandate subscription when omitted.
payment_methodstringNoAllowed 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_urlURLNoYour customer return URL after verified mandate authorization. TPI Pay appends transaction_id.
failure_urlURLNoYour customer return URL after a failed authorization. TPI Pay appends transaction_id.
cancel_urlURLNoYour customer return URL after a cancelled authorization. TPI Pay appends transaction_id.
webhook_urlURLNoYour 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.
environmentstringYesMust 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.

Example response
{
  "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 fieldDescription
successIndicates 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_idTPI Pay payment record ID. Save it for reconciliation/support.
data.transaction_idYour transaction reference, echoed back for matching the response to your order.
data.amountCalculated installment amount formatted as a decimal string with two places.
data.gatewayGateway selected from the merchant's active credentials for the authenticated environment.
data.emiServer-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.statusCurrent 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.environmentEnvironment resolved from the authenticated API credential.
data.payment_methodPayment method selected for the mandate.
data.checkout_urlHosted checkout URL. Redirect the customer here to continue mandate authorization.
data.status_urlAuthenticated merchant status endpoint for this transaction. Poll it from your backend using the same API credentials.
data.success_url, data.failure_url, data.cancel_urlThe 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_urlThe 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.
When 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.

GET https://staging.login.tpipay.ai/api/v1/status/{transaction_id}

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'
Example response
{
  "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
  }
}
The response is scoped to the authenticated merchant and its API-key environment. 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 statusError / meaningWhat to check
401Missing or invalid API key/secret.Confirm the active merchant credentials and send them in the documented headers.
403Merchant 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.
409DUPLICATE_TRANSACTION_ID.Use a unique transaction ID. For a retry after a timeout, reconcile the original request before creating a new transaction.
404Payment not found on the status endpoint.Confirm the transaction ID and that the API credentials use the same environment as the original request.
422One 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.
422GATEWAY_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.
422ENVIRONMENT_MISMATCH: body environment does not match the API credential environment.Use live with a Live API key/secret, or test with Test credentials.
503AUTOPAY_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.
500AUTOPAY_CREATION_FAILED: an unexpected server error prevented mandate creation.Check the transaction ID before retrying and contact TPI Pay support if the problem persists.
502AUTOPAY_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.
Example validation error
{
  "message": "The principal amount field is required.",
  "errors": {
    "principal_amount": [
      "The principal amount field is required."
    ]
  }
}