Milestone Payment Integration

This guide provides all the technical steps and API endpoint specifications required to seamlessly integrate the GoWit milestone payment system into your marketplace. By following this guide, you will enable sellers on your platform to effectively utilize milestone payments.

1. Getting Started

GoWit's milestone payment solution allows sellers in your marketplace to manage their balances more efficiently. This integration works through server-to-server communication between the GoWit platform and your marketplace platform. The process involves transferring a balance from an advertiser on GoWit's platform to a seller's account on your marketplace as a "milestone."

This document explains how the integration works, which API endpoints you need to provide, and what steps to take in case of potential errors.

2. Integration Flow Overview

The milestone payment integration involves seamless server-to-server communication between GoWit and your marketplace.

When a milestone payment is initiated:

1. Balance Check: GoWit checks the advertiser’s available balance via your marketplace API.
2. If Balance is Sufficient: If your marketplace API returns a positive response, GoWit sets aside the requested balance amount in our system.
3. Transaction Approval: GoWit sends a "Transaction Approval" request to your API to signal that the requested amount can now be added to the seller's marketplace account.
4. Balance Update: Upon receiving this confirmation, GoWit updates the advertisers's balance in our system.
5. Rollback: If an error occurs at any point, no balance update is performed in GoWit.

3. API Authentication

To ensure secure and authorized access to the marketplace’s API endpoints, each marketplace integrating with GoWit must authenticate directly with its own API. Marketplaces can choose whichever of their API’s supported methods best fits their security and integration needs.

Authentication Types

1. API Key

   • Include your API key in the headers of your API requests to authenticate each call.
   • Example:

     Authorization: Bearer YOUR_API_KEY

2. Basic Auth (Username & Password)

   • Provide your username and password as a base64-encoded string in the Authorization header.
   • Example:

     Authorization: Basic BASE64_ENCODED_USERNAME_PASSWORD

3. JWT (JSON Web Token)

   • Include a valid JWT token in the Authorization header for each request.
   • Example:

     Authorization: Bearer YOUR_JWT_TOKEN

Note:
The example requests in the following sections demonstrate authentication using the API Key method.

4. API Endpoint Specifications

For the integration, your marketplace is required to provide the following API endpoints.

Check Balance Endpoint

The Check Balance API endpoint allows our platform to programmatically verify the available balance for a seller on an external marketplace before processing a milestone payment.

When a milestone payment is initiated, our system sends a request to the relevant marketplace's API to check the seller’s current balance. This server-to-server integration ensures there are sufficient balance before the payment process continues.

Request Specification:

• Method: POST
• Endpoint: MARKETPLACE_CHECK_BALANCE_ENDPOINT
• Sample Request Body:

  {
    "external_advertiser_id": "string",
    "amount": 150.00
  }

• Sample Success Response:

  {
    "isSufficientBalance": true
  }

Transaction Approval Endpoint

The Transaction Approval API endpoint is a crucial step in the milestone payment process. After the seller’s balance is confirmed, this endpoint is used to approve the transaction.

Request Specification:

• Method: POST
• Endpoint: MARKETPLACE_TRANSACTION_SUCCESS_ENDPOINT
• Body:

  {
    "external_advertiser_id": "string",
    "transactionId": "string",
    "amount": 10,
  }

This endpoint confirms the release of amount to the seller for the approved milestone payment.

Note:
Depending on the marketplace API requirements, include the advertiserId and/or transactionId either in the request body or within the endpoint URL.

Required Environment Variables

Configure the following environment variables according to your chosen authentication type and marketplace integration:

Variable	Description
MARKETPLACE_CLIENT_API_KEY	API key for marketplace requests
MARKETPLACE_CLIENT_USERNAME	Username for Basic Auth
MARKETPLACE_CLIENT_PASSWORD	Password for Basic Auth
MARKETPLACE_JWT_SECRET	Secret key for signing JWT tokens
MARKETPLACE_CHECK_BALANCE_ENDPOINT	Marketplace balance check endpoint
MARKETPLACE_TRANSACTION_SUCCESS_ENDPOINT	Marketplace transaction approval endpoint

Note:
Depending on your marketplace integration and authentication method, only a subset of these variables may be required.

5. Error Handling and Rollback Scenarios

If the add-balance request completes successfully, GoWit will add the specified amount to the seller’s account. If any error occurs, the request returns an error message and no balance is added.

Failure Scenario	Description and Required Action
Check Balance Fails	If your API responds with 4xx/5xx to the balance-check step, no balance is added.
Transaction Approval Fails	If your API responds with 4xx/5xx when GoWit attempts to add the balance, no balance is added.
GoWit Internal Error (Post-Balance)	If GoWit encounters an internal error after checking balance but before adding it, no balance is added.

Typical error responses include:

• 400 Bad Request: The request contains invalid or missing parameters, or corresponds to one of the failure scenarios above.
• 403 Forbidden: Access denied for the specified advertiser.
• 500 Internal Server Error: Unexpected error on the server side.

In all cases, GoWit includes a clear, human-readable message in the response body to help diagnose and correct the issue.

6. Integration Checklist and Next Steps

Before starting the integration process, please review the following steps and be prepared:

• Determine your preferred API authentication method (API Key, Basic Auth, or JWT).
• Prepare the necessary credentials for your chosen method.
• Develop and test the three API endpoints specified in this document (Check Balance, Transaction Approval, Transaction Rollback) on your platform.
• Be ready to share the full URLs of your endpoints and the required environment variables with the GoWit team.

Our team at GoWit will support you throughout the onboarding process to ensure a smooth and successful integration. Thank you for your partnership.