Check Payment Status¶

Use this endpoint to check the status of an H2H payment, including payment confirmation, 3DS authentication status (for card payments), and proof verification status (for local payments).

Response Structure Overview¶

The status response includes:

Original Request Data - Use identifier, requested_amount, and requested_currency to match the response to your original payment request
Processed Amount Breakdown - Complete fee breakdown in both gateway currency and USD:
gross_amount / gross_amount_usd - Total received before fees
charge / charge_usd - Processing fees
net_amount / net_amount_usd - Net amount after fees (what you receive)
Conversion Rate - Exchange rate applied for currency conversion
Payment-Specific Details - 3DS info for cards, proof verification for local payments

Important: The amounts are shown in both the gateway currency (e.g., INR, BDT) and the platform's base currency (USD) to give you complete visibility into the transaction.

HTTP Request¶

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

Request Example¶

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

Response Examples¶

Card Payment Response¶

For card payments, the response includes 3DS authentication information:

{
  "status": "success",
  "trx": "UUID",

  "identifier": "merchant_order_123",
  "requested_amount": 100.00,
  "requested_currency": "USD",

  "payment_status": "pending",

  "gross_amount": 100.00,
  "charge": 2.50,
  "net_amount": 97.50,
  "currency": "USD",

  "gross_amount_usd": 100.00,
  "charge_usd": 2.50,
  "net_amount_usd": 97.50,

  "conversion_rate": 1.00,

  "created_at": "2023-12-01T10:30:00.000Z",
  "updated_at": "2023-12-01T10:35:00.000Z",

  "requires_3ds": true,
  "redirect_url": "https://3ds-authentication-url.com/auth/xyz123",
  "message": "3DS authentication required"
}

Local Payment Response (UPI/Bangladesh)¶

For local payments, the response includes proof verification information:

{
  "status": "success",
  "trx": "UUID",

  "identifier": "merchant_order_456",
  "requested_amount": 1000.00,
  "requested_currency": "INR",

  "payment_status": "success",

  "gross_amount": 1000.00,
  "charge": 20.00,
  "net_amount": 980.00,
  "currency": "INR",

  "gross_amount_usd": 12.00,
  "charge_usd": 0.24,
  "net_amount_usd": 11.76,

  "conversion_rate": 83.33,

  "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"
}

Request Parameters¶

Parameter	Required	Description	Example
public_key	true	Your API key	"your_api_key"
trx	true	Transaction ID from initiate response	"UUID"

Response Parameters¶

Common Parameters (All Payment Methods)¶

Parameter	Description	Example
status	The status of the API request	"success"
trx	The transaction identifier	"UUID"
identifier	Your order/payment identifier from the initiate request	"merchant_order_123"
requested_amount	Original amount from your initiate request	100.00
requested_currency	Original currency from your initiate request	"INR", "USD", "BDT"
payment_status	Current payment status	"pending", "success", "failed", "cancelled"
gross_amount	Payment amount received (before fees) in gateway currency	100.00
charge	Processing fee charged in gateway currency	2.50
net_amount	Net amount (after fees) in gateway currency	97.50
currency	Gateway/payment currency	"INR", "USD", "BDT"
gross_amount_usd	Payment amount received (before fees) in USD	12.00
charge_usd	Processing fee charged in USD	0.24
net_amount_usd	Net amount (after fees) in USD	11.76
conversion_rate	Exchange rate applied (1 USD = X currency)	83.33
created_at	When the payment was initiated	"2023-12-01T10:30:00.000Z"
updated_at	Last status update timestamp	"2023-12-01T10:35:00.000Z"

Card Payment Specific Parameters¶

Parameter	Description	Example
requires_3ds	Whether 3DS authentication is required/pending	true, false
redirect_url	3DS authentication URL (only if requires_3ds is true)	"https://3ds-auth.com/..."
message	Human-readable payment status message	"3DS authentication required"

Local Payment Specific Parameters (UPI/Bangladesh)¶

Parameter	Description	Example
proof_status	Status of proof verification	"pending", "verified", "rejected"
proof_submitted_at	When proof was submitted	"2023-12-01T10:32:00.000Z"
proof_verified_at	When proof was verified	"2023-12-01T10:35:00.000Z"
verification_notes	Additional verification information	"Payment verified successfully"

Payment Status Values¶

Status	Description
pending	Payment initiated but not yet completed
success	Payment completed and verified
failed	Payment failed or rejected
cancelled	Payment cancelled

Proof Status Values¶

Status	Description
pending	Proof submitted, awaiting verification
verified	Proof verified, payment confirmed
rejected	Proof rejected, payment failed

Example Usage Patterns¶

Simple Status Check¶

Check if a payment has been completed:

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

Polling for Status Updates¶

For Local Payments (UPI/Bangladesh)¶

You can poll this endpoint to monitor payment progress:

async function pollPaymentStatus(trx) {
  const maxAttempts = 60; // Poll for up to 10 minutes
  const interval = 10000; // 10 seconds between polls

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const response = await fetch('https://{{DOMAIN}}/h2h/status', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          public_key: 'your_api_key',
          trx: trx
        })
      });

      const data = await response.json();

      if (data.payment_status === 'success') {
        console.log('Payment successful!');
        return data;
      } else if (data.payment_status === 'failed') {
        console.log('Payment failed');
        return data;
      }

      // Still pending, continue polling
      await new Promise(resolve => setTimeout(resolve, interval));

    } catch (error) {
      console.error('Error checking status:', error);
    }
  }

  console.log('Polling timeout - payment still pending');
}

For Card Payments with 3DS¶

Poll this endpoint to detect when 3DS authentication is completed:

async function pollCardPayment3DS(trx) {
  const maxAttempts = 60; // Poll for up to 10 minutes
  const interval = 5000; // 5 seconds between polls

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const response = await fetch('https://{{DOMAIN}}/h2h/status', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          public_key: 'your_api_key',
          trx: trx
        })
      });

      const data = await response.json();

      // Check if 3DS is completed (requires_3ds becomes false)
      if (!data.requires_3ds) {
        if (data.payment_status === 'success') {
          console.log('Card payment successful!');
          return data;
        } else if (data.payment_status === 'failed') {
          console.log('Card payment failed');
          return data;
        }
      }

      // 3DS still pending, continue polling
      await new Promise(resolve => setTimeout(resolve, interval));

    } catch (error) {
      console.error('Error checking status:', error);
    }
  }

  console.log('Polling timeout - 3DS authentication not completed');
}

Common Error Responses¶

Transaction Not Found¶

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

Authentication Error¶

{
  "status": "error",
  "message": ["Invalid public key"]
}

Best Practices¶

Polling Strategy¶

Card Payments¶

Initial Check: Check status immediately after payment initiation
3DS Polling: Poll every 5-10 seconds while 3DS is in progress
Timeout: 5-10 minutes (most 3DS authentications complete within 2-3 minutes)
Completion: Stop polling when requires_3ds becomes false

Local Payments (UPI/Bangladesh)¶

Initial Check: Check status immediately after payment initiation
Automatic Confirmations: Poll every 10-15 seconds for automatic confirmations
Manual Verification: If proof is required, consider polling every 30-60 seconds
Timeout: 10-15 minutes for automatic confirmation, longer if proof required

On Timeouts

You can choose any timeout that fits your specific UX scenarios for the status polling. Card payments generally need shorter polling intervals than local payments.

Integration with IPN Webhooks¶

For better user experience, combine status polling with IPN notifications:

Poll Initially: Check status immediately after payment initiation
Set Up IPN: Configure IPN webhooks to receive automatic updates
Fallback Polling: Use status polling as a fallback if IPN fails or for manual verification scenarios

Next Steps¶

Set up IPN notifications for automatic status updates
Learn about proof submission if manual verification is needed
Understand the complete H2H flow