E-Guard API Documentation

Welcome to the E-Guard Developer Platform. Build secure escrow services into your applications.

Secure Escrow

Protect buyers and sellers with our trusted third-party escrow service.

Easy Integration

RESTful API with comprehensive documentation and code examples.

Bank-Grade Security

SSL encryption and secure API keys protect all transactions.

Introduction

E-Guard is a full-stack escrow service platform designed to provide trust and security for transactions between buyers and sellers. It acts as a neutral third party that holds funds until all parties have fulfilled their obligations in a deal.

The E-Guard Public API allows third-party platforms (like marketplaces, service providers, and e-commerce sites) to programmatically access E-Guard's core functionalities. This enables our partners to offer secure, integrated escrow services directly within their own applications without needing to build the complex payment and dispute logic themselves.

Base URL

All API endpoints are relative to the base URL:

Base URLtext

https://eguard.ewalletly.com/api/public/v1

Rate Limits

To ensure fair usage and system stability, the E-Guard API implements the following rate limits:

Test Mode

• 1000 requests per hour
• 50 requests per minute
• No transaction limits

Live Mode

• 5000 requests per hour
• 100 requests per minute
• Based on your subscription plan

Note: Rate limit headers are included in all responses. When limits are exceeded, the API returns a 429 Too Many Requests status.

Authentication

The E-Guard API uses API Keys to authenticate requests. All API requests must be made over HTTPS and include a valid API key in the Authorization header.

Obtaining Your API Key

To get your API key, you must first create a Vendor Account on the E-Guard platform. Once your account is set up, you can navigate to the Developer section in your dashboard to generate your keys.

Steps to get your API key:

Visit eguard.ewalletly.com and create a vendor account
Complete the account verification process
Navigate to the Developer section in your dashboard
Generate your test and live API keys

Live vs. Test Modes

Every vendor account has access to two modes, each with its own set of API keys:

Live Mode

• For processing real transactions with real money
• Live keys are prefixed with sk_live_
• Requires completed verification
• All transactions are final

Test Mode

• For development and integration testing
• Test keys are prefixed with sk_test_
• Uses a sandboxed environment
• No real money is moved

Making Authenticated Requests

You must include your API key in the Authorization header using the Bearer scheme.

Authorization Headertext

Authorization: Bearer sk_test_your_secret_api_key_here

Example Request

cURL Examplebash

curl -X GET "https://eguard.ewalletly.com/api/public/v1/transactions" \
  -H "Authorization: Bearer sk_test_your_secret_api_key_here" \
  -H "Content-Type: application/json"

Important Security Notes

• Keep your API keys secure and never expose them in client-side code
• Use environment variables to store API keys in your applications
• Rotate your API keys regularly
• Requests without a valid key will receive a 401 Unauthorized error

Error Response

401 Unauthorized Responsejson

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The provided API key is invalid or missing from the Authorization header."
  }
}

Vendors

Manage vendor accounts and profiles. These endpoints handle the creation and management of vendor and user profiles.

Create a Vendor

POST/vendors

Creates a new vendor account. This is the starting point for registering a new seller from a partner platform.

Parameters

Name	Type	Required	Description
email	string	Yes	Valid email address for the vendor account
password	string	Yes	Strong password (minimum 8 characters)
firstName	string	Yes	Vendor's first name
lastName	string	Yes	Vendor's last name
businessName	string	Yes	Name of the vendor's business

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/vendors" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "new-vendor@example.com",
  "password": "a-strong-password123",
  "firstName": "John",
  "lastName": "Doe",
  "businessName": "JD Electronics"
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Vendor registered successfully. A verification email has been sent.",
    "userId": "cmf1234567890abcdef",
    "vendorId": "cmf0987654321fedcba"
  }
}

Get Public Vendor Profile

GET/vendors/{vendorId}/profile

Retrieves the public profile information for a vendor, including ratings and reviews.

Parameters

Name	Type	Required	Description
vendorId	string	Yes	The unique identifier for the vendor

Code Examples

curl -X GET "https://eguard.ewalletly.com/api/public/v1/vendors/{vendorId}/profile" \
  -H "Content-Type: application/json"

Response Example

Responsejson

{
  "success": true,
  "data": {
    "userId": "cmf1234567890abcdef",
    "businessName": "JD Electronics",
    "memberSince": "2025-09-17T10:30:00.000Z",
    "isVerified": true,
    "averageRating": 4.8,
    "totalReviews": 25,
    "reviews": {
      "items": [],
      "totalPages": 0,
      "totalCount": 0
    }
  }
}

Update Vendor Profile

PUT/vendors/{vendorId}/profile

Updates the vendor profile information. Only the vendor can update their own profile.

Parameters

Name	Type	Required	Description
vendorId	string	Yes	The unique identifier for the vendor
user	object	No	User information to update (phoneNumber, etc.)
vendorProfile	object	No	Vendor profile information to update

Code Examples

curl -X PUT "https://eguard.ewalletly.com/api/public/v1/vendors/{vendorId}/profile" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "user": {
    "phoneNumber": "08012345678"
  },
  "vendorProfile": {
    "businessAddress": "123 Commerce Way, Lagos"
  }
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Profile updated successfully.",
    "user": {
      "id": "cmf1234567890abcdef",
      "email": "vendor@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "08012345678"
    },
    "profile": {
      "id": "cmf0987654321fedcba",
      "businessName": "JD Electronics",
      "businessAddress": "123 Commerce Way, Lagos",
      "isVerified": true
    }
  }
}

Transactions

Manage escrow transactions between vendors and buyers. These endpoints handle the complete transaction lifecycle from creation to completion, including acceptance, rejection, delivery confirmation, and cancellation.

Create a Transaction

POST/transactions

Create a new escrow transaction between a vendor and buyer.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/transactions" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Sale of Macbook Pro",
  "currency": "NGN",
  "buyerEmail": "existing-buyer@example.com",
  "orderItems": [
    {
      "productName": "Macbook Pro 16-inch",
      "quantity": 1,
      "price": 1200000
    }
  ]
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Transaction created successfully. An invitation has been sent to the buyer.",
    "transactionId": "cmf...",
    "publicId": "sale-of-macbook-pro-...",
    "status": "AWAITING_PAYMENT",
    "shareableLink": "https://e-guard.com/deal/sale-of-macbook-pro-..."
  }
}

List Transactions

GET/transactions

Retrieve a paginated list of all transactions for the authenticated vendor.

Code Examples

curl -X GET "https://eguard.ewalletly.com/api/public/v1/transactions" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json"

Response Example

Responsejson

{
  "success": true,
  "data": {
    "deals": [
      {
        "id": "cmf...",
        "publicId": "sale-of-macbook-pro-...",
        "title": "Sale of Macbook Pro",
        "status": "AWAITING_PAYMENT",
        "totalAmount": 1200000,
        "currency": "NGN",
        "createdAt": "2025-09-17T10:30:00Z"
      }
    ],
    "totalDeals": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

Get Transaction Details

GET/transactions/{id}

Retrieve detailed information about a specific transaction.

Code Examples

curl -X GET "https://eguard.ewalletly.com/api/public/v1/transactions/{id}" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json"

Response Example

Responsejson

{
  "success": true,
  "data": {
    "id": "cmf...",
    "publicId": "sale-of-macbook-pro-...",
    "title": "Sale of Macbook Pro",
    "status": "AWAITING_PAYMENT",
    "totalAmount": 1200000,
    "currency": "NGN",
    "buyer": {
      "id": "cmf...",
      "email": "existing-buyer@example.com",
      "firstName": "Jane",
      "lastName": "Smith"
    },
    "vendor": {
      "id": "cmf...",
      "businessName": "JD Electronics"
    },
    "orderItems": [
      {
        "productName": "Macbook Pro 16-inch",
        "quantity": 1,
        "price": 1200000
      }
    ],
    "createdAt": "2025-09-17T10:30:00Z"
  }
}

Accept a Transaction

POST/transactions/{id}/accept

Accept a pending transaction invitation. Changes status to AWAITING_PAYMENT.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/transactions/{id}/accept" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "acceptorUserId": "cmf..."
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Transaction accepted successfully. Awaiting payment.",
    "transactionId": "cmf...",
    "status": "AWAITING_PAYMENT"
  }
}

Reject a Transaction

POST/transactions/{id}/reject

Reject a pending transaction invitation with a reason.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/transactions/{id}/reject" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "rejectorUserId": "cmf...",
  "reason": "The price listed in the deal is incorrect."
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Transaction rejected successfully.",
    "transactionId": "cmf...",
    "status": "REJECTED"
  }
}

Mark as Delivered

POST/transactions/{id}/deliver

Mark a transaction as delivered. Optionally include delivery notes and tracking information.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/transactions/{id}/deliver" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "deliveryNotes": "Shipped via GIG Logistics.",
  "trackingNumber": "GIGL123456"
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Transaction marked as delivered successfully.",
    "transactionId": "cmf...",
    "status": "DELIVERED"
  }
}

Confirm Receipt

POST/transactions/{id}/confirm-receipt

Confirm receipt of goods/services. This releases funds to the vendor and completes the transaction.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/transactions/{id}/confirm-receipt" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "buyerId": "cmf..."
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Transaction confirmed successfully. Funds have been released to the vendor.",
    "transactionId": "cmf...",
    "status": "COMPLETED"
  }
}

Cancel a Transaction

POST/transactions/{id}/cancel

Cancel a transaction with a reason. Available for transactions that haven't been completed.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/transactions/{id}/cancel" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "cancellerId": "cmf...",
  "reason": "The buyer is no longer interested in the item."
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Transaction cancelled successfully.",
    "transactionId": "cmf...",
    "status": "CANCELLED"
  }
}

Guest Checkout

Enable seamless transactions for first-time buyers who don't have an E-Guard account. This endpoint streamlines the onboarding process by automatically creating buyer accounts and initiating escrow deals in a single request.

Guest Flow Benefits

Perfect for marketplaces and platforms where buyers might be new to escrow services. Reduces friction while maintaining security and trust.

Guest Checkout

POST/guest-checkout

Create a transaction for first-time buyers who don't have an account. This endpoint automatically creates a buyer account and initiates an escrow deal.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/guest-checkout" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Purchase of Vintage Lamp",
  "currency": "NGN",
  "buyerEmail": "first-time-buyer@example.com",
  "orderItems": [
    {
      "productName": "Vintage Lamp",
      "quantity": 1,
      "price": 15000
    }
  ]
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Guest checkout successful. Buyer account created and deal initiated.",
    "buyerId": "cmf...",
    "userId": "cmf...",
    "dealId": "cmf...",
    "publicId": "purchase-of-vintage-lamp-...",
    "shareableLink": "https://e-guard.com/deal/purchase-of-vintage-lamp-..."
  }
}

Disputes & Reviews

Handle dispute resolution and manage review systems for completed transactions. These endpoints facilitate communication between parties and help maintain trust in the platform.

Dispute Management

When issues arise, disputes provide a structured way for parties to communicate and resolve problems.

Review System

Build trust through transparent reviews that help future buyers make informed decisions.

Dispute Management

Open a Dispute

POST/transactions/{id}/disputes

Open a dispute for a transaction when there are issues with the deal.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/transactions/{id}/disputes" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "disputerId": "cmf...",
  "reason": "Item Not as Described",
  "description": "The product received was a different color."
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Dispute opened successfully.",
    "disputeId": "cmf...",
    "transactionId": "cmf...",
    "status": "DISPUTED"
  }
}

List Disputes

GET/disputes

Retrieve a paginated list of all disputes for the authenticated user.

Code Examples

curl -X GET "https://eguard.ewalletly.com/api/public/v1/disputes" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json"

Response Example

Responsejson

{
  "success": true,
  "data": {
    "disputes": [
      {
        "id": "cmf...",
        "transactionId": "cmf...",
        "disputerId": "cmf...",
        "reason": "Item Not as Described",
        "status": "OPEN",
        "createdAt": "2025-09-17T10:30:00Z"
      }
    ],
    "totalDisputes": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

Get Dispute Details

GET/disputes/{disputeId}

Retrieve detailed information about a specific dispute, including message logs.

Code Examples

curl -X GET "https://eguard.ewalletly.com/api/public/v1/disputes/{disputeId}" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json"

Response Example

Responsejson

{
  "success": true,
  "data": {
    "id": "cmf...",
    "transactionId": "cmf...",
    "transaction": {
      "title": "Sale of Macbook Pro",
      "publicId": "sale-of-macbook-pro-..."
    },
    "disputerId": "cmf...",
    "reason": "Item Not as Described",
    "description": "The product received was a different color.",
    "status": "OPEN",
    "messages": [
      {
        "id": "cmf...",
        "senderId": "cmf...",
        "message": "Here are photos showing the discrepancy.",
        "createdAt": "2025-09-17T11:00:00Z"
      }
    ],
    "createdAt": "2025-09-17T10:30:00Z"
  }
}

Add Dispute Message

POST/disputes/{disputeId}/messages

Add a message to an existing dispute for communication between parties.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/disputes/{disputeId}/messages" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "senderId": "cmf...",
  "message": "Here are photos showing the discrepancy."
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Message added to dispute successfully.",
    "disputeLogEntry": {
      "id": "cmf...",
      "senderId": "cmf...",
      "message": "Here are photos showing the discrepancy.",
      "createdAt": "2025-09-17T11:00:00Z"
    }
  }
}

Review System

Submit a Review

POST/transactions/{id}/reviews

Submit a review for a completed transaction to rate the vendor.

Code Examples

curl -X POST "https://eguard.ewalletly.com/api/public/v1/transactions/{id}/reviews" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "reviewerId": "cmf...",
  "rating": 5,
  "comment": "Excellent and smooth transaction!"
}'

Response Example

Responsejson

{
  "success": true,
  "data": {
    "message": "Review submitted successfully.",
    "reviewId": "cmf..."
  }
}

List Vendor Reviews

GET/vendors/{vendorId}/reviews

Retrieve paginated reviews for a specific vendor.

Code Examples

curl -X GET "https://eguard.ewalletly.com/api/public/v1/vendors/{vendorId}/reviews" \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json"

Response Example

Responsejson

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "cmf...",
        "reviewerId": "cmf...",
        "reviewer": {
          "firstName": "Jane",
          "lastName": "Smith"
        },
        "rating": 5,
        "comment": "Excellent and smooth transaction!",
        "createdAt": "2025-09-17T10:30:00Z"
      }
    ],
    "totalReviews": 1,
    "averageRating": 5,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

Error Handling

The E-Guard API uses conventional HTTP response codes to indicate the success or failure of API requests. All error responses follow a consistent format to help you handle errors programmatically.

Error Response Format

All error responses include a success: false field and an error object with detailed information.

HTTP Status Codes

400

Bad Request

The request was malformed or missing required parameters.

Example Response:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      {
        "field": "email",
        "message": "Valid email is required"
      },
      {
        "field": "amount",
        "message": "Amount must be greater than 0"
      }
    ]
  }
}

401

Unauthorized

Authentication failed or API key is invalid.

Example Response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403

Forbidden

The request is valid but the server is refusing to process it.

Example Response:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to access this resource"
  }
}

404

Not Found

The requested resource could not be found.

Example Response:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction not found"
  }
}

409

Conflict

The request conflicts with the current state of the resource.

Example Response:

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Transaction is already completed and cannot be modified"
  }
}

422

Unprocessable Entity

The request was well-formed but contains semantic errors.

Example Response:

{
  "success": false,
  "error": {
    "code": "BUSINESS_LOGIC_ERROR",
    "message": "Cannot cancel a transaction that has already been delivered"
  }
}

429

Too Many Requests

Rate limit exceeded. Please wait before making another request.

Example Response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds.",
    "retryAfter": 60
  }
}

500

Internal Server Error

An unexpected error occurred on the server.

Example Response:

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later."
  }
}

Common Error Codes

These are the most common error codes you'll encounter when integrating with the E-Guard API:

VALIDATION_ERROR

Request validation failed due to invalid or missing data.

UNAUTHORIZED

Invalid or missing authentication credentials.

FORBIDDEN

Insufficient permissions for the requested operation.

NOT_FOUND

The requested resource does not exist.

CONFLICT

Request conflicts with current resource state.

BUSINESS_LOGIC_ERROR

Operation not allowed due to business rules.

RATE_LIMIT_EXCEEDED

API rate limit has been exceeded.

INTERNAL_ERROR

Unexpected server error occurred.

Best Practices

Always check the success field in responses before processing data.
Handle validation errors by checking the details array for field-specific issues.
Implement exponential backoff for rate limit errors using the retryAfter value.
Log error codes and messages for debugging and monitoring purposes.
Provide meaningful error messages to end users based on the error codes received.