SERVER 2 SERVER

S2S Wallet

Initiate wallet payments from your server using a supported wallet provider.

Supported wallets

Fetch the wallet providers available to your account using the Methods API.

The wallet object contains only wallets enabled for your account. Display the returned wallet name and submit its corresponding object key as the wallet code.

Open the Methods API guide

Test wallets by response flow

Use these wallet codes in the FiatPe test environment to validate HTML Form and Redirect handling.

Test flow	Wallet	Wallet code	Expected action
HTML form	Airtel Money	`AIRTELMONEY`	`html_form`
Redirect	PayZapp	`PAYZAPP`	`redirect`

Test every response flow in UAT before going live.

Your integration must successfully handle Redirect and HTML Form flows in the UAT environment. The flow returned for a transaction can vary based on the configured TID, acquiring bank, issuing bank, payment network, payment method, and other transaction parameters.

Do not hardcode a flow for a card, bank, wallet, or PayLater provider. Always inspect the returned next[].action value and process redirect or html_form as instructed by the API response.

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 wallet payment

Send the payment request from your backend with the wallet selected by the customer. Generate the Basic authorization value by Base64 encoding api_key:secret_key.

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",
    "return_url": "https://example.com/payment/return",
    "callback_url": "https://api.example.com/webhooks/fiatpe",
    "description": "Test payment",
    "method": "wallet",
    "provider": "AIRTELMONEY",
    "metadata": {
      "note_key": "value1"
    }
  }'

Request fields

Field	Required	Description
`amount`	Yes	Payment amount in the currency’s smallest sub-unit.
`currency`	Yes	Three-letter currency code, such as `INR`.
`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 in Step 1.
`return_url`	Yes	HTTPS URL used after wallet authorisation completes.
`callback_url`	No	Optional HTTPS endpoint on your server where FiatPe sends asynchronous payment updates.
`method`	Yes	Set to `wallet`.
`provider`	Yes	FiatPe wallet provider code selected by the customer, for example `AIRTELMONEY` or `PAYZAPP`.
`metadata`	No	Merchant-defined key-value data associated with the payment.

Response actions

HTML form flow

When next[0].action is html_form, render the returned html_content as a full HTML document in the customer’s browser. The included form continues the customer to the selected wallet’s authorisation flow.

200 OK

{
  "payment_id": "FIATPEST5YW9DBBT041790704898",
  "next": [
    {
      "action": "html_form",
      "html_content": "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <title>Redirecting | FiatPe</title>\n  <script src=\"https://cdnjs.cloudflare.com/ajax/libs/lottie-web/5.12.2/lottie.min.js\"></script>\n</head>\n<body>\n  <div class=\"redirect-container\">\n    <div id=\"lottie-loader\"></div>\n    <h1>Redirecting...</h1>\n    <p>Please wait while we redirect you securely. Do not close this window.</p>\n    <form id=\"payment-form\" method=\"GET\"\n      action=\"https://api.fiatpe.com/v1/payments/FIATPEST5YW9DBBT041790704898/authentication/\"\n      hidden>\n      <input type=\"hidden\" name=\"paymentMode\" value=\"WALLET\">\n      <input type=\"hidden\" name=\"walletCode\" value=\"AIRTELMONEY\">\n    </form>\n    <noscript>\n      <button type=\"submit\" form=\"payment-form\">Continue to payment</button>\n    </noscript>\n  </div>\n  <script>\n    if (window.lottie) {\n      lottie.loadAnimation({\n        container: document.getElementById(\"lottie-loader\"),\n        renderer: \"svg\",\n        loop: true,\n        autoplay: true,\n        path: \"https://bucket.fiatpe.com/static/animation/lottie/fiatpe_pg_processing_loader.json\"\n      });\n    }\n    window.setTimeout(function () {\n      document.getElementById(\"payment-form\").submit();\n    }, 1000);\n  </script>\n</body>\n</html>"
    }
  ]
}

Redirect flow

Some wallets return next[0].action as redirect. The following PAYZAPP example demonstrates this response flow.

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",
    "return_url": "https://example.com/payment/return",
    "callback_url": "https://api.example.com/webhooks/fiatpe",
    "description": "Test payment",
    "method": "wallet",
    "provider": "PAYZAPP",
    "metadata": {
      "note_key": "value1"
    }
  }'

200 OK

{
  "payment_id": "FIATPESTDS7GILWFCO1790705098",
  "next": [
    {
      "action": "redirect",
      "url": "https://api.fiatpe.com/v1/payments/FIATPESTDS7GILWFCO1790705098/authentication/"
    }
  ]
}

Redirect the customer’s browser to next[0].url so they can complete wallet authentication.

Handle the wallet result

Return the HTML document to the browser with a text/html content type.
For a redirect action, navigate the customer’s browser to the returned URL.
Do not modify the form action, payment mode, or wallet code returned by FiatPe.
Do not treat the redirect as proof of payment success.
Confirm the final payment status on your backend and process webhooks idempotently.