Introduction

Welcome to the Wipays API! You can use our API to receive payments from your customers. You will be able to create payment links, and receive payment notifications.

This API documentation is a part of Wipays. Feel free to contact us for any questions or feedback.

Authentication

To authorize, add the field public_key to the body of your request:

curl -X POST https://{{DOMAIN}}/endpoint \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key"
}'

You will need 2 keys to use Wipays API: public_key and secret_key. You can receive both API keys from your support manager.

public_key is used to authenticate your requests to the API. You should include it in the body of your request.

secret_key is used to generate and verify signatures for Instant Payment Notification (IPN).

Initiate Payment

To initiate a payment, send a POST request to the following endpoint: Fields are sorted in alphabetical order.

curl -X POST https://{{DOMAIN}}/payment/initiate \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key",
  "amount": "",
  "billing_info": {
       "address_one": "",
       "address_two": "",
       "area": "",
       "city": "",
       "sub_city": "",
       "state": "",
       "postcode": "",
       "country": "",
       "others": "",
  },
  "cancel_url": "",
  "currency": "USD",
  "customer": {
      "first_name": "",
      "last_name": "",
      "email": "",
      "mobile": "",
  },
  "details": "",
  "identifier": "",
  "ipn_url": "",
  "shipping_info": {
       "address_one": "",
       "address_two": "",
       "area": "",
       "city": "",
       "sub_city": "",
       "state": "",
       "postcode": "",
       "country": "",
       "others": "",
  },
  "site_name": "",
  "site_logo": "",
  "success_url": "",
}'

The above command returns JSON structure like this:

{
  "status": "success",
  "message": "Payment initiated successfully",
  "redirect_url": "https://wipays.com/payment/checkout?payment_trx=UNIQUE_PAYMENT_ID"
}

This endpoint initiates a payment. The response will contain a payment link that you can redirect your customer to.

HTTP Request

POST http://{{DOMAIN}}/payment/initiate

Query Parameters

Customer Parameters

Billing Info Parameters

Shipping Info Parameters

Response Parameters

IPN (Instant Payment Notification)

Wipays sends payment notifications to the IPN URL you provide in the payment initiation request. The IPN will contain the payment details.

IPN Parameters

Signature Generation

To generate the signature, you should hash the concatenation of the identifier and timestamp with your secret_key using sha256 and convert it to uppercase. See the code examples. PHP example is the "source of truth" for the signature generation

$signature = strtoupper(hash_hmac('sha256', $identifier.$timestamp, $secret_key));

const signature = crypto.createHmac('sha256', secret_key).update(`${identifier}${timestamp}`).digest('hex').toUpperCase();

IPN types

• Checkout - type: "checkout"
• Chargeback Initiated - type: "chargeback_initiated"
• Chargeback Resolved - type: "chargeback_resolved"

Checkout IPN Data

Chargeback Initiated IPN Data

Chargeback Resolved IPN Data

H2H (Host-to-Host) Payments

The H2H API allows merchants to process payments directly in their applications without redirecting customers to hosted payment pages. This provides a seamless payment experience where customers stay on the merchant's website throughout the payment process.

H2H Payment Flow

1. Initiate H2H Payment: Create a payment and receive payment credentials (e.g. Payment link and QR Code for UPI)
2. Display Payment Data: Render payment credentials and instructions on your page
3. Customer Pays: For UPI: Customer scans QR code or clicks "Pay" button with the deeplink on mobile and completes payment in their app
4. Payment Confirmed: Most payments are confirmed automatically in ~60 seconds. Some payments may require manual verification.

Manual Verification Flow

This is only required for the payments that were not confirmed automatically in ~60 seconds. 1. Submit Proof: Customer uploads proof of payment – a screenshot of operation with payment ID visible 2. Send Proof To Platform: Merchant sends proof of payment to the platform via designated H2H API endpoint 3. Manual Verification: Payment is verified and confirmed

Proof of payment can be uploaded automatically via the H2H API. There is no need for the Client to leave Merchant's payment page at any moment – all process is designed to be as smooth as possible.

What To Expect

• The normal time for the automatic payment confirmation is up to 60 seconds. However, you may choose how long you want to wait before requesting proof of payment from the client.
• The share of payments that require proof of payment is normally in range between 5% to 25%. This is constantly changing due to UPI's internal processes.
• The average processing time for proof of payment is 5 – 30 minutes.

Initiate H2H Payment

To initiate an H2H payment, send a POST request to the following endpoint:

curl -X POST https://{{DOMAIN}}/h2h/initiate \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key",
  "amount": 100.00,
  "currency": "INR",
  "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "mobile": "+919876543210"
  },
  "details": "Payment for order #123",
  "identifier": "order_123_unique_id",
  "ipn_url": "https://yourdomain.com/ipn",
  "success_url": "https://yourdomain.com/success",
  "cancel_url": "https://yourdomain.com/cancel",
  "site_name": "Your Store"
}'

The above command returns JSON structure like this:

{
  "status": "success",
  "trx": "UUID",
  "qr_code": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51...",
  "qr_content": "upi://pay?pa=merchant@upi&pn=MerchantName&am=100.00&cu=INR&tn=TXN123456789",
  "paymentlinks": {
    "upi": "upi://pay?pa=merchant@upi&pn=MerchantName&am=100.00&cu=INR&tn=TXN123456789",
    "upi1": "upi://pay?pa=merchant@upi&pn=MerchantName&am=100.00&cu=INR&tn=TXN123456789&mode=01",
    "paytm": "paytmmp://cash_wallet?pa=merchant@upi&am=100.00&featuretype=money_transfer",
    "phonepe": "phonepe://pay?pa=merchant@upi&am=100.00",
    "gpay": "gpay://pay?pa=merchant@upi&am=100.00"
  }
}

This endpoint initiates an H2H payment and returns payment credentials data that you can display directly on your website or in your application.

HTTP Request

POST http://{{DOMAIN}}/h2h/initiate

Request Parameters

Customer Parameters

Billing Info Parameters

Shipping Info Parameters

H2H-Specific Considerations

• Only currencies/countries with H2H support will be used
• Response contains payment credentials instead of redirect_url

H2H Response Parameters

Payment Links Object

The paymentlinks object contains platform-specific payment links that can be used to direct customers to their preferred payment apps. Those links can be used to give the clients deeplink on their mobile devices – when the client goes through such link, the corresponding app (Bank, PayTM, PhonePe, GPay) will open and he will be sent directly to the payment screen there.

Submit Proof of Payment

To submit proof of payment, send a POST request:

curl -X POST https://{{DOMAIN}}/h2h/confirm \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key",
  "trx": "UUID",
  "payment_proof": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."
}'

The above command returns JSON structure like this:

{
  "status": "success",
  "message": ["Payment proof submitted successfully. Transaction is pending manual verification."],
  "trx": "UUID",
  "proof_status": "pending",
  "verification_note": "Your payment proof has been submitted and will be verified by our team. You will be notified once verification is complete."
}

After the customer completes payment, they may need to submit proof of payment for verification.

HTTP Request

POST http://{{DOMAIN}}/h2h/confirm

Request Parameters

Proof Formats

Base64 Image (Screenshot): "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."

URL (Link to proof image): "https://example.com/payment-proof.jpg"

Check Payment Status

To check the status of an H2H payment:

curl -X POST https://{{DOMAIN}}/h2h/status \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key",
  "trx": "UUID"
}'

The above command returns JSON structure like this:

{
  "status": "success",
  "trx": "UUID",
  "payment_status": "pending",
  "amount": 100.00,
  "currency": "INR",
  "created_at": "2023-12-01T10:30:00.000Z",
  "updated_at": "2023-12-01T10:35:00.000Z",
  "proof_status": "verified",
  "proof_submitted_at": "2023-12-01T10:32:00.000Z",
  "proof_verified_at": "2023-12-01T10:35:00.000Z",
  "verification_notes": "Payment verified successfully"
}

HTTP Request

POST http://{{DOMAIN}}/h2h/status

Request Parameters

Payment Status Values

Proof Status Values

Common H2H Error Responses

No H2H Gateways Available

{
  "status": "error",
  "message": ["No H2H flows available for this currency and merchant"]
}

Invalid Proof Format

{
  "status": "error",
  "message": ["Invalid proof format. Please provide a base64 image, URL, or text reference"]
}

Transaction Not Found

{
  "status": "error",
  "message": ["Transaction not found or not H2H payment"]
}