Inter API Documentation

Version 2.0 - Enhanced Partner Integration Guide

# CreateNewOrder Method

Overview

This method allows Client Applications to create new remittance orders in the Inter system. This is the core method for submitting international money transfers.

Use Cases:

Performance: Typically responds in 5-12 seconds (includes compliance checks)

Important: This method performs multiple validations and compliance checks. Always call GetRatesAndCosts first to ensure accurate rates.

Request Fields

Authentication & Order Identification

Field Name Type (Length) Option Description
AgentID Integer (9) R Your unique ID as an agent in the Inter system
PartnerID Integer (9) R Your unique ID as a partner in the Inter system
AgentOrderReference Alpha (25) R Your unique reference for this order. Must be unique per partner.
OrderCreationTime DateTime R Timestamp when the order was created (ISO 8601 format: YYYY-MM-DDTHH:MM:SS)

Sender Information

Field Name Type (Length) Option Description
SenderFirstName Alpha (50) C Sender's first name (Required for P2P, P2B)
SenderLastName Alpha (50) C Sender's last name (Required for P2P, P2B)
SenderCompanyName Alpha (100) C Sender's company name (Required for B2P, B2B)
SenderCountry Alpha (2) R ISO 3166-1 alpha-2 country code (e.g., "US")
SenderAddress Alpha (225) R Sender's street address
SenderCity Alpha (50) R Sender's city
SenderState Alpha (50) R Sender's state/province
SenderZip Alpha (10) R Sender's postal/ZIP code
SenderPhone1 Alpha (20) R Sender's primary phone number
SenderDateOfBirth Date C Sender's date of birth (Required for P2P, P2B)
SenderDocument1Type Alpha (20) C Document type (e.g., "PASSPORT", "DL", "CPF") (Required for P2P, P2B)
SenderDocument1Number Alpha (30) C Document number (Required for P2P, P2B)

Recipient Information

Field Name Type (Length) Option Description
RecipientFirstName Alpha (50) C Recipient's first name (Required for P2P, B2P)
RecipientLastName Alpha (50) C Recipient's last name (Required for P2P, B2P)
RecipientCompany Alpha (100) C Recipient's company name (Required for P2B, B2B)
RecipientCountry Alpha (2) R ISO 3166-1 alpha-2 country code (e.g., "BR", "US")
RecipientAddress1 Alpha (225) R Recipient's street address
RecipientCity Alpha (50) R Recipient's city
RecipientState Alpha (50) R Recipient's state/province
RecipientZip Alpha (10) R Recipient's postal/ZIP code
RecipientPhone1 Alpha (20) R Recipient's primary phone number
RecipientTIN Alpha (20) C Tax ID (CPF/CNPJ for Brazil, SSN/EIN for USA) (Required for TED, P2B, B2B)
RecipientDocument1Type Alpha (20) C Document type (Required for TED)
RecipientDocument1Number Alpha (30) C Document number (Required for TED)

Bank Account Information (TED/DOC, ACH/FedWire)

Field Name Type (Length) Option Description
RecipientBankName Alpha (100) C Bank name (Required for TED/DOC, ACH/FedWire)
RecipientBankRouting Alpha (20) C Bank routing number (Required for TED/DOC, ACH/FedWire)
RecipientBranchID Alpha (10) C Branch ID (Required for TED/DOC in Brazil)
RecipientBankAccountNo Alpha (30) C Account number (Required for TED/DOC, ACH/FedWire)
RecipientBankAccoutType Alpha (20) C Account type: "CHECKING", "SAVINGS" (Required for TED/DOC, ACH/FedWire)

PIX Information (Brazil Only)

Field Name Type (Length) Option Description
PixTypeId Alpha (20) C PIX key type: "CPF", "PHONE", "EMAIL", "RANDOMKEY" (Required for PIX)
PixId Alpha (100) C PIX key value (Required for PIX)

Transaction Amounts

Field Name Type (Length) Option Description
NetAmountSent Decimal (2) C Amount sent (2 decimals). Required if AmountReceived not provided
AmountReceived Decimal (2) C Amount received (2 decimals). Required if NetAmountSent not provided
CurrencySent Alpha (3) R ISO 4217 currency code (e.g., "USD")
CurrencyOfPayment Alpha (3) R ISO 4217 currency code (e.g., "BRL")
CurrencyOfPaymentID Integer R Currency ID (e.g., 2 for BRL, 1 for USD)
ExchangeRateSender Decimal (2-4) O Exchange rate (2 decimals for Brazil, 4 for others)
TotalFeeSender Decimal (2) O Total fee charged to sender (2 decimals)
TotalCollectedFromSender Decimal (2) O Total amount collected from sender (2 decimals)

Payment Method

Field Name Type (Length) Option Description
TypeOfPaymentID Integer R Payment method ID (31=TED/DOC, 42=PIX, 2=ACH, 3=FedWire)
TypeOfPaymentText Alpha (50) R Payment method name (e.g., "TED", "PIX", "ACH")

Compliance Information

Field Name Type (Length) Option Description
Custom2 Alpha (50) C Transaction type: "B2B" (Required for B2B transactions)
CardToken Alpha (100) C Card token (Required if payment via card)

Legend: R = Required, O = Optional, C = Conditional

Conditional Field Rules

Special Characters in Name and Address Fields

Allowed characters:

Limitations:

Decimal Places Requirements

Value Fields (always 2 decimal places):

Exchange Rates:

Response Fields

Field Name Type (Length) Option Description
OrderID Integer (10) R Unique order ID generated by MTS
AgentOrderReference Alpha (25) R Your order reference (echoed back)
OrderProcessingTime DateTime R When order was processed
OrderAcceptanceCode Alpha (1) R "A" = Accepted, "R" = Rejected
TransactionResult Alpha (1) R Reserved for future use
ResultCodes Alpha (200) R Result codes (comma-separated if multiple)
AdditionalMessage Alpha (200) R Additional information or instructions
StatusCode Integer (9) R Order status (1-8)
LastStatusUpdade DateTime R When status was last updated
PaymentInstructions Alpha (200) O Payment instructions for recipient
PdfReceipt Base64 String O PDF receipt (base64 encoded)

Payment Method Requirements

Understanding TypeOfPaymentID is critical for creating orders successfully. This ID determines:

TypeOfPaymentID Reference Guide

Brazil (BR) - Available Payment Methods

TypeOfPaymentID Payment Method Description Processing Time Required Fields
31 TED/DOC/PIX Bank Deposit Traditional bank transfer or PIX to bank account 30-120 minutes RecipientBankName, RecipientBankRouting, RecipientBankAccountNo, RecipientBankAccoutType, RecipientBranchID
42 PIX via Key Instant payment using PIX key (CPF, Phone, Email, Random Key) 5-30 minutes PixTypeId, PixId (NO bank fields allowed)

Important Notes for Brazil:

TypeOfPaymentID = 31 (Bank Deposit - TED/DOC/PIX - Brazil)

Required Fields:

Processing:

Bank Code Examples:

Account Format:

TypeOfPaymentID = 42 (PIX - Brazil Instant Payment)

Required Fields:

PROHIBITED Fields (must be empty or omitted):

PIX Key Types (TypeOfPaymentID 42):

<!-- CPF as PIX Key -->
<PixTypeId>CPF</PixTypeId>
<PixId>12345678901</PixId>

<!-- Phone as PIX Key -->
<PixTypeId>PHONE</PixTypeId>
<PixId>+5511999999999</PixId>

<!-- Email as PIX Key -->
<PixTypeId>EMAIL</PixTypeId>
<PixId>recipient@email.com</PixId>

<!-- Random Key as PIX Key -->
<PixTypeId>RANDOMKEY</PixTypeId>
<PixId>123e4567-e89b-12d3-a456-426614174000</PixId>

PIX Key Validation:

PixTypeId Format Example Validation
CPF 11 digits "12345678901" Must be valid CPF
PHONE International format "+5511999999999" Must include country code +55
EMAIL Valid email "user@domain.com" Must be valid email format
RANDOMKEY UUID "123e4567-e89b-12d3-a456-426614174000" Must be valid UUID

Processing:

Error Codes:

United States (US) - Available Payment Methods

TypeOfPaymentID Payment Method Description Processing Time Cost
449 ACH Transfer Automated Clearing House - Standard bank transfer 1-3 business days Lowest
784 FedWire (Same Day) Federal Reserve Wire Network - Priority transfer Same business day Medium
783 FedNow (Instant) Instant payment service (24/7/365) Real-time Higher

Important Notes for United States:

TypeOfPaymentID = 449 (ACH Transfer - United States)

Note: TypeOfPaymentID for ACH is 449. Use GetCurrencyTypesOfPayment to confirm your available IDs.

Required Fields:

Optional Fields:

Processing:

ABA Routing Number:

Common US Banks:

Notes:

Common Errors:

TypeOfPaymentID = 784 (FedWire Same Day - United States)

Note: TypeOfPaymentID for FedWire is typically 784. Use GetCurrencyTypesOfPayment to confirm your available IDs.

Required Fields:

Optional Fields:

Processing:

Notes:

TypeOfPaymentID = 783 (FedNow Instant - United States)

Note: TypeOfPaymentID for FedNow is typically 783. Use GetCurrencyTypesOfPayment to confirm your available IDs.

Required Fields:

Processing:

Notes:

US Bank Account Example:

<RecipientBankName>Chase Bank</RecipientBankName>
<RecipientBankRouting>021000021</RecipientBankRouting>
<RecipientBankAccountNo>123456789012</RecipientBankAccountNo>
<RecipientBankAccoutType>checking</RecipientBankAccoutType>
<TypeOfPaymentID>YOUR_PARTNER_ACH_ID</TypeOfPaymentID>

How to Get Your TypeOfPaymentID Values

Step 1: Call GetCurrencyTypesOfPayment with your credentials:

<GetCurrencyTypesOfPayment>
  <AgentID>YOUR_AGENT_ID</AgentID>
  <PartnerID>YOUR_PARTNER_ID</PartnerID>
  <SenderCountry>US</SenderCountry>
  <RecipientCountry>BR</RecipientCountry>
</GetCurrencyTypesOfPayment>

Step 2: Parse the response to get available TypeOfPaymentID values:

<PaymentMethod>
  <TypeOfPaymentID>31</TypeOfPaymentID>
  <TypeOfPaymentText>Bank Deposit (TED/DOC/PIX)</TypeOfPaymentText>
  <MaxAmountSent>10000.00</MaxAmountSent>
</PaymentMethod>

Step 3: Use the TypeOfPaymentID in CreateNewOrder

Best Practice: Cache TypeOfPaymentID values per corridor and refresh daily.

Request Examples

Example 1: Successful Bank Deposit to Brazil

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>
    <CreateNewOrder xmlns="http://mts.geobridge.org/">
      <!-- Authentication -->
      <AgentID>12345</AgentID>
      <PartnerID>100</PartnerID>
      <AgentOrderReference>REF-2025-001234</AgentOrderReference>
      <OrderCreationTime>2025-11-05T10:30:00</OrderCreationTime>

      <!-- Sender Information -->
      <SenderUID>SENDER-12345</SenderUID>
      <SenderFirstName>John</SenderFirstName>
      <SenderLastName>Smith</SenderLastName>
      <SenderAddress>123 Main Street</SenderAddress>
      <SenderCity>New York</SenderCity>
      <SenderState>NY</SenderState>
      <SenderZip>10001</SenderZip>
      <SenderCountry>US</SenderCountry>
      <SenderPhone1>2125551234</SenderPhone1>
      <SenderEmail>john.smith@email.com</SenderEmail>
      <SenderDateOfBirth>1980-05-15</SenderDateOfBirth>
      <SenderGender>M</SenderGender>
      <SenderDocument1Type>SSN</SenderDocument1Type>
      <SenderDocument1Number>123-45-6789</SenderDocument1Number>
      <SenderOccupation>Software Engineer</SenderOccupation>

      <!-- Recipient Information -->
      <RecipientUID>RECIPIENT-67890</RecipientUID>
      <RecipientFirstName>Maria</RecipientFirstName>
      <RecipientLastName>Silva</RecipientLastName>
      <RecipientAddress1>Rua das Flores, 456</RecipientAddress1>
      <RecipientCity>São Paulo</RecipientCity>
      <RecipientState>SP</RecipientState>
      <RecipientZip>01310-100</RecipientZip>
      <RecipientCountry>BR</RecipientCountry>
      <RecipientPhone1>11987654321</RecipientPhone1>
      <RecipientEmail>maria.silva@email.com</RecipientEmail>
      <RecipientDocument1Type>CPF</RecipientDocument1Type>
      <RecipientDocument1Number>123.456.789-00</RecipientDocument1Number>

      <!-- Bank Information -->
      <RecipientBankName>Banco do Brasil</RecipientBankName>
      <RecipientBankRouting>001</RecipientBankRouting>
      <RecipientBranchID>1234-5</RecipientBranchID>
      <RecipientBankAccountNo>12345678-9</RecipientBankAccountNo>
      <RecipientBankAccoutType>checking</RecipientBankAccoutType>

      <!-- Transaction Amounts -->
      <NetAmountSent>1000.00</NetAmountSent>
      <TotalFeeSender>15.00</TotalFeeSender>
      <TotalCollectedFromSender>1015.00</TotalCollectedFromSender>
      <ExchangeRateSender>5.25</ExchangeRateSender>
      <CurrencySent>USD</CurrencySent>
      <AmountReceived>5250.00</AmountReceived>
      <CurrencyOfPayment>BRL</CurrencyOfPayment>
      <CurrencyOfPaymentID>1</CurrencyOfPaymentID>

      <!-- Payment Method -->
      <TypeOfPaymentID>31</TypeOfPaymentID>
      <TypeOfPaymentText>Bank Deposit (TED/DOC/PIX)</TypeOfPaymentText>

      <!-- Compliance Information -->
      <RelationshipToSender>Sister</RelationshipToSender>
      <PurposeOfOrder>Family Support</PurposeOfOrder>
      <OrderFundSource>Salary</OrderFundSource>
    </CreateNewOrder>
  </soap:Body>
</soap:Envelope>

SOAP Response (Success - Auto-Released):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CreateNewOrderResponse xmlns="http://mts.geobridge.org/">
      <CreateNewOrderResult>
        <Order>
          <OrderID>987654321</OrderID>
          <AgentOrderReference>REF-2025-001234</AgentOrderReference>
          <OrderProcessingTime>2025-11-05T10:30:15</OrderProcessingTime>
          <OrderAcceptanceCode>A</OrderAcceptanceCode>
          <TransactionResult></TransactionResult>
          <ResultCodes>1050</ResultCodes>
          <AdditionalMessage>Order successfully created and auto-released for payment</AdditionalMessage>
          <StatusCode>3</StatusCode>
          <LastStatusUpdade>2025-11-05T10:30:15</LastStatusUpdade>
          <PaymentInstructions>Funds will be deposited to Banco do Brasil account ending in 8-9</PaymentInstructions>
        </Order>
      </CreateNewOrderResult>
    </CreateNewOrderResponse>
  </soap:Body>
</soap:Envelope>

Explanation:

Example 2: Order On Hold - OFAC Hit

SOAP Request: (Same as Example 1, but sender name matches OFAC list)

SOAP Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CreateNewOrderResponse xmlns="http://mts.geobridge.org/">
      <CreateNewOrderResult>
        <Order>
          <OrderID>987654322</OrderID>
          <AgentOrderReference>REF-2025-001235</AgentOrderReference>
          <OrderProcessingTime>2025-11-05T11:00:00</OrderProcessingTime>
          <OrderAcceptanceCode>A</OrderAcceptanceCode>
          <TransactionResult></TransactionResult>
          <ResultCodes>1051</ResultCodes>
          <AdditionalMessage>Order on hold for compliance review - OFAC screening detected potential match</AdditionalMessage>
          <StatusCode>2</StatusCode>
          <LastStatusUpdade>2025-11-05T11:00:05</LastStatusUpdade>
        </Order>
      </CreateNewOrderResult>
    </CreateNewOrderResponse>
  </soap:Body>
</soap:Envelope>

Explanation:

Example 3: Order with bank validation system Bank Validation Failure

SOAP Response:

<Order>
  <OrderID>987654323</OrderID>
  <AgentOrderReference>REF-2025-001236</AgentOrderReference>
  <OrderProcessingTime>2025-11-05T12:00:00</OrderProcessingTime>
  <OrderAcceptanceCode>A</OrderAcceptanceCode>
  <ResultCodes>1054</ResultCodes>
  <AdditionalMessage>Order on hold - Bank account validation failed. Please verify routing and account numbers.</AdditionalMessage>
  <StatusCode>2</StatusCode>
  <LastStatusUpdade>2025-11-05T12:00:10</LastStatusUpdade>
</Order>

Explanation:

Example 4: PIX Transfer via CPF Key (TypeOfPaymentID 42)

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>
    <CreateNewOrder xmlns="http://mts.geobridge.org/">
      <!-- Authentication -->
      <AgentID>12345</AgentID>
      <PartnerID>100</PartnerID>
      <AgentOrderReference>REF-2025-PIX-001</AgentOrderReference>
      <OrderCreationTime>2025-11-05T14:30:00</OrderCreationTime>

      <!-- Sender Information -->
      <SenderUID>SENDER-12345</SenderUID>
      <SenderFirstName>John</SenderFirstName>
      <SenderLastName>Smith</SenderLastName>
      <SenderAddress>123 Main Street</SenderAddress>
      <SenderCity>New York</SenderCity>
      <SenderState>NY</SenderState>
      <SenderZip>10001</SenderZip>
      <SenderCountry>US</SenderCountry>
      <SenderPhone1>2125551234</SenderPhone1>
      <SenderEmail>john.smith@email.com</SenderEmail>
      <SenderDateOfBirth>1980-05-15</SenderDateOfBirth>
      <SenderDocument1Type>SSN</SenderDocument1Type>
      <SenderDocument1Number>123-45-6789</SenderDocument1Number>

      <!-- Recipient Information -->
      <RecipientUID>RECIPIENT-PIX-001</RecipientUID>
      <RecipientFirstName>Carlos</RecipientFirstName>
      <RecipientLastName>Santos</RecipientLastName>
      <RecipientAddress1>Av. Paulista, 1000</RecipientAddress1>
      <RecipientCity>São Paulo</RecipientCity>
      <RecipientState>SP</RecipientState>
      <RecipientZip>01310-100</RecipientZip>
      <RecipientCountry>BR</RecipientCountry>
      <RecipientPhone1>11987654321</RecipientPhone1>
      <RecipientEmail>carlos.santos@email.com</RecipientEmail>
      <RecipientDocument1Type>CPF</RecipientDocument1Type>
      <RecipientDocument1Number>123.456.789-00</RecipientDocument1Number>

      <!-- PIX Information - NO BANK FIELDS -->
      <PixTypeId>CPF</PixTypeId>
      <PixId>12345678900</PixId>

      <!-- Transaction Amounts -->
      <NetAmountSent>500.00</NetAmountSent>
      <TotalFeeSender>10.00</TotalFeeSender>
      <TotalCollectedFromSender>510.00</TotalCollectedFromSender>
      <ExchangeRateSender>5.25</ExchangeRateSender>
      <CurrencySent>USD</CurrencySent>
      <AmountReceived>2625.00</AmountReceived>
      <CurrencyOfPayment>BRL</CurrencyOfPayment>
      <CurrencyOfPaymentID>1</CurrencyOfPaymentID>

      <!-- Payment Method - PIX -->
      <TypeOfPaymentID>42</TypeOfPaymentID>
      <TypeOfPaymentText>PIX</TypeOfPaymentText>

      <!-- Compliance Information -->
      <RelationshipToSender>Friend</RelationshipToSender>
      <PurposeOfOrder>Gift</PurposeOfOrder>
      <OrderFundSource>Savings</OrderFundSource>
    </CreateNewOrder>
  </soap:Body>
</soap:Envelope>

SOAP Response (Success):

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CreateNewOrderResponse xmlns="http://mts.geobridge.org/">
      <CreateNewOrderResult>
        <Order>
          <OrderID>987654324</OrderID>
          <AgentOrderReference>REF-2025-PIX-001</AgentOrderReference>
          <OrderProcessingTime>2025-11-05T14:30:08</OrderProcessingTime>
          <OrderAcceptanceCode>A</OrderAcceptanceCode>
          <TransactionResult></TransactionResult>
          <ResultCodes>1050</ResultCodes>
          <AdditionalMessage>PIX order successfully created and auto-released. Payment will be processed via PIX key (CPF)</AdditionalMessage>
          <StatusCode>3</StatusCode>
          <LastStatusUpdade>2025-11-05T14:30:08</LastStatusUpdade>
          <PaymentInstructions>Funds will be sent via PIX to CPF key ***.***.789-00</PaymentInstructions>
        </Order>
      </CreateNewOrderResult>
    </CreateNewOrderResponse>
  </soap:Body>
</soap:Envelope>

Explanation:

Important: When using TypeOfPaymentID 42 (PIX), you MUST NOT include any bank account fields. Only use PixTypeId and PixId.

Example 5: Error - Duplicate Order Reference

SOAP Request: (Using AgentOrderReference that already exists)

SOAP Response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>Duplicate order reference</faultstring>
      <detail>
        <ErrorCode>2001</ErrorCode>
        <ErrorMessage>AgentOrderReference 'REF-2025-001234' already exists. Please use a unique reference.</ErrorMessage>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Example 6: Error - Credit Limit Exceeded

SOAP Response:

<soap:Fault>
  <faultcode>soap:Server</faultcode>
  <faultstring>Credit limit exceeded</faultstring>
  <detail>
    <ErrorCode>4101</ErrorCode>
    <ErrorMessage>Your current credit limit is insufficient for this transaction. Current balance: $5,234.50. Order amount: $1,015.00. Available credit: $0.00. Please make a payment or contact finance to increase your limit.</ErrorMessage>
  </detail>
</soap:Fault>

Response Fields Explained

Order Identification

Field Description Example
OrderID Unique ID generated by MTS 987654321
AgentOrderReference Your reference (echoed back) "REF-2025-001234"
OrderProcessingTime When order was processed "2025-11-05T10:30:15"

Order Status

Field Description Values
OrderAcceptanceCode Was order accepted? "A" = Accepted, "R" = Rejected
StatusCode Current order status 1-8 (see Status Codes table)
ResultCodes Result code(s) "1001", "1050", "1051", etc.
AdditionalMessage Human-readable message Explanation or instructions

Payment Information

Field Description When Provided
PaymentInstructions Instructions for recipient All orders
PdfReceipt PDF receipt (base64) If enabled for your account

Error Response Example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Server</faultcode>
      <faultstring>Missing required field</faultstring>
      <detail>
        <ErrorCode>3001</ErrorCode>
        <ErrorMessage>Required field 'SenderDateOfBirth' is missing for US → BR corridor with amount > $1000</ErrorMessage>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Business Rules

Amount Limits

Corridor Min Amount Max Amount Notes
US → BR (Bank) $10.00 $10,000.00 Per transaction
US → BR (Cash) $10.00 $5,000.00 Per transaction

Note: Limits may vary by partner. Contact support for your specific limits.

Processing Time

Status Typical Duration Notes
Verifying (8) 5-30 minutes LexisNexis compliance check
On Hold (2) 1-24 hours Manual review required
Open (3) 10-60 minutes Sent to payer automatically
Processing (4) 5-120 minutes Payment in progress
Paid (5) Final Transaction complete

Integration Best Practices

1. Always Get Fresh Rates Before Creating Order

// ❌ BAD: Using old rates
const quote = await GetRatesAndCosts(params);
await showQuoteToCustomer(quote);
// ... customer takes 10 minutes to fill form ...
await CreateNewOrder({
  ...orderData,
  ExchangeRateSender: quote.ExchangeRateSender,
});

// ✅ GOOD: Get fresh rates immediately before creating order
const quote = await GetRatesAndCosts(params);
await showQuoteToCustomer(quote);
// ... customer fills form ...
const freshQuote = await GetRatesAndCosts(params);
await CreateNewOrder({
  ...orderData,
  ExchangeRateSender: freshQuote.ExchangeRateSender,
});

2. Use Unique AgentOrderReference

// Generate unique reference
function generateOrderReference() {
  const timestamp = Date.now();
  const random = Math.floor(Math.random() * 1000);
  return `ORD-${timestamp}-${random}`;
}

// Store in database to prevent duplicates
async function createOrder(orderData) {
  const reference = generateOrderReference();

  // Check if reference exists in your database
  const exists = await db.orders.findOne({ reference });
  if (exists) {
    return createOrder(orderData); // Regenerate
  }

  // Create order
  const result = await CreateNewOrder({
    ...orderData,
    AgentOrderReference: reference,
  });

  // Store in database
  await db.orders.insert({
    reference,
    pontualOrderId: result.OrderID,
    status: result.StatusCode,
  });

  return result;
}

5. Store OrderID for Future Reference

async function createAndStoreOrder(orderData) {
  try {
    const response = await CreateNewOrder(orderData);

    // Store in your database
    await db.orders.insert({
      agentOrderReference: orderData.AgentOrderReference,
      pontualOrderId: response.OrderID,
      status: response.StatusCode,
      statusText: getStatusText(response.StatusCode),
      resultCodes: response.ResultCodes,
      claimCode: response.OrderClaimCode,
      createdAt: new Date(),
      senderName: `${orderData.SenderFirstName} ${orderData.SenderLastName}`,
      recipientName: `${orderData.RecipientFirstName} ${orderData.RecipientLastName}`,
      amount: orderData.NetAmountSent,
      currency: orderData.CurrencySent,
    });

    return response;
  } catch (error) {
    // Log error
    await db.errors.insert({
      agentOrderReference: orderData.AgentOrderReference,
      errorCode: error.code,
      errorMessage: error.message,
      timestamp: new Date(),
    });

    throw error;
  }
}

Testing

Related Methods

Before calling CreateNewOrder:

After creating order:

Support

© 2025 Inter. All rights reserved.

Documentation v2.0 - Last Updated: November 5, 2025