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
      });
    }
  }
}

6. Post-payment monitoring — US destination orders

Partner recommendation: Continue calling GetOrderStatus for approximately 7 days after the order reaches Paid, so your systems can detect a reversal as early as possible. A reversed payment may appear as Canceled (6) or Problem (7); review StatusUpdateReason and LastStatusUpdate when those statuses are returned.

Important: This monitoring is a best practice for your integration—it does not replace our internal processes. Our Finance team will contact you regarding reversed orders as soon as possible, regardless of whether you have already detected the status change.

There is currently no webhook for status updates; polling GetOrderStatus (or batch queries such as GetOrderStatusByDate / GetPaymentsByDate where applicable) is required.

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