Payment Inquiries

Payment Inquiries allow you to request additional information from the payer during the payment process. This is useful when you need specific details that aren't available at payment creation time.

Use Cases

Delivery address, Gift messages, Special instructions, Custom form fields

What are Inquiries?

Inquiries are questions or form fields presented to the user during payment confirmation. The user's responses are included in the transaction data and callbacks.

When to Use

✅ Good for: Delivery details, Gift messages, Special requests, Additional contact info

❌ Not for: Payment amount, Beneficiary selection, Critical payment data

Creating Inquiries

View Creation Examples

Basic Inquiry

POST /rest/v1/transaction

{
  "payments": [{
    "description": "Gift purchase",
    "price": 2999
  }],
  "inquiries": [
    {
      "name": "gift_message",
      "title": "Gift message (optional)",
      "type": "text"
    }
  ]
}

Multiple Inquiries

{
  "payments": [{
    "description": "Product order",
    "price": 4999
  }],
  "inquiries": [
    {
      "name": "delivery_address",
      "title": "Delivery address",
      "type": "text",
      "required": true
    },
    {
      "name": "delivery_time",
      "title": "Preferred delivery time",
      "type": "select",
      "options": [
        "Morning (8-12)",
        "Afternoon (12-17)",
        "Evening (17-20)"
      ]
    },
    {
      "name": "gift_wrap",
      "title": "Gift wrapping?",
      "type": "checkbox"
    }
  ]
}

Inquiry Types

View Available Types

Text Input

Free-form text field:

{
  "name": "special_instructions",
  "title": "Special delivery instructions",
  "type": "text",
  "required": false
}

Select Dropdown

Predefined options:

{
  "name": "size",
  "title": "Select size",
  "type": "select",
  "options": ["Small", "Medium", "Large", "X-Large"],
  "required": true
}

Checkbox

Yes/No choice:

{
  "name": "newsletter",
  "title": "Subscribe to newsletter",
  "type": "checkbox"
}

Radio Buttons

Single choice from multiple options:

{
  "name": "delivery_method",
  "title": "Delivery method",
  "type": "radio",
  "options": [
    "Standard (3-5 days)",
    "Express (1-2 days)",
    "Same day"
  ],
  "required": true
}

Inquiry Fields

Field	Type	Required	Description
`name`	string	✅ Yes	Unique identifier for this inquiry
`title`	string	✅ Yes	Question/label shown to user
`type`	string	✅ Yes	Input type (`text`, `select`, `checkbox`, `radio`)
`required`	boolean	⚠️ Optional	Whether user must answer (default: false)
`options`	array	⚠️ For select/radio	Available options
`default_value`	string	⚠️ Optional	Pre-filled value

Accessing Inquiry Responses

View Response Handling

In Transaction Object

GET /rest/v1/transaction/{transaction_key}

Response includes answers:

{
  "transaction_key": "pDAlAZ3z",
  "status": "confirmed",
  "inquiries": [
    {
      "name": "delivery_address",
      "answer": "123 Main St, Apt 4B, Vilnius"
    },
    {
      "name": "delivery_time",
      "answer": "Afternoon (12-17)"
    },
    {
      "name": "gift_wrap",
      "answer": "true"
    }
  ]
}

In Callbacks

Inquiry responses are included in payment callbacks:

POST https://yoursite.com/payment-callback

{
  "transaction_key": "pDAlAZ3z",
  "status": "confirmed",
  "inquiries": [
    {
      "name": "delivery_address",
      "answer": "123 Main St, Vilnius"
    }
  ]
}

Processing Responses

app.post('/payment-callback', (req, res) => {
  const { transaction_key, inquiries } = req.body;
  
  // Extract answers
  const answers = {};
  inquiries.forEach(inquiry => {
    answers[inquiry.name] = inquiry.answer;
  });
  
  // Use the data
  await processOrder({
    transactionKey: transaction_key,
    deliveryAddress: answers.delivery_address,
    deliveryTime: answers.delivery_time,
    giftWrap: answers.gift_wrap === 'true'
  });
  
  res.status(200).send('OK');
});

Common Patterns

View Real-World Patterns

Pattern 1: E-Commerce with Delivery

{
  "payments": [{
    "description": "Online order",
    "items": [...]
  }],
  "inquiries": [
    {
      "name": "delivery_address",
      "title": "Delivery address",
      "type": "text",
      "required": true
    },
    {
      "name": "phone",
      "title": "Contact phone",
      "type": "text",
      "required": true
    },
    {
      "name": "delivery_notes",
      "title": "Delivery instructions (optional)",
      "type": "text",
      "required": false
    }
  ]
}

Pattern 2: Gift Purchase

{
  "payments": [{
    "description": "Gift card purchase",
    "price": 5000
  }],
  "inquiries": [
    {
      "name": "recipient_email",
      "title": "Recipient email",
      "type": "text",
      "required": true
    },
    {
      "name": "gift_message",
      "title": "Personal message",
      "type": "text",
      "required": false
    },
    {
      "name": "send_date",
      "title": "Send on",
      "type": "select",
      "options": [
        "Immediately",
        "Tomorrow",
        "Next week",
        "Specific date"
      ]
    }
  ]
}

Pattern 3: Service Booking

{
  "payments": [{
    "description": "Consultation booking",
    "price": 7500
  }],
  "inquiries": [
    {
      "name": "preferred_date",
      "title": "Preferred date",
      "type": "select",
      "options": availableDates,
      "required": true
    },
    {
      "name": "preferred_time",
      "title": "Preferred time",
      "type": "select",
      "options": availableTimes,
      "required": true
    },
    {
      "name": "topic",
      "title": "What would you like to discuss?",
      "type": "text",
      "required": false
    }
  ]
}

Advanced Topics

Validation

Client-Side Validation

const validateInquiries = (inquiries, responses) => {
  const errors = [];
  
  inquiries.forEach(inquiry => {
    const response = responses[inquiry.name];
    
    // Check required fields
    if (inquiry.required && !response) {
      errors.push(`${inquiry.title} is required`);
    }
    
    // Validate select/radio options
    if ((inquiry.type === 'select' || inquiry.type === 'radio') && 
        response && 
        !inquiry.options.includes(response)) {
      errors.push(`Invalid option for ${inquiry.title}`);
    }
  });
  
  return errors;
};

Server-Side Validation

app.post('/payment-callback', (req, res) => {
  const { inquiries } = req.body;
  
  // Validate email format
  const emailInquiry = inquiries.find(i => i.name === 'email');
  if (emailInquiry && !isValidEmail(emailInquiry.answer)) {
    console.error('Invalid email provided');
  }
  
  // Validate phone format
  const phoneInquiry = inquiries.find(i => i.name === 'phone');
  if (phoneInquiry && !isValidPhone(phoneInquiry.answer)) {
    console.error('Invalid phone provided');
  }
  
  res.status(200).send('OK');
});

Limitations & Alternatives

Current Limitations

⚠️ No file uploads - Only text-based inputs
⚠️ No validation rules - Validate in your callback
⚠️ Limited formatting - Basic HTML in title only
⚠️ No conditional logic - All inquiries always shown
⚠️ No real-time updates - Answers come in callback

Alternative: Using Payment Parameters

For simple key-value data:

{
  "payments": [{
    "price": 2999,
    "parameters": {
      "size": "Large",
      "color": "Blue",
      "gift_wrap": "yes"
    }
  }]
}

Better when: Data is known before payment (from your form)

Alternative: External Forms

Collect data on your site, then create payment:

// 1. User fills form on your site
const formData = { address: "...", phone: "..." };

// 2. Store in your database
const order = await createOrder(formData);

// 3. Create payment with order reference
const tx = await createTransaction({
  payments: [{
    description: `Order #${order.id}`,
    price: order.total,
    parameters: { order_id: order.id }
  }]
});

Better when: Complex validation needed, or storing data before payment

API Reference

Inquiries are set when creating a transaction:

POST /rest/v1/transaction
{
  "payments": [...],
  "inquiries": [
    {
      "name": "field_name",
      "title": "Question for user",
      "type": "text",
      "required": true
    }
  ]
}

Full API reference: Wallet API Endpoints

What's Next?

Now you've learned all API Resources! Continue with:

Authorising Transactions - All acceptance methods
Callbacks - Handle payment notifications
Samples & Examples - See it all in action

Need Help?

Questions? → tech_support@paysera.com
Transaction Guide → Transaction Resource
Examples → Code Samples

Quick Reference

Types: text, select, checkbox, radio
Access: Via transaction object or callbacks
Best for: Delivery info, preferences, optional details
Not for: Critical payment data

What are Inquiries?​

Creating Inquiries​

Inquiry Types​

Inquiry Fields​

Accessing Inquiry Responses​

Common Patterns​

Advanced Topics​

API Reference​

What's Next?​

Need Help?​