Make your first transaction

An end-to-end path from sandbox credentials to an executed payment with status tracking.

This guide walks the full flow in the sandbox: authenticate, set up the context, quote, initiate an intent, execute a payment, and track it to completion.

This walkthrough is a scaffold. The structure and endpoints are correct; the worked request and response examples are still being finalised and are marked with TODO.

1. Prerequisites

   Before you start, make sure you have:

   • Sandbox application credentials (client ID, client secret, application secret). See API keys.
   • A server-side environment to hold secrets and make requests.
   • Optional: a public https endpoint if you want to receive webhook updates during the walkthrough.
2. Obtain sandbox credentials

   Confirm your credentials work against the sandbox base URL https://api.dev.zeam.paytec.io/v1. If you do not have credentials, ask your association administrator to register an application.

3. Configure authentication

   Issue an access token with POST /v1/auth/token, then send it with your application secret on every call.

   cURL

   curl -sS https://api.dev.zeam.paytec.io/v1/auth/token \
     -H "Content-Type: application/json" \
     -d '{ "clientId": "…", "clientSecret": "$ZEAM_CLIENT_SECRET" }'
   
4. Select the wallet and beneficiary context

   List your wallets and beneficiaries, or create what you need.

   • GET /v1/wallets, choose a source wallet (or POST /v1/wallets to create one).
   • GET /v1/beneficiaries, choose a destination (or POST /v1/beneficiaries to add one).
5. Discover a connector and request a quote

   Discover the connector for your corridor, then request a quote.

   • GET /v1/connectors?country=…&method=…&direction=…
   • POST /v1/quotes with the chosen connectorId, amount, and direction.
6. Initiate a transaction intent

   Create the intent that describes the transaction with POST /v1/intents. Keep the returned intentId.

7. Execute the payment

   Execute the intent as a payment with POST /v1/payments. The gateway accepts it for processing and returns a status.

8. Track the transaction status

   Poll the intent state with GET /v1/intents/{intentId} until it reaches a terminal state.

9. Receive webhook updates

   Instead of polling, subscribe to payment-intent events so Zeam notifies your endpoint as the state changes. Register your endpoint in the business portal. See Webhooks.

10. Prepare for production

    When the flow works end to end in the sandbox, review Production promotion. Switch the base URL and production credentials through configuration, not code.

Related

API concepts

The intent-then-payment model in context.

API reference

Exact request and response shapes for each step.