Inter API Documentation

# GetPaymentsByDate Method

Overview

The GetPaymentsByDate method retrieves all orders that were confirmed as paid to recipients on a specific date. This is the primary method for daily reconciliation and financial reporting. The payment confirmation date is the actual date when funds were delivered to the recipient, as reported by the bank or payment agent.

Use Cases

• Daily Reconciliation: Match payments with your accounting system
• Financial Reporting: Generate daily payment reports for management
• Commission Calculation: Calculate partner commissions based on completed payments
• Audit Trail: Maintain records of all completed transactions
• Customer Service: Verify payment completion dates for customer inquiries
• Compliance: Provide payment records for regulatory reporting

Response Fields

The method returns an array of orders. Each order contains:

Note: For complete order details (amounts, sender, recipient), use GetOrderDetails with the returned OrderID.

Request Fields

SOAP Request/Response Examples

Example 2: No Payments for Date

Request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPaymentsByDate xmlns="http://tempuri.org/">
      <AgentID>12345</AgentID>
      <PartnerID>67890</PartnerID>
      <PaymentConfirmationDate>2025-11-01</PaymentConfirmationDate>
    </GetPaymentsByDate>
  </soap:Body>
</soap:Envelope>

Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPaymentsByDateResponse xmlns="http://tempuri.org/">
      <GetPaymentsByDateResult>
        <Payments />
      </GetPaymentsByDateResult>
    </GetPaymentsByDateResponse>
  </soap:Body>
</soap:Envelope>

Example 3: Single Payment

Request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPaymentsByDate xmlns="http://tempuri.org/">
      <AgentID>12345</AgentID>
      <PartnerID>67890</PartnerID>
      <PaymentConfirmationDate>2025-11-04</PaymentConfirmationDate>
    </GetPaymentsByDate>
  </soap:Body>
</soap:Envelope>

Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetPaymentsByDateResponse xmlns="http://tempuri.org/">
      <GetPaymentsByDateResult>
        <Payments>
          <Payment>
            <OrderID>9876542</OrderID>
            <AgentOrderReference>TXN-2025-001233</AgentOrderReference>
            <OrderCreationTime>2025-11-04T14:00:00</OrderCreationTime>
            <OrderPaymentTime>2025-11-04T18:30:00</OrderPaymentTime>
            <AdditionalInformation>Bank deposit - TED</AdditionalInformation>
          </Payment>
        </Payments>
      </GetPaymentsByDateResult>
    </GetPaymentsByDateResponse>
  </soap:Body>
</soap:Envelope>

Response Fields Explained

Understanding the Response

The response contains a list of orders that were paid to recipients on the specified date. Key points:

OrderID & AgentOrderReference:

• Use these to match payments with your internal records
• AgentOrderReference is your original order reference from CreateNewOrder

OrderCreationTime vs OrderPaymentTime:

• OrderCreationTime - When customer placed the order
• OrderPaymentTime - When recipient actually received funds
• Important: These can be different days! Use OrderPaymentTime for reconciliation.

AdditionalInformation:

• Contains payment method details
• May include payer bank name, confirmation numbers, or other relevant info
• Format varies by payment method and destination country

Time Zones

• All timestamps are in UTC
• Convert to your local timezone for display
• PaymentConfirmationDate parameter uses date only (no time component)

Integration Best Practices

2. Get Full Order Details for Each Payment

// For reconciliation, you typically need full order details
async function getPaymentsWithDetails(date) {
  // 1. Get list of paid orders
  const payments = await soapClient.GetPaymentsByDate({
    AgentID: config.agentID,
    PartnerID: config.partnerID,
    PaymentConfirmationDate: date
  });
  
  if (!payments || payments.length === 0) {
    return [];
  }
  
  // 2. Get full details for each order (in parallel)
  const detailsPromises = payments.map(payment =>
    soapClient.GetOrderDetails({
      AgentID: config.agentID,
      PartnerID: config.partnerID,
      OrderID: payment.OrderID,
      AgentOrderReference: ''
    })
  );
  
  const allDetails = await Promise.all(detailsPromises);
  
  // 3. Combine payment info with full details
  return payments.map((payment, index) => ({
    ...payment,
    details: allDetails[index]
  }));
}

// Usage
const paymentsWithDetails = await getPaymentsWithDetails('2025-11-05');

paymentsWithDetails.forEach(payment => {
  console.log(`Order: ${payment.AgentOrderReference}`);
  console.log(`Amount: ${payment.details.NetAmountSent} USD`);
  console.log(`Recipient: ${payment.details.RecipientFirstName} ${payment.details.RecipientLastName}`);
  console.log(`Payment Method: ${payment.details.TypeOfPaymentText}`);
  console.log(`Paid At: ${payment.OrderPaymentTime}`);
  console.log('---');
});

4. Handle Missing Payments

// Check for orders that should have been paid but weren't
async function checkMissingPayments(date) {
  // 1. Get all orders created 2+ days ago that should be paid
  const expectedDate = new Date(date);
  expectedDate.setDate(expectedDate.getDate() - 2);
  
  const pendingOrders = await db.orders.find({
    createdAt: { $lte: expectedDate },
    status: { $in: ['open', 'processing'] }
  });
  
  if (pendingOrders.length === 0) {
    console.log('No missing payments found');
    return;
  }
  
  console.log(`Found ${pendingOrders.length} orders pending payment`);
  
  // 2. Check status of each order
  for (const order of pendingOrders) {
    try {
      const status = await soapClient.GetOrderStatus({
        AgentID: config.agentID,
        PartnerID: config.partnerID,
        OrderID: order.pontualOrderID
      });
      
      if (status.StatusCode === 5) {
        // Order was paid but not in reconciliation yet
        console.warn(`Order ${order.orderReference} is paid but not in reconciliation`);
        // May need to check previous days
      } else if (status.StatusCode === 2 || status.StatusCode === 7) {
        // Order has issues
        console.error(`Order ${order.orderReference} has issues: Status ${status.StatusCode}`);
        await alertOps(`Order ${order.orderReference} requires attention`);
      }
    } catch (error) {
      console.error(`Error checking order ${order.orderReference}:`, error);
    }
  }
}

5. Backfill Historical Data

// Backfill reconciliation for multiple days
async function backfillReconciliation(startDate, endDate) {
  const start = new Date(startDate);
  const end = new Date(endDate);
  
  console.log(`Backfilling reconciliation from ${startDate} to ${endDate}...`);
  
  const results = [];
  
  for (let date = new Date(start); date <= end; date.setDate(date.getDate() + 1)) {
    const dateStr = date.toISOString().split('T')[0];
    
    try {
      console.log(`Processing ${dateStr}...`);
      
      const payments = await soapClient.GetPaymentsByDate({
        AgentID: config.agentID,
        PartnerID: config.partnerID,
        PaymentConfirmationDate: dateStr
      });
      
      results.push({
        date: dateStr,
        count: payments ? payments.length : 0,
        status: 'success'
      });
      
      if (payments && payments.length > 0) {
        await generateReconciliationReport(dateStr, payments);
      }
      
      // Rate limiting - wait 1 second between requests
      await sleep(1000);
    } catch (error) {
      console.error(`Error processing ${dateStr}:`, error);
      results.push({
        date: dateStr,
        count: 0,
        status: 'error',
        error: error.message
      });
    }
  }
  
  console.log('Backfill complete:', results);
  return results;
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

// Usage
await backfillReconciliation('2025-10-01', '2025-10-31');

Testing

Best Practices

Timing

When to Call:

• Recommended: 9:00 AM local time (allows overnight payments to settle)
• Minimum: Wait until 6:00 AM local time
• Frequency: Once per day per date

Why Not Real-Time:

• Payment confirmations may arrive with delays
• Banks process payments in batches
• Some payment methods take 1-2 hours to confirm

Data Retention

• Store reconciliation reports for at least 7 years (regulatory requirement)
• Keep raw payment data for 90 days minimum
• Archive older data to cold storage

Error Handling

// Robust error handling for reconciliation
async function safeReconciliation(date) {
  const maxRetries = 3;
  let attempt = 0;
  
  while (attempt < maxRetries) {
    try {
      const payments = await soapClient.GetPaymentsByDate({
        AgentID: config.agentID,
        PartnerID: config.partnerID,
        PaymentConfirmationDate: date
      });
      
      return payments;
    } catch (error) {
      attempt++;
      
      if (error.code === 3001 && attempt < maxRetries) {
        // Database error - retry after delay
        console.log(`Retry ${attempt}/${maxRetries} for ${date}...`);
        await sleep(30000); // Wait 30 seconds
      } else {
        // Other error or max retries reached
        throw error;
      }
    }
  }
}

Related Methods

Before calling GetPaymentsByDate:

• CreateNewOrder - Create orders
• GetOrderStatus - Check if orders are paid

After getting payments:

• GetOrderDetails - Get full details for each payment
• GetCancelationsByCanceledDate - Reconcile cancellations

Support

• remittance@inter.co
• marcos.lanzoni@inter.co