Skip to main content
The Connect payment flow is the primary integration path for off-ramp payments — moving value from a Stellar wallet to a beneficiary’s bank account, mobile money wallet, or other payment destination.

​
Overview

The flow has nine steps, executed in order:

​
Prerequisites

  • A registered application with Stellar credentials and a connect secret
  • An authenticated Business session (OTP or OAuth)
  • A beneficiary with at least one payment destination

​
Step by step

1

List associations

Retrieve the associations (organisations) your application has access to:
curl -s https://api.zeam.money/gw/v1/business/association/all \
  -H "Authorization: Bearer $BUSINESS_TOKEN" | jq
Pick the associationId you want to operate with.
2

List wallets

Get the wallets available for that association:
curl -s https://api.zeam.money/gw/v1/business/wallet/association/$ASSOCIATION_ID \
  -H "Authorization: Bearer $BUSINESS_TOKEN" | jq
Select the wallet that holds the asset you want to send from.
3

Get the beneficiary

Look up the beneficiary who will receive the payment:
curl -s https://api.zeam.money/gw/v1/business/beneficiaries/$ASSOCIATION_ID/$BENEFICIARY_ID \
  -H "Authorization: Bearer $BUSINESS_TOKEN" | jq
The response includes the beneficiary’s payment destinations (bank accounts, mobile money wallets, etc.).
4

Authenticate for Connect

The Connect lane requires Ed25519 authentication with your application’s Stellar keypair:
# Use the Ed25519 flow from /authentication/ed25519-app-auth
# to obtain a Connect bearer token
5

Discover available connectors

Find which payment connectors can deliver to your beneficiary’s destination:
curl -s "https://api.zeam.money/gw/v1/business/beneficiaries/getAvailableConnectors/$ASSOCIATION_ID/$BENEFICIARY_ID/BANK" \
  -H "Authorization: Bearer $BUSINESS_TOKEN" | jq
The response lists connectors with their supported corridors, methods, and accepted assets.
6

Get a Connect quote

Request a quote from the selected connector:
curl -s -X POST https://api.zeam.money/gw/v1/connect-quote \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "connectorId": "'$CONNECTOR_ID'",
    "amount": "100.00",
    "currency": "USDC"
  }' | jq
The quote includes the exchange rate, fees, the destination amount, and a quoteId for execution.
7

Get a Stellar quote (if needed)

If your wallet holds a different asset than what the connector accepts, get an on-chain path-payment quote:
curl -s -X POST https://api.zeam.money/gw/v1/stellar/quote \
  -H "Authorization: Bearer $BUSINESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "fromAsset": "ZARZ:GABC...",
    "toAsset": "USDC:GABC...",
    "amount": "100.00"
  }' | jq
This returns the sendMax value needed for the Stellar transaction.
Skip this step if your wallet already holds the asset the connector accepts.
8

Execute the Stellar transaction

Fund the payment by sending the asset to the connector’s clearing account:
curl -s -X POST https://api.zeam.money/gw/v1/business/wallet/$WALLET_ID/transaction \
  -H "Authorization: Bearer $BUSINESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "toPublicKey": "'$CLEARING_ACCOUNT'",
    "fromAsset": "USDC:GABC...",
    "amount": "100.00"
  }' | jq
On success, you receive a Stellar transaction hash.
9

Execute the Connect payment

Finalize the off-ramp with the connector:
curl -s -X POST https://api.zeam.money/gw/v1/connect-execute \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "'$QUOTE_ID'",
    "txHash": "'$STELLAR_TX_HASH'"
  }' | jq
The response includes a transactionId and status for tracking.

​
Using the Go SDK

The SDK provides a ConnectPayment recipe that orchestrates all nine steps: 
import (
    "github.com/ZeamMoney/zeam-sdk-go/recipes"
    "github.com/ZeamMoney/zeam-sdk-go/stellar"
)

flow := recipes.NewConnectPayment(client, recipes.ConnectPaymentInput{
    BusinessSession:      businessSession,
    ApplicationSeed:      seed,
    ApplicationPublicKey: publicKey,
    AssociationID:        "assoc-uuid",
    WalletID:             "wallet-uuid",
    FundingAsset:         stellar.Asset{Code: "USDC", Issuer: "GABC..."},
    BeneficiaryID:        "beneficiary-uuid",
    Method:               "BANK",
    CountryISO:           "ZA",
    SendAmount:           "100.00",
})

result, err := flow.Do(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Payment %s: status=%s, tx=%s\n",
    result.ConnectTransactionID,
    result.ConnectStatus,
    result.StellarTxHash,
)
You can also drive each step individually to interleave your own UI or business logic between steps.

​
Tracking payment status

After execution, query the payment status: 
curl -s https://api.zeam.money/gw/v1/connect-status/$TRANSACTION_ID \
  -H "Authorization: Bearer $CONNECT_TOKEN" \
  -H "x-zeam-auth: $CONNECT_SECRET" | jq

​
Auth requirements

StepAuth required
Steps 1-3 (Business data)Business session (OTP or OAuth)
Step 4 (Ed25519 login)Stellar keypair
Steps 5-9 (Connect)Connect bearer + x-zeam-auth connect secret