# Initial Setup

This is the recommended starting point for every new ConnectPSP integration.

It consolidates the minimum setup required before you move to your first Cash-In or Cash-Out flow.

> ✅ **Use this page first** if you are still collecting credentials, choosing environments, or defining your webhook strategy.


## What you need from ConnectPSP

| Item | Purpose | Required for |
|  --- | --- | --- |
| `clientId` + `clientSecret` | Generate the JWT used in `Authorization` | All authenticated flows |
| `ApplicationToken` | Identifies your integration | All authenticated flows |
| `CryptoToken` | Generates `DigitalSignature` | Cash-Out and Rebalance |
| Webhook URL | Receives asynchronous events | Cash-In and Cash-Out confirmations |


## Step 1 — Choose the environment

| Environment | Base URL | Use it for |
|  --- | --- | --- |
| **Staging** | `https://api.homologacao.connectpsp.com` | Development, QA, and first end-to-end tests |
| **Production** | `https://api.connectpsp.com` | Real operations after validation and rollout approval |


Start in **staging** and keep production credentials isolated until your flows are fully validated.

## Step 2 — Store credentials securely

Keep all secrets server-side only.

- Never expose `clientSecret` or `CryptoToken` in browser or mobile code
- Use environment variables or a secret manager
- Rotate credentials according to your internal security policy
- Log request IDs and `externalReference`, but never raw secrets


## Step 3 — Generate your JWT token

Call `POST /auth/token` with the credentials provided during onboarding:


```bash
curl -X POST https://api.homologacao.connectpsp.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'
```

Save the returned `accessToken` and send it in the `Authorization` header of subsequent requests.

## Step 4 — Understand the required headers

For most authenticated requests, the minimum header set is:


```text
Authorization: Bearer <accessToken>
ApplicationToken: <your-app-token>
```

For sensitive operations like Cash-Out and Rebalance, you also need:


```text
DigitalSignature: <hmac-sha256>
```

See the [Authentication Guide](/guides/authentication) for complete signature examples in Node.js, Python, and cURL.

## Step 5 — Prepare your webhook endpoint

Both inbound and outbound flows are asynchronous. Your integration should be ready to receive events before you move to business validation.

Recommended webhook behaviors:

- Respond with `200 OK` quickly
- Process asynchronously in your application layer
- Use `externalReference` or internal transaction codes for reconciliation
- Record event timestamps and idempotently ignore duplicates


If you have not prepared webhook handling yet, review the [Webhooks Guide](/guides/webhooks) before production rollout.

## Step 6 — Pick your first validation flow

Choose one of these next steps:

- [**Your First Cash-In**](/tutorials/first-cash-in) — best for validating QR Code generation and webhook confirmation
- [**Your First Cash-Out**](/tutorials/first-cash-out) — best for validating DigitalSignature and async settlement


## Go-live checklist

- Credentials stored securely on the server side
- Staging flow validated end-to-end
- Webhook endpoint reachable from the public internet
- `X-Idempotency-Key` used on mutation endpoints
- Internal reconciliation key defined using `externalReference`
- Production environment separated from staging configuration


## Where to go next

- [Authentication Guide](/guides/authentication)
- [Webhooks Guide](/guides/webhooks)
- [Error Handling Guide](/guides/error-handling)
- [API Reference](/apis)