Mesta Integration Workflow

Overview

This guide outlines the step-by-step process for integrating with Mesta's cross-border payment platform. Follow these steps to set up senders, beneficiaries, fetch quotes and initiate orders seamlessly.

Table of Contents

1. Authentication
2. Supported Digital Assets
   • Stablecoins and Networks
3. Payment Types
   • Bank Account Transfer
   • PIX (Brazil)
   • SPEI (Mexico)
   • Philippines Payment Methods
4. Validation Rules
5. Create Sender
6. Create Source Wallet (Web3 only)
7. Create Beneficiary
8. Create Quote
9. Create Order
10. Post-Order Creation Steps
    • Get Deposit Wallet Address
    • Getting Test Tokens
    • Order Status Monitoring
    • Fund Transfer Guidelines
    • Monitoring and Updates

Integration Steps

1. Authentication

Before you begin, ensure you have proper authentication credentials. Refer to the Quickstart Guide for detailed instructions on authenticating with the Mesta API.

2. Supported Digital Assets

Stablecoins and Networks (Web3)

3. Payment Types

4. Validation Rules

Before creating senders or beneficiaries, it's crucial to understand and validate the required fields based on the entity type, owner type, and country.

How to Use Validation Rules

1. For Senders:
   GET /v1/validation-rules/senders?ownerType=individual&country=PH GET /v1/validation-rules/senders?ownerType=business&country=PH
2. For Beneficiaries:
   GET /v1/validation-rules/beneficiaries?ownerType=individual&country=MX GET /v1/validation-rules/beneficiaries?ownerType=business&country=MX

Required Parameters

• ownerType: Type of owner (individual or business)
• country: ISO 3166-1 alpha-2 country code

Response Structure

The API returns:

• Required fields
• Document requirements
• Field formats and validations
• Country-specific requirements

5. Create Sender

To comply with regulatory requirements, Mesta needs to verify the sender of the funds.

Sender Types

State and Country Codes

1. State and Country Fields: The state and country fields in the address must be provided using standardized codes.
2. Country Codes: Use the ISO 3166-1 alpha-2 country codes listed here.
3. State Codes: Use the appropriate state or province codes as listed here.
4. Postal Codes:
   • Use the correct postal code format for each country
   • For countries where postal codes are not commonly used or available, use "00000" as the default value

Identity Document Images

1. The front and back fields in the identity object should contain the base64-encoded binary data of the front and back images of the identity document, respectively.
2. This encoding ensures that the image data is correctly transmitted and received by the API.

Sender Creation Process

1. Call the Create Sender API to initialize the sender profile.
2. For business senders, upload verification documents using the Upload Document API.
3. If applicable, provide UBO (Ultimate Beneficial Owner) details via the Create UBO API. UBO is mandatory for business senders.
4. Trigger the verification process using the Verify Sender API.

Verification Statuses

Sender Verification Status

When creating or retrieving a sender, the kyb:status field indicates their verification status:

🔄 Individual vs Business: Key Differences

👤 Individual Senders

Fast Track Verification

• ⚡️ Verification Process: Automatic verification
• 📄 UBO Requirement: No UBO information needed
• ⏱️ Timeline: Near-instant verification
• 🔄 Status Flow: unverified → approved

🏢 Business Senders

Enhanced Due Diligence

• 👥 Verification Process: Manual verification by Mesta team
• 📊 UBO Requirement: Must provide UBO information
• ⏳ Timeline: 1-2 business days
• 🔄 Status Flow: unverified → pending → approved/declined

💡

Pro Tip: Business senders must complete both document submission AND UBO registration before their status can be reviewed.

📌 Quick Reference

• Individual: Instant verification, no UBO needed
• Business: Manual review, UBO required

6. Create Source Wallet

For Web3 transactions, you need to register the source of funds by creating a source wallet.

Required Input:

• An array of objects, each containing:
  • address: The cyrpto address for fund transfers
  • chain: The associated blockchain network

7. Create Beneficiary

To facilitate fund transfers, Mesta requires information about the receiver.

Beneficiary Types

State and Country Codes

1. State and Country Fields: The state and country fields in the address must be provided using standardized codes.
2. Country Codes: Use the ISO 3166-1 alpha-2 country codes listed here.
3. State Codes: Use the appropriate state or province codes as listed here.

Payment Information

**Note: **The paymentType must be provided and must be one of the supported payment types as specified in the API reference.

🏦 Country-Specific Payment Types

• 🇺🇸 United States (US):

  • Payment Type: bank_account
  • Required: accountNumber, routingNumber

• 🇪🇺 European Union (EUR):

  • Payment Type: bank_account
  • Required: accountNumber (IBAN), BIC (Bank Identifier Code)
  • Supported in all EU member states

• 🇬🇧 United Kingdom (GB):

  • Payment Type: bank_account
  • Required: accountNumber, sortCode

• 🇧🇷 Brazil (BR):

  • Payment Type: pix
  • Required Fields:
    • pixKeyId
    • taxId

• 🇲🇽 Mexico (MX):

  • Payment Type: spei
  • Required Fields:
    • targetName
    • targetBankAccountId

• 🇵🇭 Philippines (PH):

  • Payment Types:
    • instapay (< 50,000)
    • swiftpay_pesonet (≥ 50,000)
  • Required Fields:
    • channelSubject
    • extendInfo
    • recipientAccountNumber
    • recipientName

• 🇨🇴 Colombia (CO):

  • Payment Type: bank_account
  • Required: accountNumber, accountType, bankId

• 🇮🇳 India (IN):

  • Payment Type: bank_account
  • Required: accountNumber, accountType, bankId, ifscCode

• 🇨🇦 Canada (CA):

  • Payment Type: bank_account
  • Required: accountNumber, accountType, bankId, branchCode (Combined format of Institution Number (3 digits) and Transit Number (5 digits) - Example: 00607621)

• 🇸🇬 Singapore (SG):

  • Payment Type: bank_account
  • Required: accountNumber, accountType, bankId

• All Other Countries:

  • Payment Type: bank_account
  • Required: accountNumber, accountType, bankId
  • bankDocumentNumber is required for Argentina (AR)

Note: Always check the validation rules endpoint for the most up-to-date requirements for each country.

Important Notes:

• bankId:
  • Fetch the bankId for a specific country using Banks end point.
  • Ensure you provide the accurate bank ID as per the Beneficiary Banks API for the respective country.
• Supported Payment Types:
  • The paymentType must match one of the supported payment types listed in the API reference for the specific country.
  • Field Requirements:
  • All fields listed under paymentInfo are mandatory unless specified otherwise.
  • Make sure to include all required information to avoid any processing delays.

Beneficiary Creation Process

1. Call the Create Beneficiary API to register the beneficiary.
2. Trigger the verification process using the Verify Beneficiary API.

Beneficiary Verification Status

Similar to senders, beneficiaries also have a verification status:

8. Create Quote

Before creating an order, create a quote for the order.

Required Fields:

• sourceCurrency
  • For Web2 merchants, sourceCurrency can only be USD.
  • For Web3 merchants, sourceCurrency can be any supported stablecoin (e.g., USDC, USDT on Ethereum (ETH), Polygon (POL/NPL)).
• targetCurrency
• targetAmount

Optional Fields:

• developerFee - Amount in source currency to be charged as developer fee (e.g., "1.50")
  • Must be a valid decimal number
  • Will be added to the gross source amount
  • Displayed separately in quote response

9. Create Order

After setting up the sender, beneficiary, and obtaining a quote, you can create an order to initiate the fund transfer.

Required Fields:

• senderId (from Create Sender API response)
• beneficiaryId (from Create Beneficiary API response)
• acceptedQuoteId (from Get Quote API response)

Order Status Flow

10. Post-Order Creation Steps

After creating an order, it's crucial to follow the correct process for sending funds. The order goes through several status changes, and timing is critical for successful processing.

A. Get Deposit Wallet Address

After order creation, fetch the correct deposit wallet address before sending any funds:

{
  "data": {
    "id": "4e2f085a-85c0-4de8-90fc-34e1dbe97be7",
    "address": "0xd4bDFcaDDFB326a954007d675A7738da4fBC576b",
    "chain": "polygon",
    "ownerType": "sender"
  }
}

Important Notes:

• Wallet addresses are order-specific
• Addresses expire with the order
• Different networks (⟠ ETH, ◈ POL) use different address formats
• Always verify the network matches your token type

B. Getting Test Tokens for Sandbox Testing

After obtaining the deposit wallet address, you'll need test tokens to simulate the payment flow in our sandbox environment.

Quick Reference

1. Enable Sepolia testnet in MetaMask
2. Get test ETH for gas fees
3. Obtain test USDC/USDT from faucets
4. Send to order's deposit wallet address

C. Order Status Monitoring

Important Status Transitions

1. Wait for "awaiting_funds" Status
   • After order creation, wait for status to change to "awaiting_funds"
   • Do not send funds before this status change
2. Time-Sensitive Window
   • Orders have a limited time window for fund receipt
   • If status changes to "awaiting_funds_timeout", funds will not be accepted
   • New order creation required if timeout occurs

D. Fund Transfer Guidelines

For Web2 Customers (Fiat)

• Send exact FIAT amount to designated bank account
• Amount must match order creation value
• Use provided bank details exactly as specified

For Web3 Customers (Stablecoin)

• Send exact stablecoin amount specified during order creation
• Use correct token type (USDC/USDT) as selected
• Ensure correct blockchain network (ETH,POL/NPL) is used
• Send to wallet address provided in order details

E. Monitoring and Updates

• Use the Get Order Status API to monitor progress
• Set up webhooks for real-time status updates
• Track order status through the dashboard
• For Web3 orders, monitor blockchain confirmations

Need Help?

If you encounter any issues or have questions, please refer to our API Documentation or contact our Support Team.