API Reference

API Reference v1.6

SprintPay Payments API

Full REST API reference for the SprintPay payments platform — customers, orders, payments, refunds, payouts, webhooks and more.

Base URL (Production)

https://api.sprintpay.io

Content-Type

application/json

Authentication

All API requests require two header credentials. These are applied to every endpoint without exception.

Header	Type	Required	Description
X-API-KEY	String	Required	Your API key for authentication.
X-API-SECRET	String	Required	Your API secret for authentication. Also used as the HMAC-SHA256 signing key.

Example Headers

X-API-KEY: your_api_key_here
X-API-SECRET: your_api_secret_here
Content-Type: application/json

POST/customer/create

Create Customer

Creates a new customer profile. Returns the details of the newly created customer, including the system-assigned customer ID.

Notes

• merchantCustomerId must be unique per customer.

Request Body

Field	Type	Required	Description
firstName	String	Required	Customer's first name.
lastName	String	Required	Customer's last name.
customerEmail	String	Required	Customer's email address.
countryCode	String	Required	ISO 2-letter country code (e.g. IN, US).
residenceCountry	String	Optional	ISO 2-letter residence country code.
birthDate	String	Required	Date of birth in YYYY-MM-DD format.
merchantCustomerId	String	Required	Your unique identifier for this customer. Must be unique.
phoneNo	String	Required	Customer's phone number (min 10 digits).
address1	String	Optional	Primary address line.
address2	String	Optional	Secondary address line.
city	String	Optional	City.
stateCode	String	Optional	State code (2 characters).
zipCode	String	Optional	Postal or ZIP code.

Example RequestJSON

{
  "data": {
    "firstName": "Sridhar",
    "lastName": "Sethuraman",
    "customerEmail": "sridhar@example.com",
    "countryCode": "US",
    "residenceCountry": "US",
    "birthDate": "1985-06-15",
    "merchantCustomerId": "CUST-001",
    "phoneNo": "14155552671",
    "address1": "123 Market Street",
    "city": "San Francisco",
    "stateCode": "CA",
    "zipCode": "94105"
  }
}

Success Response200 OK

{
  "data": {
    "customerId": "dcc5c2a8-1151-4f39-921a-8ce6058e64ab",
    "firstName": "Sridhar",
    "lastName": "Sethuraman",
    "customerEmail": "sridhar@example.com",
    "phoneNo": "14155552671",
    "countryCode": "US",
    "merchantCustomerId": "CUST-001"
  },
  "errorMessage": "Success",
  "errorData": null
}

POST/customer/update-address

Update Customer Address

Updates the address fields (address1, address2, city, stateCode, zipCode) for an existing customer.

Request Body

Field	Type	Required	Description
customerId	String	Required	The system-issued customer ID.
address1	String	Required	Primary address line.
address2	String	Required	Secondary address line.
city	String	Required	City.
stateCode	String	Required	State code (2 characters).
zipCode	String	Required	Postal or ZIP code.

Success Response200 OK

{
  "data": null,
  "errorMessage": "Success",
  "errorData": null
}

GET/customer/{customerId}

Get Customer

Fetches the complete details of a specific customer by their system-issued ID.

Path Parameters

Field	Type	Required	Description
customerId	String	Required	Unique system ID of the customer.

Success Response200 OK

{
  "data": {
    "customerId": "dcc5c2a8-1151-4f39-921a-8ce6058e64ab",
    "firstName": "Sridhar",
    "lastName": "Sethuraman",
    "customerEmail": "sridhar@example.com",
    "phoneNo": "14155552671",
    "countryCode": "US",
    "residenceCountry": "US",
    "birthDate": "1985-06-15",
    "merchantCustomerId": "CUST-001",
    "address1": "123 Market Street",
    "city": "San Francisco",
    "stateCode": "CA",
    "zipCode": "94105"
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/customer

List Customers

Fetches a paginated list of customers.

Query Parameters

Field	Type	Required	Description
page	Integer	Required	Page number to retrieve (starts at 1).
size	Integer	Required	Number of records to return per page.

Success Response200 OK

{
  "data": {
    "totalPages": 1,
    "totalElements": 7,
    "size": 50,
    "customerList": [
      {
        "customerId": "51a8561f-77e4-458d-be43-171b910297cc",
        "firstName": "Sridhar",
        "lastName": "Sethuraman",
        "customerEmail": "sridhar@example.com",
        "phoneNo": "14155552671",
        "countryCode": "US",
        "merchantCustomerId": "CUST-001"
      }
    ]
  },
  "errorMessage": "Success",
  "errorData": null
}

POST/api/order

Create Order

Creates a new order. Returns a checkout URL and order ID. The customer is redirected to the checkout URL to complete payment.

Notes

• merchantRef must be unique per order.
• All monetary fields (amount, discountValue, shippingValue, taxValue) must be positive numbers.

Request Body

Field	Type	Required	Description
amount	Decimal	Required	Total order amount.
currency	String	Required	Currency code (e.g. "INR", "USD").
merchantRef	String	Required	Your unique reference/order ID.
discountValue	Decimal	Optional	Discount applied to the order.
shippingValue	Decimal	Optional	Shipping charges.
taxValue	Decimal	Optional	Tax applied to the order.
notes	String	Required	Customer-facing notes.
callbackUrl	String	Optional	URL to redirect customer after transaction. If omitted, stays on our page.
clientIp	String	Required	IP address of the client initiating the request.
customerId	String	Required	Customer ID from Create Customer.

Example RequestJSON

{
  "amount": 1200.50,
  "currency": "INR",
  "merchantRef": "ORD-20250609-001",
  "discountValue": 100.00,
  "shippingValue": 50.00,
  "taxValue": 18.00,
  "notes": "Order for SprintPay demo",
  "callbackUrl": "https://yoursite.com/payment/callback",
  "clientIp": "192.168.1.1",
  "customerId": "7e5b6ac5-27c2-4710-b8b8-5a17a361a5b9"
}

Success Response200 OK

{
  "data": {
    "orderId": "ac7859aa-8967-4551-bab0-1f03d01c5af4",
    "checkoutUrl": "https://api.sprintpay.io/order/payment-checkout/ac7859aa-8967-4551-bab0-1f03d01c5af4",
    "orderStatus": "PENDING"
  },
  "errorMessage": "Success",
  "errorData": null
}

Error Response400 / 404

{
  "data": null,
  "errorMessage": "Failed",
  "errorData": [
    {
      "errorCode": 3014,
      "fieldName": "currency",
      "errorDescription": "Currency is required when Order ID is not provided"
    }
  ]
}

GET/api/payment/payment-methods

Get Available Payment Methods

Returns available payment methods based on the transaction amount and currency.

Query Parameters

Field	Type	Required	Description
amount	Decimal	Required	Transaction amount used to filter eligible methods.
currency	String	Required	Currency code (e.g. "INR").

Success Response200 OK

{
  "data": {
    "paymentMethods": [
      {
        "value": "UPI",
        "displayValue": "UPI",
        "minAmount": 50.00,
        "maxAmount": 100000.00
      },
      {
        "value": "UPI_SEAMLESS",
        "displayValue": "UPI Seamless",
        "minAmount": 50.00,
        "maxAmount": 100000.00
      },
      {
        "value": "CARD",
        "displayValue": "Card",
        "minAmount": 1.00,
        "maxAmount": 50000.00
      }
    ]
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/order

List Orders

Fetches orders filtered by date range and status.

Query Parameters

Field	Type	Required	Description
startDate	String	Required	Start date in YYYY-MM-DD format.
endDate	String	Required	End date in YYYY-MM-DD format.
status	String	Required	PENDING · COMPLETED · FAILED · REFUNDED · CANCELED · EXPIRED · PARTIALLY_REFUNDED

Success Response200 OK

{
  "data": {
    "totalPages": 1,
    "totalElements": 2,
    "size": 10,
    "orderList": [
      {
        "orderId": "46eed875-82ba-42b1-9ac7-bd0e394ca69a",
        "amount": 1200.50,
        "currency": "INR",
        "orderStatus": "PENDING",
        "merchantOrderRef": "ORD-20250609-001",
        "customerName": "Sridhar Sethuraman",
        "createdOn": "2025-06-09T10:00:00",
        "expiredAt": "2025-06-09T10:20:00"
      }
    ]
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/order/{orderId}

Get Order Details

Fetches the complete details of a specific order.

Path Parameters

Field	Type	Required	Description
orderId	String	Required	Unique ID of the order.

Success Response200 OK

{
  "data": {
    "orderId": "f3b6fe94-336e-441c-80ea-a26fcfd4dd46",
    "amount": 500.00,
    "currency": "INR",
    "expiredAt": "2025-04-30T23:59:59",
    "discountValue": 50,
    "taxValue": 18,
    "shippingCharges": 20,
    "merchantOrderRef": "ORD-20250430-1234",
    "customerName": "Sridhar Sethuraman",
    "orderStatus": "PENDING",
    "createdOn": "2025-04-30T10:00:00",
    "items": [
      { "itemId": "item-1234", "name": "Product 1", "quantity": 2, "price": 250.00 }
    ]
  },
  "errorMessage": "Success",
  "errorData": null
}

Error Response400 / 404

{
  "data": null,
  "errorMessage": "Failed",
  "errorData": [
    { "errorCode": 3014, "fieldName": null, "errorDescription": "Order not found" }
  ]
}

GET/api/order/cancel/{orderId}

Cancel Order

Cancels an existing order. Sets orderStatus to CANCELED, checkoutUrl becomes null, and the order can no longer be used for payment.

Notes

• Completed or expired orders cannot be cancelled (error 5014).

Path Parameters

Field	Type	Required	Description
orderId	String	Required	Unique ID of the order to cancel.

Success Response200 OK

{
  "data": {
    "orderId": "d3369d56-49d1-443a-a9c6-f471d43e19c4",
    "checkoutUrl": null,
    "orderStatus": "CANCELED"
  },
  "errorMessage": "Success",
  "errorData": null
}

POST/api/payment

Initiate Payment — UPI

Initiates a UPI payment. Can create a new payment directly or use an existing orderId. Returns a redirectUrl for the customer to complete payment.

Notes

• If orderId is provided, only paymentMethod is required.
• If orderId is not provided, all payment details are mandatory.
• For UPI_SEAMLESS: the redirectUrl contains AES-256-CBC encrypted data — decrypt to get the QR/UPI link.
• Payment status starts as PENDING until completed.

Request Body

Field	Type	Required	Description
amount	Decimal	Required	Amount to pay.
currency	String	Required	Currency code (e.g. "INR").
merchantRef	String	Required	Your unique reference ID.
notes	String	Required	Payment notes.
paymentMethod	String	Required	"UPI" or "UPI_SEAMLESS". For UPI_SEAMLESS the redirectUrl is encrypted.
callbackUrl	String	Optional	Redirect URL after transaction.
clientIp	String	Required	IP address of the initiating client.
customerId	String	Required	System-issued customer ID.

Request Body — With orderId (minimal)

Field	Type	Required	Description
orderId	String	Required	Existing order ID.
paymentMethod	String	Required	"UPI" or "UPI_SEAMLESS".

Example RequestJSON

{
  "amount": 220,
  "paymentMethod": "UPI",
  "currency": "INR",
  "merchantRef": "PAY-20250609-001",
  "discountValue": 0,
  "shippingValue": 0,
  "taxValue": 0,
  "clientIp": "192.168.1.1",
  "callbackUrl": "https://yoursite.com/payment/callback",
  "notes": "Invoice #INV-001",
  "customerId": "5bfa8217-1a0c-473b-886f-3935de8fbf5f"
}

Success Response200 OK

{
  "data": {
    "paymentId": "6d66761c-f3d9-465e-a127-b30cbeddbbf3",
    "isRedirectRequired": true,
    "redirectUrl": "https://api.sprintpay.io/payment/6d66761c-f3d9-465e-a127-b30cbeddbbf3",
    "paymentMethod": "UPI",
    "status": "PENDING",
    "merchantRef": "PAY-20250609-001"
  },
  "errorMessage": "Success",
  "errorData": null
}

Error Response400 / 404

{
  "data": null,
  "errorMessage": "Failed",
  "errorData": [
    { "errorCodes": 3022, "fieldName": "notes", "errorDescription": "Notes is required" }
  ]
}

POST/api/payment

Initiate Payment — Card

Initiates a card payment. Same endpoint as UPI payment — pass paymentMethod: "CARD" and include the cardData object.

Notes

• Card number must be 16 digits.
• Expiry date must be in MM/YY format.
• CVV must be exactly 3 digits.

Request Body

Field	Type	Required	Description
amount	Decimal	Required	Amount to pay.
currency	String	Required	Currency code (e.g. "EUR", "USD").
merchantRef	String	Required	Your unique reference ID.
notes	String	Required	Payment notes.
paymentMethod	String	Required	"CARD"
callbackUrl	String	Optional	Redirect URL after transaction.
clientIp	String	Required	IP address of the initiating client.
customerId	String	Required	System-issued customer ID.
cardData.cardNumber	String	Required	16-digit card number.
cardData.cardholderName	String	Required	Name on the card.
cardData.expiryDate	String	Required	Card expiry in MM/YY format.
cardData.cvv	String	Required	3-digit CVV security code.

Example RequestJSON

{
  "amount": 220,
  "paymentMethod": "CARD",
  "currency": "EUR",
  "merchantRef": "PAY-20250609-002",
  "notes": "Invoice #INV-002",
  "clientIp": "192.168.1.1",
  "customerId": "5bfa8217-1a0c-473b-886f-3935de8fbf5f",
  "cardData": {
    "cardNumber": "4444333322221111",
    "cardholderName": "Sridhar Sethuraman",
    "expiryDate": "08/29",
    "cvv": "345"
  }
}

Success Response200 OK

{
  "data": {
    "paymentId": "ea5b0a18-56be-4c2d-82c7-0937921e8aeb",
    "isRedirectRequired": true,
    "redirectUrl": "https://api.sprintpay.io/payment/ea5b0a18-56be-4c2d-82c7-0937921e8aeb",
    "paymentMethod": "CARD",
    "status": "PENDING",
    "merchantRef": "PAY-20250609-002"
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/transaction

Get Transaction List

Returns a paginated list of transactions. All parameters are optional — if none provided, all transactions are returned with default pagination.

Notes

• transactionStatus can be: PENDING, COMPLETED, FAILED, REFUNDED, CANCELLED, EXPIRED, PARTIALLY_REFUNDED.
• settlementStatus will be null until the transaction is settled.

Query Parameters

Field	Type	Required	Description
page	Integer	Optional	Page number (default: 1).
size	Integer	Optional	Items per page (default: 10).
currency	String	Optional	Currency filter (e.g. "INR").
startDate	Date	Optional	Start date filter (YYYY-MM-DD).
endDate	Date	Optional	End date filter (YYYY-MM-DD).

Success Response200 OK

{
  "data": {
    "totalPages": 3,
    "totalElements": 21,
    "size": 10,
    "transactionList": [
      {
        "amount": 220,
        "currency": "INR",
        "paymentMethod": "UPI",
        "paymentId": "3ba28f88-cd15-42b3-9b25-ca67541017c4",
        "transactionDate": "2025-06-09T10:17:57",
        "txCharge": 0,
        "txChargeType": "FIXED_RATE",
        "settlementStatus": null,
        "transactionStatus": "COMPLETED",
        "customerName": "Sridhar Sethuraman"
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "Success",
  "errorData": null
}

GET/api/transaction/{paymentId}

Get Transaction Detail

Fetches details of a single transaction. If the transaction is linked to an order, orderDto will contain order details; otherwise it is null.

Path Parameters

Field	Type	Required	Description
paymentId	String	Required	Unique identifier of the transaction.

Success Response200 OK

{
  "data": {
    "amount": 222,
    "currency": "INR",
    "paymentMethod": "UPI",
    "clientRef": "82f330ca-fb80-4420-838a-f5b54a4de06f",
    "transactionDate": "2025-06-09T14:56:10",
    "txCharge": 22.2,
    "txChargeType": "PERCENTAGE",
    "settlementStatus": "PENDING",
    "transactionStatus": "COMPLETED",
    "orderDto": null
  },
  "errorCode": 0,
  "errorMessage": "Success",
  "errorData": null
}

GET/api/payment/cancel/{paymentId}

Cancel Payment

Cancels an existing payment. Only PENDING payments can be cancelled.

Path Parameters

Field	Type	Required	Description
paymentId	UUID	Required	Unique identifier of the payment.

Success Response200 OK

{
  "data": {
    "transactionStatus": "CANCELLED",
    "paymentId": "5e262225-cd12-4202-a6ff-a3087546a307",
    "merchantOrderRef": "ORD-20250609-001"
  },
  "errorMessage": "Success",
  "errorData": null
}

POST/api/refund

Create Refund

Initiates a refund for a completed payment. refundStatus starts as PENDING.

Notes

• paymentId must reference a successfully completed payment.
• Refund amount cannot exceed the available refundable balance.

Request Body

Field	Type	Required	Description
amount	Decimal	Required	Amount to refund.
paymentId	UUID	Required	Payment ID for which refund is requested.
notes	String	Optional	Additional information about the refund.
merchantRef	String	Required	Your reference ID.
reason	String	Required	PRODUCT_DEFECT · WRONG_ITEM_SHIPPED · LATE_DELIVERY · CUSTOMER_CHANGE_MIND · DUPLICATE_ORDER · CANCELLED_ORDER · PRICE_MISMATCH · RETURNED_DAMAGED · UNSATISFIED_WITH_PRODUCT · OTHER

Success Response200 OK

{
  "data": {
    "refundId": "210b5687-9d7f-4b37-b7cc-38fedf7f6457",
    "merchantRef": "REF-001",
    "refundStatus": "PENDING"
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/refund

List Refunds

Retrieves a paginated list of all refunds for the merchant.

Query Parameters

Field	Type	Required	Description
page	Integer	Optional	Page number.
size	Integer	Optional	Items per page.
currency	String	Optional	Currency filter.

Success Response200 OK

{
  "data": {
    "totalPages": 1,
    "totalElements": 2,
    "size": 10,
    "refundList": [
      {
        "amount": 5,
        "currency": "INR",
        "paymentId": "434f0bcd-3ea4-4c55-84a1-2770fbed3b2c",
        "refundId": "25ff3058-31bd-42ba-96a5-deb74347561b",
        "merchantOrderRef": "ORD-001",
        "reason": "OTHER",
        "refundStatus": "REFUNDED"
      }
    ]
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/refund/{refundId}

Get Refund Details

Retrieves detailed information about a specific refund.

Path Parameters

Field	Type	Required	Description
refundId	String	Required	Unique ID of the refund.

Success Response200 OK

{
  "data": {
    "amount": 5,
    "currency": "INR",
    "paymentId": "434f0bcd-3ea4-4c55-84a1-2770fbed3b2c",
    "refundId": "25ff3058-31bd-42ba-96a5-deb74347561b",
    "merchantOrderRef": "ORD-001",
    "notes": "Product returned",
    "reason": "OTHER",
    "refundStatus": "REFUNDED"
  },
  "errorMessage": "Success",
  "errorData": null
}

POST/api/beneficiaries

Add Beneficiary

Adds a bank account beneficiary for payouts.

Request Body

Field	Type	Required	Description
accountNumberType	String	Required	Account type (e.g. "ACCOUNT_NUMBER").
accountNumber	String	Required	Bank account number (6–20 characters, alphanumeric only).
routingType	String	Required	Routing type (e.g. "IFSC").
routingCode	String	Required	11-character routing/IFSC code.
firstName	String	Required	Account holder first name.
lastName	String	Required	Account holder last name.
email	String	Required	Valid email address for reference.
phone	String	Required	Valid phone number for reference.
bankName	String	Required	Name of the bank.

Example RequestJSON

{
  "accountNumberType": "ACCOUNT_NUMBER",
  "accountNumber": "123456789012",
  "routingType": "IFSC",
  "routingCode": "SBIN0000123",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "1234567890",
  "bankName": "State Bank of India"
}

Success Response200 OK

{
  "data": {
    "id": "d7ff29e9-2a22-4ed0-bf16-ee11308428c6"
  },
  "errorMessage": "Success",
  "errorData": null
}

POST/api/beneficiaries/{id}

Update Beneficiary

Updates an existing beneficiary's contact details.

Path Parameters

Field	Type	Required	Description
id	String	Required	Unique ID of the beneficiary.

Request Body

Field	Type	Required	Description
firstName	String	Required	Updated first name.
lastName	String	Required	Updated last name.
email	String	Required	Updated email address.
phone	String	Required	Updated phone number.
bankName	String	Required	Updated bank name.

Success Response200 OK

{
  "data": { "id": "d7ff29e9-2a22-4ed0-bf16-ee11308428c6" },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/beneficiaries

List Beneficiaries

Fetches a list of beneficiaries within a date range.

Query Parameters

Field	Type	Required	Description
startDate	String	Required	Start date (YYYY-MM-DD).
endDate	String	Required	End date (YYYY-MM-DD).

Success Response200 OK

{
  "data": {
    "totalPages": 1,
    "totalElements": 4,
    "size": 10,
    "beneficiaryList": [
      {
        "id": "1842e3a9-42e2-49b6-b146-c694a5e92b6d",
        "accountNumberType": "ACCOUNT_NUMBER",
        "accountNumber": "123456789012",
        "routingType": "IFSC",
        "routingCode": "SBIN0000123",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "1234567890",
        "bankName": "State Bank of India"
      }
    ]
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/beneficiaries/{id}

Get Beneficiary

Fetches complete details of a specific beneficiary.

Path Parameters

Field	Type	Required	Description
id	String	Required	Unique ID of the beneficiary.

Success Response200 OK

{
  "data": {
    "id": "d7ff29e9-2a22-4ed0-bf16-ee11308428c6",
    "accountNumberType": "ACCOUNT_NUMBER",
    "accountNumber": "123455674879012",
    "routingType": "IFSC",
    "routingCode": "SBIN0000123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "1234567890",
    "bankName": "State Bank of India"
  },
  "errorMessage": "Success",
  "errorData": null
}

POST/api/payout

Initiate Payout

Initiates a new payout to a beneficiary using their beneficiaryId.

Request Body

Field	Type	Required	Description
amount	Decimal	Required	Amount to pay out.
currency	String	Required	Currency code (e.g. "INR").
countryCode	String	Required	ISO 2-letter country code.
notes	String	Required	Payout notes/description.
payoutMethod	String	Required	Payment method (e.g. "NET_BANKING").
beneficiaryId	String	Required	Beneficiary ID returned from Add Beneficiary.

Example RequestJSON

{
  "amount": 100.50,
  "currency": "INR",
  "countryCode": "IN",
  "notes": "Payment for invoice #12345",
  "payoutMethod": "NET_BANKING",
  "beneficiaryId": "d7ff29e9-2a22-4ed0-bf16-ee11308428c6"
}

Success Response200 OK

{
  "data": {
    "payoutId": "01b35954-556e-4988-8a37-c721df365f08",
    "payoutStatus": "PENDING",
    "merchantRef": "49867677675"
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/payout

List Payouts

Fetches a list of payouts within a date range.

Query Parameters

Field	Type	Required	Description
startDate	String	Required	Start date (YYYY-MM-DD).
endDate	String	Required	End date (YYYY-MM-DD).

Success Response200 OK

{
  "data": {
    "totalPages": 1,
    "totalElements": 3,
    "size": 10,
    "payoutList": [
      {
        "payoutId": "7aae73cd-3837-4cc0-8ca2-a53127251f0c",
        "merchantRef": "qwertpxsy",
        "currency": "INR",
        "countryCode": "IN",
        "amount": 56.50,
        "notes": "Payment for invoice #12345",
        "status": "PENDING",
        "createdOn": "2025-05-29T10:37:38"
      }
    ]
  },
  "errorMessage": "Success",
  "errorData": null
}

GET/api/payout/{payoutId}

Get Payout

Fetches complete details of a specific payout.

Path Parameters

Field	Type	Required	Description
payoutId	String	Required	Unique ID of the payout.

Success Response200 OK

{
  "data": {
    "payoutId": "a0ab1270-e7a0-41e7-bc88-2bfafac60f96",
    "merchantRef": "4986777675",
    "currency": "INR",
    "countryCode": "IN",
    "amount": 51.50,
    "notes": "Payment for invoice #12345",
    "status": "PENDING",
    "createdOn": "2025-05-29T10:38:56"
  },
  "errorMessage": "Success",
  "errorData": null
}

Webhooks

SprintPay sends signed webhook payloads to your configured endpoint URL when key payment events occur. Your endpoint must return HTTP 200 — any other status marks the webhook as failed.

Event	webhookType	Status	Description
Payment Success	PAYMENT	COMPLETED	Payment completed successfully.
Payment Cancelled	PAYMENT	CANCELLED	Payment was cancelled.
Payment Expired	PAYMENT	EXPIRED	Payment link timed out without completion.
Refund Success	REFUND	COMPLETED	Refund processed successfully.
Refund Failed	REFUND	FAILED	Refund attempt failed.
Payout Success	PAYOUT	COMPLETED	Payout to beneficiary completed.
Payout Cancelled	PAYOUT	CANCELLED	Payout was cancelled.
Payout Failed	PAYOUT	FAILED	Payout processing failed.

Webhook Payload Structure

{
  "eventType": "COMPLETED",
  "webhookType": "PAYMENT",
  "requestPayload": "{"transactionDate":"2025-06-09T17:39:20","amount":300.0000,"currency":"INR","paymentMethod":"UPI","clientRef":"abc123","merchantRef":"ORD-001","status":"COMPLETED"}"
}

Important

The requestPayload field is a JSON-encoded string. Parse it after receiving the webhook. Always verify the signature before processing.

Signature Verification

SprintPay signs both callbacks and webhooks using your X-API-SECRET. Always verify signatures to prevent spoofed payloads.

Callback Signature

When a payment completes and redirects to your callbackUrl, query parameters will include a signature field.

1. Collect fields: amount, currency, merchant_ref, payment_id, payment_method, status

2. Sort alphabetically by field name, take the values only.

3. Concatenate values with & as delimiter.

4. Hash the string using HMAC-SHA256 with your X-API-SECRET.

5. Compare to the received signature parameter (timing-safe comparison).

Signature Construction Example

// Fields sorted alphabetically by name:
// amount=190.00, currency=INR, merchant_ref=starbucksPay3,
// payment_id=a6e5fb2b-f51a-4adb-ae52-64080198c46d,
// payment_method=UPI, status=COMPLETED

const string = "190.00&INR&starbucksPay3&a6e5fb2b-f51a-4adb-ae52-64080198c46d&UPI&COMPLETED";
const signature = HMAC_SHA256(string, X_API_SECRET);

Webhook Signature

When a webhook fires, the signature is delivered in the HTTP headers.

1. Read the raw request body — do not parse, re-serialize, or modify it.

2. Hash the raw body using HMAC-SHA256 with your X-API-SECRET.

3. Compare to the Signature HTTP header (timing-safe comparison).

Ensure UTF-8 encoding when generating the hash.

AES Decryption (UPI_SEAMLESS)

When using UPI_SEAMLESS, the redirectUrl contains AES-encrypted data to retrieve the QR/UPI link.

Algorithm: AES · Key Size: 256-bit · Mode: CBC · Padding: PKCS5

Key: uppercase(X-API-SECRET), first 32 characters

IV: first 16 characters of the uppercase secret

Error Codes

All API responses include errorMessage and errorData. On failure, errorData is an array with errorCode, fieldName, and errorDescription.

Code	Message	Description
2000	Missing required header parameters	Required headers (X-API-KEY or X-API-SECRET) are missing.
3000	Data type mismatch	The provided data type does not match the expected type.
3001	Validation Error	General validation error in request fields.
3002	Invalid Format	Input format does not match the expected pattern.
3003	Missing required fields	Mandatory fields are missing.
3004	Amount must be greater than 1	The amount must be greater than 1.
3005	Amount exceeds maximum limit	Amount exceeds the maximum for the selected payment method.
3007	Maximum 36 characters required	Merchant reference must not exceed 36 characters.
3008	Amount is required	The amount field is mandatory.
3009	Payment ID is required	Payment ID must be provided.
3010	Merchant Ref is required	Merchant reference is required.
3012	Insufficient Funds	Account has insufficient funds.
3014	Currency is required	Currency must be provided when Order ID is not given.
3015	Currency must be ISO 3-letter code	Currency must follow ISO three-letter standard.
3019	Invalid email format	Email format is incorrect.
3021	Invalid phone number format	Phone number is not in valid format.
3022	Notes is required	Notes field must not be empty.
3023	Invalid callback URL	Callback URL must start with http:// or https://.
3032	Payment Method is required	Payment method selection is mandatory.
3033	Card data is required	Card data must be provided for card-based transactions.
3035	Card number must be 16 digits	Card number must have exactly 16 digits.
3038	Expiry date must be in MM/YY format	Card expiry date must be formatted as MM/YY.
3040	CVV must be 3 digits	CVV must be exactly 3 digits.
3053	Refund amount must equal deposit amount	Refund amount must equal the completed transaction amount.
3068	Amount below minimum	Amount is below the minimum for the selected payment method.
3070	Daily limit exceeded	Completed transactions total exceeds daily limit.
3071	Weekly limit exceeded	Completed transactions total exceeds weekly limit.
3072	Monthly limit exceeded	Completed transactions total exceeds monthly limit.
4001	Merchant authentication failed	Credentials are invalid or missing.
4002	Merchant configuration pending	Payment provider configuration is pending.
5000	Payment order not found	The payment order could not be found.
5002	Unsupported Payment method	Selected payment method is not supported.
5003	Payment not found	The requested payment could not be found.
5004	Payment already completed	Payment has already been made for this order.
5007	Duplicate merchant reference	Merchant reference already used in a previous order.
5009	Order is already completed	No further action allowed on completed orders.
5010	Duplicate transaction	Duplicate transaction with same merchant reference.
5011	Refund exceeds transaction amount	Refund cannot exceed the transaction amount.
5013	Refund already completed	Payment refund has already been processed.
5014	Completed/Expired orders cannot be cancelled	Cannot cancel completed or expired orders.
5018	Customer already exists	A customer with this merchantCustomerId already exists.
5020	Customer not found	No customer found with the given ID.
5022	Beneficiary not found	No beneficiary found with the provided ID.
5023	Payout not found	No payout found with the provided ID.
5024	Account number already exists	A beneficiary with this account number already exists.
5029	Transaction Declined	Transaction was declined by the bank.
5030	Transaction Failed	Unknown exception during transaction or bank server issue.
5031	Payout Declined	Payout was declined by the bank.
5033	Refund Declined	Refund was declined by the bank.
5035	Refund only for completed transactions	Only completed transactions can be refunded.
8000	Signature verification failed	Signature does not match. Payload may have been altered.

SprintPay Payments API v1.6 · Developer Hub · Contact Support