GetOrderStatus - Inter API v2.0

# 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

Field Name	Type (Length)	Option	Description
AgentID	Integer (9)	R	Your agent ID
PartnerID	Integer (9)	R	Your partner ID
OrderID	Integer (10)	C	Pontual's unique order ID. Required if AgentOrderReference is not provided
AgentOrderReference	Alpha (25)	C	Your unique order reference. Required if OrderID is not provided

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

Error 3101: Missing both valid OrderID and AgentOrderReference.

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>
          <LastStatusUpdade>2025-11-05T14:25:00</LastStatusUpdade>
        </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>
          <LastStatusUpdade>2025-11-05T10:32:00</LastStatusUpdade>
        </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>
  <LastStatusUpdade>2025-11-05T11:15:00</LastStatusUpdade>
</OrderStatus>

Explanation:

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

Response Fields Explained

Key Fields for Customer Display

Field	Description	When to Show
StatusCode	Current order status (1-8)	Always
PaymentInstructions	Instructions for recipient	Always, if provided
LastStatusUpdade	When status last changed	Always
AmountReceived	Amount recipient will receive	Always

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 'Verifying - Compliance check in progress';
    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
marcos.lanzoni@inter.co

Inter API Documentation