> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.yodl.me/api/mcp` to find what you need.

# Integrations

An **integration** is a wallet or app that embeds the Yodl SDK and wants payment data on its own backend.

This section is optional. The SDK ships the complete payment flow and needs no backend of yours to work. Everything here exists for when you want your own records.

## What you get

| Capability | What it does | You need |
| --- | --- | --- |
| [Payment notifications](/integrations/notifications) | We POST a signed snapshot whenever a payment's state or merchant data changes | An HTTPS endpoint and the webhook signing secret |
| [Payments API](/integrations/payments-api) | You query the payments made through your integration, newest first | The API secret |
| [Email attestation](/integrations/email-attestation) | Your users skip Yodl's email OTP because you already verified the address | A JWKS URL, and per-integration approval from us |

Notifications and the Payments API carry the same payment shape, so you parse one contract.

## The integration address

An integration is identified by an **integration address**: an EVM address (`0x` followed by 40 hex characters) that you pick and we register. It is used in three places:

* payments made through your app carry it in their on-chain metadata, which is how we attribute a payment to you
* it is the HTTP Basic **username** on every Payments API request
* it is the `iss` claim on every email attestation you sign

We store and match it lowercased. Use an address you control and will not reuse. A processor's own address cannot be registered.

## What we issue, what you provide

You provide:

| Item | Notes |
| --- | --- |
| Integration address | An EVM address you control |
| Label | A human name, for our operator tooling |
| Notification URL | Where we POST notifications. HTTPS only |
| JWKS URL | Only if you want email attestation. HTTPS only |

We issue:

| Item | Notes |
| --- | --- |
| Webhook signing secret | Verifies our notifications |
| API secret | The Basic password on Payments API requests |

## The two secrets

Both are opaque, high-entropy random strings, with opposite handling.

| | Webhook signing secret | API secret |
| --- | --- | --- |
| Direction | Yodl → you | You → Yodl |
| Purpose | Key for the HMAC on notifications we send you | Password for HTTP Basic on read requests you send us |
| Ever on the wire? | No | Yes, on every Payments API request |
| If leaked | Anyone can forge notifications to your endpoint | Anyone can read every payment made through your integration |

:::danger
Neither secret belongs in a mobile app, a browser bundle, or a repository. The API secret in particular travels on **every** Payments API request, so it must stay server-side. If either leaks, ask us to rotate it.
:::

## Getting started

Work through [onboarding](/integrations/onboarding) — nine steps from picking an address to reconciling payments.