SERVER 2 SERVER

S2S UPI Collect

Initiate a UPI Collect payment directly from your server and request approval on the customer’s UPI app.

Supported UPI capabilities

Fetch the UPI flows and payer account types enabled for your account using the Methods API.

Only present UPI Intent, UPI Collect, or a payer account type when the corresponding value returned by the API is true.

STEP 1

Create the order on your server

Create a new FiatPe order for each payment attempt. Amounts use the smallest currency sub-unit: for INR, 5000 represents ₹50.00. Store the returned order ID against your internal order before using it in the S2S payment request.

Open the Create Order API reference

Server request example

Use your FiatPe credentials only from a trusted backend environment.

REQUEST

Curl

curl --request POST \
  --url https://api.fiatpe.com/v1/orders/ \
  --header "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 5000,
    "currency": "INR"
  }'

Response

Store the returned data.id and pass it as the order_id in Step 2.

200 OK

{
  "data": {
    "id": "order_2f40f08f4baa4e5b",
    "amount": 5000,
    "entity": "order",
    "method": null,
    "status": "created",
    "currency": "INR",
    "metadata": {},
    "created_at": 1788148983,
    "return_url": null,
    "amount_paid": 0,
    "bank_details": null,
    "return_method": "POST",
    "amount_pending": 5000
  },
  "message": "order created successfully."
}

STEP 2

Initiate a payment

Send this request from your backend. Generate the Basic authorization value by Base64 encoding api_key:secret_key. Never expose either credential in browser or mobile application code.

REQUEST

Curl

curl --location 'https://api.fiatpe.com/v1/payments/s2s/' \
  --header 'Authorization: Basic <base64(api_key:secret_key)>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "amount": 5000,
    "currency": "INR",
    "contact": "+919898989898",
    "name": "Aftab Hussain",
    "email": "customer@example.com",
    "order_id": "order_75db8a5703ba4d3a",
    "callback_url": "https://api.example.com/webhooks/fiatpe",
    "description": "Test payment",
    "method": "upi",
    "upi": {
      "flow": "collect",
      "vpa": "customer@upi"
    },
    "metadata": {
      "note_key": "value1"
    }
  }'

Request fields

Field	Required	Description
`amount`	Yes	Payment amount in the currency’s smallest sub-unit. For INR, `5000` represents ₹50.00.
`currency`	Yes	Three-letter currency code. Use `INR` for Indian Rupees.
`contact`	Yes	Customer phone number including the country code.
`name`	Yes	Customer’s full name.
`email`	Yes	Customer email address.
`order_id`	Yes	Order ID returned by the Create Order API.
`callback_url`	No	Optional HTTPS endpoint on your server where FiatPe sends asynchronous payment updates.
`description`	No	Description associated with the payment.
`method`	Yes	Set to `upi`.
`upi.flow`	Yes	Set to `collect`.
`upi.vpa`	Yes	Customer’s valid Virtual Payment Address.
`metadata`	No	Merchant-defined key-value data associated with the payment.

Simulate UPI Collect in Sandbox

Scenario	UPI ID (VPA)	Expected result
Success	Any syntactically valid VPA, for example `customer@upi`	The UPI Collect request is simulated as successful.
Failure	`fiatpe@failure`	The UPI Collect request is simulated as failed.

Sandbox only

These simulation rules work only in the FiatPe Sandbox environment. Never use test VPAs to determine payment status in production.

Response

Store the returned payment_id. Use it to track the payment and reconcile the final status through your backend and webhooks.

200 OK

{
  "payment_id": "FIATPEST7LGJ0HOP9H1790703210"
}

Handle the final result

Do not mark the order as paid from the initiation response.
Wait for the customer to approve the collect request in their UPI app.
Confirm the final payment status from your server and process FiatPe webhooks idempotently.
Match the payment ID, order ID, amount, and currency before fulfilment.