Milestone Payment Integration

This section describes how partners can enable milestone payments so sellers can fund campaigns directly from their sales earnings.

Use Case

Allow sellers to finance advertising campaigns using their accumulated commission or wallet balance.
Reduces friction by keeping funds within the ecosystem rather than requiring external payment channels.

How It Works

Funding API Exposure: Partner provides a dedicated funding API endpoint for advertisers to be used.
Balance Transfer: When a seller chooses this payment method, the GoWit system triggers a transfer from the seller’s internal wallet to the advertiser account using the funding API.
Accounting: Funds are deducted from the seller’s wallet balance and credited to the advertiser account for campaign spend.

UI Impact

The “Load Balance” interface should display a new Payment Method option labeled “Wallet” (or similar) to indicate funding from sales earnings.
Selecting this option initiates the balance-transfer flow described above.

Integration Flow Overview

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

When a milestone payment is initiated:

Balance Check: GoWit checks the advertiser’s available balance via your marketplace funding API.
If Balance is Sufficient: If your marketplace API returns a positive response, GoWit sets aside the requested balance amount in our system.
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.
Balance Update: Upon receiving approval confirmation, GoWit updates the advertisers's balance in our system.
Rollback: If an error occurs at any point, no balance update is performed in GoWit.

API Endpoint Specifications

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

Note:
The described request and response models reflect one viable approach; you may require alternative payloads depending on your specific requirements.

Authentication

GoWit authenticates directly with each marketplace’s API to ensure secure and authorized access to their API endpoints.
In this process, the marketplace must provide GoWit with its API authentication credentials (e.g., API key, username/password, or JWT token).
GoWit can integrate using any of the authentication methods supported by the marketplace’s API.

Authentication Types

API Key
- The marketplace provides an API key to GoWit.
- GoWit includes this key in the headers of its API requests to authenticate each call.
- Example:
```
Authorization: MARKETPLACE_API_KEY
```
Basic Auth (Username & Password)
- The marketplace shares a username and password for API access.
- GoWit encodes these credentials in Base64 format and includes them in the Authorization header.
- Example:
```
Authorization: Basic BASE64_ENCODED_USERNAME_PASSWORD
```
JWT (JSON Web Token)
- If the marketplace supports JWT-based authentication, GoWit includes a valid JWT token in the Authorization header for each request.
- Example:
```
Authorization: Bearer MARKETPLACE_JWT_TOKEN
```

Note:
The example requests in the following sections demonstrate authentication using the API Key method. However, GoWit can support any authentication type provided by the marketplace.

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
}

Responses:

200 - Success Response:

{
  "is_sufficient_balance": true
}

or if balance is insufficient:

{
  "is_sufficient_balance": false
}

400 - Bad Request:

{
  "error": "Invalid request parameters",
  "message": "Amount must be a positive number"
}

401 - Unauthorized:

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication credentials"
}

500 - Internal Server Error:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred while checking balance"
}

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

Sample Request Body:

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

Responses:

200 - Success Response:

{
  "success": true,
  "transactionId": "string",
  "message": "Transaction approved successfully"
}

400 - Bad Request:

{
  "error": "Invalid request parameters",
  "message": "Transaction ID is required"
}

401 - Unauthorized:

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication credentials"
}

500 - Internal Server Error:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred while processing the transaction"
}

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

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.

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 two API endpoints specified in this document (Check Balance, Transaction Approval) 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.

Use Case​

How It Works​

UI Impact​

Integration Flow Overview​

API Endpoint Specifications​

Authentication​

Authentication Types​

Check Balance Endpoint​

Transaction Approval Endpoint​

Error Handling and Rollback Scenarios​

Integration Checklist and Next Steps​