SERVER 2 SERVER

S2S Wallet

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

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`

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",
    "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/create/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",
    "description": "Test payment",
    "method": "wallet",
    "wallet": "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.
`method`	Yes	Set to `wallet`.
`wallet`	Yes	FiatPe wallet 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/create/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",
    "description": "Test payment",
    "method": "wallet",
    "wallet": "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.