UPI Setu - Payments - Create TPV API

Reading time — 5 minutes

When it comes to a TPV QR, these are the APIs that are available for a merchant to manage its lifecyle

#Create TPV QR

The merchant generates a payment link. This unique link serves as the gateway for customers to initiate intent transactions via their Third-Party Application Provider (TPAP).

Host	`https://umap.setu.co/api`
Method	`POST`
Path	`/v1/merchants/tpv`
Header	`merchantId` `Authorization`: Bearer <insert_token_here> Generate an access token ↗ `Content-Type`—will be `application/json`
API reference	Create TPV QR ↗

Bank account details passed in the request payload are not stored in plain text to keep them safe. So you would see a combination of encrypted, masked and hashed account numbers in the response payload.

#Error codes

Error code	HTTP code	Description
`invalid-min-amount`	`400`	When both amount and minAmount fields are present in the request payload, the amount value should be greater than minAmount value
`merchant-inactive`	`400`	When the merchant identified by the merchant id passed in the header is inactive (transaction_status = inactive)

{
    "amount": 10000,
    "createdAt": "2023-09-04T12:08:20+0530",
    "expireAfter": 10,
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "merchantReferenceId": "1240689979139556556",
    "merchantVpa": "fastestupi@pineaxis",
    "metadata": "test",
    "minAmount": 100,
    "primaryAccount": {
        "IFSC": "SBIN0000001",
        "accountName": "ram",
        "accountNumber": "1234567890"
    },
    "secondaryAccounts": [
        {
            "IFSC": "SBIN0000001",
            "accountName": "shyam",
            "accountNumber": "1234567890"
        }
    ],
    "transactionNote": "test transaction"
}

Both amount and minAmount fields are optional, these fields when passed in the request change the behavior of how they are rendered on a Payer PSP

When only amount is passed — the amount passed in the request will be displayed on the payment page of the Payer PSP, but customer will not be allowed to choose any amount
When only minAmount is passed - the customer will be allowed to choose the amount to pay, it should be more than the minimum amount
When both amount and minAmount are passed - the amount passed in the request payload is displayed in the payment page of the Payer PSP, and the customer will be allowed to choose the payment amount

#Fetch TPV QR by id

Following the initiation of the transaction, the system retrieves the payment details. This retrieval is based on the resource id, ensuring you have access to transaction information for confirmation and record-keeping.

Host	`https://umap.setu.co/api`
Method	`GET`
Path	`/v1/merchants/tpv/{id}`
Header	`merchantId` `Authorization`: Bearer <insert_token_here> Generate an access token ↗ `Content-Type`—will be `application/json`
API reference	Fetch TPV QR ↗

#Error codes

Error code	HTTP code	Description
`tpv-not-found`	`404`	Failed to fetch tpv by it resource id. Check if the resource id and the merchant id shared in the request URL are the right ones
`merchant-inactive`	`400`	When the merchant identified by the merchant id passed in the header is inactive (transaction_status = inactive)

{
  "amount": 10000,
  "createdAt": "2024-05-17T19:17:32+05:30",
  "expireAfter": 10,
  "id": "1240689979139556556",
  "intentLink": "upi://pay?pa=test-auto-pgruosncak@pineaxis&pn=merchant-4&am=100.00&tr=SU1240659756905923780&tn=sample%20single%20use%20qr&cu=INR&mc=1234",
  "merchantId": "1240689979139556556",
  "merchantVpa": "fastestupi@pineaxis",
  "metadata": {
    "InvoiceNumber": "INV-21-12-009"
  },
  "minAmount": 100,
  "paymentDetails": {
    "customerAccountType": "SAVINGS",
    "customerVpa": "test-auto-tyvmm59i9b@pineaxis",
    "paymentId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "paymentStatus": "success",
    "rrn": "124068997913",
    "txnId": "SETmBZkQOV0M7wyyP1V4PIFhRSzW5eSjmYI"
  },
  "primaryAccount": {
    "IFSC": "SBIN0000001",
    "encryptedAccountName": "5e884898da28047151d0e56f8dc629277",
    "encryptedAccountNumber": "5e884898da28047151d0e56f8dc629277",
    "hashedAccountName": "5e884898da28047151d0e56f8dc629277",
    "hashedAccountNumber": "5e884898da28047151d0e56f8dc629277",
    "maskedAccountName": "R*M*E*S*",
    "maskedAccountNumber": "**** **** **** 7890"
  },
  "refId": "1240689979139556558",
  "referenceId": "1240689979139556556",
  "requestId": "cjqml1f2e5ocq2mesej0",
  "secondaryAccounts": [
  ],
  "shortLink": "upipay.setu.co/Np3KnBCM8Om0",
  "status": "paid",
  "transactionNote": "test transaction"
}

—

–

#Create TPV QR

#Error codes

#Fetch TPV QR by id

#Error codes