Inter API Documentation

# GetOrderStatus Method

Overview

This method allows Client Applications to obtain the status of a previously accepted order at any time. Use this method to track order progress and provide real-time updates to your customers.

Use Cases:

• Check if an order has been paid
• Track order progress through the payment lifecycle
• Get payment instructions for recipients
• Monitor orders in compliance review

Performance: Typically responds in 100-300ms

Request Fields

Note: You must provide either OrderID or AgentOrderReference (but not both).

Legend: R = Required, C = Conditional (one of OrderID or AgentOrderReference must be provided)

Validation Rules

• You can provide only AgentOrderReference (OrderID can be omitted or empty)
• You can provide only OrderID (AgentOrderReference can be omitted or empty)
• You may provide both if you prefer
• At least one valid identifier must be provided

Request Examples

Example 1: Check Order Status by OrderID

SOAP Request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="http://mts.geobridge.org/">
      <UserName>your_username</UserName>
      <Password>your_password</Password>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <GetOrderStatus xmlns="http://mts.geobridge.org/">
      <AgentID>12345</AgentID>
      <PartnerID>100</PartnerID>
      <OrderID>987654321</OrderID>
    </GetOrderStatus>
  </soap:Body>
</soap:Envelope>

SOAP Response (Order Paid):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetOrderStatusResponse xmlns="http://mts.geobridge.org/">
      <GetOrderStatusResult>
        <OrderStatus>
          <AgentOrderReference>REF-2025-001234</AgentOrderReference>
          <OrderID>987654321</OrderID>
          <OrderProcessingTime>2025-11-05T10:30:00</OrderProcessingTime>
          <NetAmountSent>1000.00</NetAmountSent>
          <TotalFeeSender>15.00</TotalFeeSender>
          <ExchangeRateSender>5.25</ExchangeRateSender>
          <CurrencySent>USD</CurrencySent>
          <ExchangeRateAgent>5.20</ExchangeRateAgent>
          <TotalFeeAgent>10.00</TotalFeeAgent>
          <TotalDueFromAgent>1010.00</TotalDueFromAgent>
          <AmountReceived>5250.00</AmountReceived>
          <TotalRecipiententFee>0.00</TotalRecipiententFee>
          <TotalPaidToRecipient>5250.00</TotalPaidToRecipient>
          <CurrencyOfPayment>BRL</CurrencyOfPayment>
          <CurrencyOfPaymentID>1</CurrencyOfPaymentID>
          <PaymentInstructions>Funds deposited to Banco do Brasil account ending in 1234</PaymentInstructions>
          <TypeOfPaymentID>1</TypeOfPaymentID>
          <OrderAcceptanceCode>A</OrderAcceptanceCode>
          <OrderClaimCode></OrderClaimCode>
          <TransactionResult></TransactionResult>
          <ResultCodes>1001</ResultCodes>
          <AdditionalMessage>Order successfully paid on 2025-11-05</AdditionalMessage>
          <StatusCode>5</StatusCode>
          <LastStatusUpdate>2025-11-05T14:25:00</LastStatusUpdate>
          <StatusUpdateReason></StatusUpdateReason>
        </OrderStatus>
      </GetOrderStatusResult>
    </GetOrderStatusResponse>
  </soap:Body>
</soap:Envelope>

Example 2: Check Order Status by AgentOrderReference

SOAP Request:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="http://mts.geobridge.org/">
      <UserName>your_username</UserName>
      <Password>your_password</Password>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <GetOrderStatus xmlns="http://mts.geobridge.org/">
      <AgentID>12345</AgentID>
      <PartnerID>100</PartnerID>
      <AgentOrderReference>REF-2025-001234</AgentOrderReference>
    </GetOrderStatus>
  </soap:Body>
</soap:Envelope>

SOAP Response (Order On Hold - OFAC):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetOrderStatusResponse xmlns="http://mts.geobridge.org/">
      <GetOrderStatusResult>
        <OrderStatus>
          <AgentOrderReference>REF-2025-001234</AgentOrderReference>
          <OrderID>987654322</OrderID>
          <OrderProcessingTime>2025-11-05T10:30:00</OrderProcessingTime>
          <NetAmountSent>5000.00</NetAmountSent>
          <TotalFeeSender>25.00</TotalFeeSender>
          <ExchangeRateSender>5.25</ExchangeRateSender>
          <CurrencySent>USD</CurrencySent>
          <ExchangeRateAgent>5.20</ExchangeRateAgent>
          <TotalFeeAgent>20.00</TotalFeeAgent>
          <TotalDueFromAgent>5020.00</TotalDueFromAgent>
          <AmountReceived>26250.00</AmountReceived>
          <TotalRecipiententFee>0.00</TotalRecipiententFee>
          <TotalPaidToRecipient>26250.00</TotalPaidToRecipient>
          <CurrencyOfPayment>BRL</CurrencyOfPayment>
          <CurrencyOfPaymentID>1</CurrencyOfPaymentID>
          <PaymentInstructions></PaymentInstructions>
          <TypeOfPaymentID>1</TypeOfPaymentID>
          <OrderAcceptanceCode>A</OrderAcceptanceCode>
          <OrderClaimCode></OrderClaimCode>
          <TransactionResult></TransactionResult>
          <ResultCodes>1051</ResultCodes>
          <AdditionalMessage>Order on hold for compliance review</AdditionalMessage>
          <StatusCode>2</StatusCode>
          <LastStatusUpdate>2025-11-05T10:32:00</LastStatusUpdate>
          <StatusUpdateReason></StatusUpdateReason>
        </OrderStatus>
      </GetOrderStatusResult>
    </GetOrderStatusResponse>
  </soap:Body>
</soap:Envelope>

Example 3: Order in Processing

SOAP Response:

<OrderStatus>
  <AgentOrderReference>REF-2025-001235</AgentOrderReference>
  <OrderID>987654323</OrderID>
  <OrderProcessingTime>2025-11-05T11:00:00</OrderProcessingTime>
  <NetAmountSent>500.00</NetAmountSent>
  <TotalFeeSender>10.00</TotalFeeSender>
  <ExchangeRateSender>17.00</ExchangeRateSender>
  <CurrencySent>USD</CurrencySent>
  <AmountReceived>8500.00</AmountReceived>
  <CurrencyOfPayment>MXN</CurrencyOfPayment>
  <TypeOfPaymentID>2</TypeOfPaymentID>
  <OrderAcceptanceCode>A</OrderAcceptanceCode>
  <OrderClaimCode>PMT-8765-4321</OrderClaimCode>
  <ResultCodes>1001</ResultCodes>
  <AdditionalMessage>Order sent to payer, awaiting confirmation</AdditionalMessage>
  <StatusCode>4</StatusCode>
  <LastStatusUpdate>2025-11-05T11:15:00</LastStatusUpdate>
  <StatusUpdateReason></StatusUpdateReason>
</OrderStatus>

Explanation:

• Order is in "Processing" (StatusCode 4)
• Claim code provided: PMT-8765-4321

Response Fields Explained

Primary fields for order tracking

The following fields are the main ones to check in the GetOrderStatus response:

Main status codes (StatusCode)

The following are the principal StatusCode values partners typically use for tracking and customer messaging. Other numeric codes may appear in specific flows; treat unknown values as non-final and keep polling GetOrderStatus or contact support.

Key Fields for Customer Display

Error Response Example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>Order not found</faultstring>
      <detail>
        <ErrorCode>2001</ErrorCode>
        <ErrorMessage>Order not found with provided OrderID or AgentOrderReference</ErrorMessage>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Integration Best Practices

1. Store OrderID for Future Reference

Always store the OrderID returned from CreateNewOrder:

// After CreateNewOrder
const createResponse = await CreateNewOrder(orderData);
const orderId = createResponse.OrderID;

// Store in your database
await db.orders.update({
  agentOrderReference: 'REF-2025-001234',
  pontualOrderId: orderId,
  status: 'pending'
});

// Later, check status
const status = await GetOrderStatus({
  AgentID: 12345,
  PartnerID: 100,
  OrderID: orderId
});

2. Implement Polling with Exponential Backoff

async function pollOrderStatus(orderId, maxAttempts = 20) {
  let attempt = 0;
  let delay = 5000; // Start with 5 seconds
  
  while (attempt < maxAttempts) {
    const status = await GetOrderStatus({ OrderID: orderId });
    
    // Check if final state
    if ([5, 6].includes(status.StatusCode)) {
      return status; // Paid or Canceled
    }
    
    // Wait before next poll
    await sleep(delay);
    
    // Exponential backoff (max 60 seconds)
    delay = Math.min(delay * 1.5, 60000);
    attempt++;
  }
  
  throw new Error('Polling timeout');
}

3. Display Status to Customers

function getCustomerFriendlyStatus(statusCode, resultCodes) {
  switch(statusCode) {
    case 1:
      return 'Pending - Additional information required';
    case 2:
      return 'Under Review - Our team is reviewing your transfer';
    case 3:
      return 'Approved - Transfer will be processed shortly';
    case 4:
      return 'In Progress - Transfer is being sent';
    case 5:
      return 'Completed - Funds are available for pickup/deposit';
    case 6:
      return 'Canceled';
    case 7:
      return 'Problem - Please contact support';
    case 8:
      return 'Unfinished - Order not finalized';
    case 11:
      return 'Pending approval - Awaiting authorization';
    default:
      return 'Unknown status';
  }
}

5. Monitor Orders Stuck in Status

// Alert if order stuck in same status for too long
async function checkStuckOrders() {
  const orders = await db.orders.find({ status: { $in: [3, 4, 8] } });
  
  for (const order of orders) {
    const hoursSinceLastUpdate = 
      (Date.now() - order.lastStatusUpdate) / (1000 * 60 * 60);
    
    if (hoursSinceLastUpdate > 4) {
      // Alert operations team
      await sendAlert({
        type: 'stuck_order',
        orderId: order.pontualOrderId,
        status: order.status,
        hoursSinceUpdate: hoursSinceLastUpdate
      });
    }
  }
}

Testing

Webhooks (Future Enhancement)

Note: Currently, status checking requires polling. Webhook support for real-time status updates is planned for future release.

Planned webhook events:

• order.status_changed
• order.paid
• order.on_hold
• order.canceled

Related Methods

• CreateNewOrder - Create order and get initial OrderID
• GetOrderDetails - Get complete order information including sender/recipient details
• GetPaymentsByDate - Get list of paid orders for reconciliation

Support

• remittance@inter.co
• Guilherme Campos — guilherme.campos@inter.co