Partner Route Pilot Endpoint Test Pack

The Pilot

This endpoint test pack allows an approved partner to review a controlled UniBridge payout route before any production rollout.

The pilot is limited to route creation, route status review, and operational coordination with UniBridge.

This pilot is not a production API rollout.

All routes remain under controlled UniBridge review during the pilot phase.

What This Pack Covers

Create a controlled partner route
Receive a UniBridge-managed route_id
Review route status through the Partner Route Console
Optionally poll the route status endpoint
Share the route_id and external_reference with UniBridge for review

What This Pack Does Not Cover

Production payout volume
Full API reference access
Direct provider access
Provider credentials
Bulk payout creation
Webhook integration
Partner-controlled automated retries

Route Creation

Approved pilot partners can create a controlled UniBridge-managed payout route using the route creation endpoint.

Each request must include a partner identifier and a valid HMAC signature. The response returns a UniBridge-managed route_id, route status, and console access when available.

Endpoint

POST /v2/partner/routes

Required Headers

Content-Type: application/json
x-ub-partner-id: <partner_id>
x-ub-signature: <hmac_sha256_hex_signature>

Example Request

{
  "external_reference": "pilot_test_001",
  "source_country": "US",
  "destination_country": "BR",
  "amount": "100.00",
  "currency": "USD",
  "payout_rail": "pix",
  "destination": {
    "rail": "pix",
    "pix_key": "recipient@email.com"
  }
}

Use a new external_reference for each test.
Do not include credentials inside shared documents.
Share the returned route_id with UniBridge after testing.

Route Status Review

Partners may review the progress of a created route through the UniBridge Partner Route Console or through the optional route status endpoint.

The status endpoint is intended for controlled pilot review only.

Endpoint

GET /v2/partner/routes/{route_id}

Required Headers

x-ub-partner-id: <partner_id>
Authorization: Bearer <route_read_token>

Example Response

{
  "ok": true,
  "route": {
    "route_id": "sett_...",
    "external_reference": "pilot_test_001",
    "status": "funding_pending",
    "stage": "funding",
    "source_country": "US",
    "destination_country": "BR",
    "payout_rail": "pix"
  },
  "funding": {
    "status": "pending",
    "method": "sender",
    "asset": "USDT",
    "network": "polygon"
  },
  "execution": {
    "status": null,
    "provider_status": null,
    "provider_reference": null
  },
  "payout": {
    "status": "pending",
    "evidence_status": "not_available"
  },
  "attention_required": false,
  "mode": "pilot"
}

Use the route_id returned from route creation.
The read token is provided separately.
Partners can only access routes linked to their approved partner scope.
UniBridge may request the route_id and external_reference after the test.

Error Responses

Pilot endpoints return structured errors for authentication, read access, request validation, route selection, route lookup, and internal route preparation failures. Error details help approved partners debug pilot requests without exposing provider credentials or internal execution secrets.

Example Error Response

{
  "ok": false,
  "error": {
    "code": "invalid_hmac",
    "message": "Invalid HMAC signature"
  }
}

Code	HTTP	Meaning
missing_partner_id	401	x-ub-partner-id was not provided.
invalid_partner_id	401	The partner identifier format is invalid.
unknown_partner	401	The partner is not configured or approved for pilot access.
missing_hmac_signature	401	x-ub-signature was not provided on a route creation request.
invalid_hmac	401	The request signature could not be verified.
missing_partner_read_token	401	The bearer token for route status review was not provided.
invalid_partner_read_token	401	The bearer token is invalid for the requested partner scope.
invalid_body	400	The request body must be a valid JSON object.
missing_external_reference	400	external_reference is required for pilot route tracking.
missing_source_country	400	source_country or source_market is required.
missing_destination_country	400	destination_country, destination_market, or receiver_country is required.
invalid_amount	400	The amount must be a positive numeric value.
invalid_destination	400	destination or recipient must be a valid object.
no_routes_available	400	No controlled pilot route is available for the requested corridor.
invalid_route_selection	400	The requested route_id is not available for this pilot request.
no_route_for_requested_payout_rail	400	No approved route supports the requested payout_rail.
missing_route_id	400	A route_id is required for this status request.
route_not_found	404	The route was not found or is outside the approved partner scope.
missing_partner_context	401	The request could not be linked to an approved partner context.
partner_route_session_create_failed	500	UniBridge could not create the internal pilot route session.
quote_not_ready	500	The route quote could not be prepared for pilot review.
funding_instructions_failed	500	Funding instructions could not be prepared.
internal_error	500	An unexpected server error occurred.

Authentication errors are returned before route creation begins.
Route selection errors mean no approved pilot route matched the request.
Internal preparation errors do not expose provider credentials or execution secrets.
Production retry behavior, webhook errors, and automated recovery require separate approval.

Status Lifecycle

Each route moves through a controlled UniBridge-managed lifecycle.

The status shown to the partner is simplified for pilot review and does not expose internal provider logic or execution secrets.

route_lockedThe route has been created and locked.

funding_pendingUniBridge is waiting for funding.

funding_detectedFunding was detected.

execution_submittedLocal payout execution has been submitted.

payout_pendingPayout is processing.

payout_completedPayout completed.

manual_reviewThe route requires UniBridge review.

payout_failedThe route failed.

expiredThe route expired.

Partner-facing statuses are intended for operational review.
Internal routing, funding, execution, and provider details remain managed by UniBridge.
UniBridge may ask for the route_id when reviewing a pilot route.

Partner Test Steps

The pilot flow is intentionally limited to a controlled route review process. Partners may use the supplied Postman collection or their own internal tooling during the pilot.

Configure Credentials → Create Partner Route → Review Route Status → Share Route Reference

1. Configure Credentials

Add the following values privately:

partner_id
route_creation_secret
route_read_token

The partner_id is sent as x-ub-partner-id. The route_creation_secret is used to generate x-ub-signature. The route_read_token is used only for route status reads.

Credentials are transmitted separately from this document.

2. Create a Partner Route

Submit a route creation request using:

POST /v2/partner/routes

Store the returned route_id and external_reference.

3. Review Route Status

Review the route through the UniBridge Partner Route Console or the optional route status endpoint.

4. Share Route Reference with UniBridge

After testing, share the following with UniBridge for pilot review:

route_id
external_reference

All pilot routes remain under controlled UniBridge review.
The pilot is intended for operational validation only.
Production rollout requires separate approval and review.

Security & Credential Handling

This pilot pack does not include credentials, provider access, or production secrets.

All pilot credentials must be shared separately through a private channel.

Credential Rules

Do not place credentials inside this document.
Do not share credentials in public repositories.
Do not store credentials in shared tickets or open workspaces.
Do not forward credentials outside the approved pilot team.

Access Boundaries

UniBridge does not expose provider credentials.
UniBridge does not expose internal execution secrets.
Route access is limited to the approved partner scope.
Status access is limited to partner-owned routes.

Production Boundary

This pilot is for controlled route review only. Production rollout, production volume, webhook access, or broader API access require separate approval and review.

Lightweight pilot endpoint for approved partners.

The Pilot

What This Pack Covers

What This Pack Does Not Cover

Route Creation

Endpoint

Required Headers

Example Request

Route Status Review

Endpoint

Required Headers

Example Response

Error Responses

Example Error Response

Status Lifecycle

Partner Test Steps

1. Configure Credentials

2. Create a Partner Route

3. Review Route Status

4. Share Route Reference with UniBridge

Security & Credential Handling

Credential Rules

Access Boundaries

Production Boundary