TPIPAY API integration
Forward a payment request, redirect the customer to the secure checkout, and verify the resulting transaction.
Copy-paste cURL (Sandbox / Test Mode)
Use these exact headers and payloads in Postman. This matches the project’s sandbox API implementation.
curl --location --request POST 'https://staging.login.tpipay.ai/api/sandbox/payment' \
--header 'X-API-KEY: pk_test_XXXXXXXX' \
--header 'Authorization: Bearer sk_test_XXXXXXXX' \
--header 'Content-Type: application/json' \
--data '{
"amount": 1500.00,
"currency": "INR",
"customer_name": "Raj Sharma",
"customer_phone": "9876543210",
"customer_email": "raj@example.com",
"transaction_id": "ORD-SANDBOX-1001",
"description": "Sandbox payment test",
"success_url": "https://yourdomain.com/payment/success",
"failure_url": "https://yourdomain.com/payment/failure",
"cancel_url": "https://yourdomain.com/payment/cancel",
"webhook_url": "https://yourdomain.com/webhook",
"payment_method": "UPI"
}'
Sandbox status check
curl --location --request GET
'https://staging.login.tpipay.ai/api/sandbox/status/ORD-SANDBOX-1001' \
--header 'X-API-KEY: pk_test_XXXXXXXX' \
--header 'Authorization: sk_test_XXXXXXXX'
Sandbox base URL
Use the sandbox/test environment for merchant API testing. The current application exposes sandbox endpoints under the API prefix.
| Endpoint | Method | Purpose |
|---|---|---|
/api/sandbox/payment |
POST | Create a sandbox payment. |
/api/sandbox/status/{transaction_id} |
GET | Retrieve a sandbox payment status by transaction ID, using the same URL pattern as live. |
Sandbox authentication
The sandbox API authenticates using merchant API credentials generated for the test environment.
| Header | Example | Description |
|---|---|---|
X-API-KEY |
pk_test_XXXXXXXX |
Merchant API key for the sandbox/test environment. |
X-API-SECRET |
sk_test_XXXXXXXX |
Merchant API secret for the sandbox/test environment. Authorization: Bearer <api_secret> is also accepted. |
Authorization |
Bearer sk_test_XXXXXXXX |
Alternative to X-API-SECRET. |
Example request headers
{
"X-API-KEY": "pk_test_XXXXXXXX",
"X-API-SECRET": "sk_test_XXXXXXXX",
"Content-Type": "application/json",
}
Credential generation is handled by the existing merchant API credential service, which stores
api_key and a hashed secret for the selected test environment. The code checks
MerchantApiCredential::where('environment', 'test') and validates the secret using Laravel
Hash.
Create sandbox payment
Creates a sandbox payment record and returns a checkout URL for the sandbox checkout flow.
| Field | Type | Required | Description |
|---|---|---|---|
transaction_id |
string | No | Custom transaction reference. If omitted, the app creates one automatically. |
amount |
numeric | Yes | Amount in rupees, accepted as a decimal; minimum 0.01 and maximum 100000000. |
currency |
string | No | Must be INR. |
customer_name |
string | Yes | Customer name. |
customer_email |
string | No | Valid email. |
customer_phone |
string | Yes | Customer mobile number. |
description |
string | No | Payment description. |
success_url |
string | No | Optional success redirect URL. |
failure_url |
string | No | Optional failure redirect URL. |
cancel_url |
string | No | Optional cancel redirect URL. |
webhook_url |
string | No | Optional webhook callback URL. |
gateway |
string | No | Optional gateway name field. |
idempotency_key |
string | No | |
payment_method |
string | No | Allowed: UPI, CARD, NET_BANKING, EMI,
WALLET, PAY_LATTER.
|
Example request
{
"amount": 1500.00,
"currency": "INR",
"customer_name": "Raj Sharma",
"customer_phone": "9876543210",
"customer_email": "raj@example.com",
"transaction_id": "ORD-SANDBOX-1001",
"description": "Sandbox payment test",
"success_url": "https://yourdomain.com/payment/success",
"failure_url": "https://yourdomain.com/payment/failure",
"webhook_url": "https://yourdomain.com/webhook"
}
Example response
{
"success": true,
"message": "Sandbox payment created successfully.",
"data": {
"payment_id": 123,
"transaction_id": "ORD-SANDBOX-1001",
"amount": "1500.00",
"status": "created",
"environment": "sandbox",
"checkout_url": "https://login.tpipay.ai/sandbox/checkout/abcd1234"
}
}
Sandbox test scenarios
These scenarios are seeded in the project and are used by the sandbox checkout screen and simulator. They are the actual values currently supported by the application.
| Method | Scenario | Result | Inputs |
|---|---|---|---|
UPI |
UPI_SUCCESS |
success |
success@tpipay |
UPI |
UPI_FAILED |
failed |
failure@tpipay |
UPI |
UPI_PENDING |
pending |
pending@tpipay |
CARD |
CARD_SUCCESS |
success |
4111111111111111, expiry 12/30, CVV 123 |
CARD |
CARD_FAILED |
failed |
4000000000000002, expiry 12/30, CVV 123 |
CARD |
CARD_PENDING |
pending |
4000000000009995, expiry 12/30, CVV 123 |
NET_BANKING |
NB_SUCCESS |
success |
Bank TPITEST, username testuser, password test123
|
NET_BANKING |
NB_FAILED |
failed |
Bank TPITEST, username faileduser, password failed123
|
WALLET |
WALLET_SUCCESS |
success |
Wallet TPITESTWALLET, mobile 9999999999, OTP 123456
|
WALLET |
WALLET_FAILED |
failed |
Wallet TPITESTWALLET, mobile 9999999998, OTP 000000
|
EMI |
EMI_SUCCESS |
success |
Card 4111111111111111, tenure 6, CVV 123 |
EMI |
EMI_FAILED |
failed |
Card 4000000000000002, tenure 6, CVV 123 |
PAY_LATTER |
PAY_LATER_SUCCESS |
success |
Provider TPIPAY_LATER, mobile 9999999999, OTP 123456
|
PAY_LATTER |
PAY_LATER_FAILED |
failed |
Provider TPIPAY_LATER, mobile 9999999998, OTP 000000
|
Sandbox status
Retrieve the current sandbox payment state by transaction ID. The URL follows the same pattern as the live status endpoint; use your sandbox API credentials for authentication.
curl --location --request GET 'https://staging.login.tpipay.ai/api/sandbox/status/ORD-SANDBOX-1001' \
--header 'X-API-KEY: your-sandbox-api-key' \
--header 'Authorization: your-sandbox-api-secret'
Example response
{
"success": true,
"message": "Payment status retrieved successfully.",
"data": {
"transaction_id": "ORD-SANDBOX-1001",
"payment_id": 123,
"currency": "INR",
"amount": "1500.00",
"status": "pending",
"payment_method": "UPI",
"paid_at": null,
"environment": "sandbox",
"success_url": "https://yourdomain.com/payment/success",
"failure_url": "https://yourdomain.com/payment/failure",
"cancel_url": "https://yourdomain.com/payment/cancel",
"webhook_url": "https://yourdomain.com/webhook"
}
}
Sandbox callback / webhook
The sandbox simulator dispatches a webhook payload when the status transitions to a terminal state. This is the implemented behavior from the queue jobs and simulator.
| Field | Type | Description |
|---|---|---|
event |
string | payment.updated |
payment_id |
integer | Local payment ID. |
transaction_id |
string | Merchant transaction ID. |
amount |
string | Amount formatted to 2 decimal places. |
currency |
string | Defaults to INR. |
status |
string | Final status: success, failed, or cancelled. |
environment |
string | sandbox |
payment_method |
string | Payment method selected in the test scenario. |
Example webhook payload
{
"event": "payment.updated",
"payment_id": 123,
"transaction_id": "ORD-SANDBOX-1001",
"amount": "1500.00",
"currency": "INR",
"status": "success",
"environment": "sandbox",
"payment_method": "UPI"
}
Sandbox error handling
The sandbox API returns structured JSON error payloads when authentication fails, credentials are missing, the merchant is invalid, or validation fails.
| Code | Meaning | Example |
|---|---|---|
INVALID_SANDBOX_CREDENTIALS |
Authentication failed or invalid credentials. | { "success": false, "message": "Sandbox authentication failed.", "error_code":
"INVALID_SANDBOX_CREDENTIALS" } |
SANDBOX_CREDENTIALS_NOT_CONFIGURED |
No active sandbox credential exists. | { "success": false, "message": "Sandbox credentials are not configured.",
"error_code": "SANDBOX_CREDENTIALS_NOT_CONFIGURED" } |
SANDBOX_CREDENTIALS_INACTIVE |
Credential exists but disabled. | { "success": false, "message": "Sandbox credentials are inactive.", "error_code":
"SANDBOX_CREDENTIALS_INACTIVE" } |
PAYMENT_NOT_FOUND |
Requested checkout token or transaction was not found. | { "success": false, "message": "Payment not found.", "error_code": "PAYMENT_NOT_FOUND"
} |
TRANSACTION_ID_ALREADY_EXISTS |
Duplicate transaction ID. | { "success": false, "message": "Transaction ID already exists.", "error_code":
"TRANSACTION_ID_ALREADY_EXISTS" } |
