# Branta

Docs for integrating Branta.


# Setup

### [Send](/setup/send)

* **Account required:** None.
* **Integration:** Drop in the [SDK](/tech/sdk) and make one API call from your send flow.

### [Receive](/setup/receive)

* **Account required:** Yes — sign up at [guardrail.branta.pro](https://guardrail.branta.pro).
* **Integration:** Use an [Integration](/setup/receive/integrations) or build a [Custom Integration](/setup/receive/custom-integration) using the SDKs or API.


# Send

### Before send

When the user scans a QR or pastes a destination, pass that string to the SDK. Scan and paste are the same call. No Branta account.

Install from the [SDK](/tech/sdk) page. Use [staging](/tech/environments) until you go live.

| Destination                 | Pass                                                                                |
| --------------------------- | ----------------------------------------------------------------------------------- |
| On-chain Bitcoin            | A `bitcoin:` URI with `branta_id` and `branta_secret`. A bare address is `unknown`. |
| bolt11, Ark, silent payment | The value (`ark1` / `tark1`, `sp1` / `tsp1`).                                       |
| Unified BIP-21              | The full URI. Do not split.                                                         |

### Status handling

| Status       | When                         | Do                                                                    |
| ------------ | ---------------------------- | --------------------------------------------------------------------- |
| `match`      | Destination is in Branta     | Show name and logo. Link to `verifyUrl`.                              |
| `unknown`    | Not in Branta, including 404 | Show nothing.                                                         |
| `tampered`   | Destination was altered      | Warn. Do not show a verified card.                                    |
| `incomplete` | 5xx, 429, or unreachable     | Tell the user Branta could not complete the check. Do not block send. |

### Payment history

Once a payment resolves to a counterparty, render the counterparty name and logo in your transaction history, too.

**This is recommended for all send integrations:**

* **Persist at send time.** When the send-flow lookup returns a `match`, store the counterparty `name` and `logo` on your transaction record. History rendering is then a local read — no extra network calls, and it works offline.
* **Make it searchable.** Include the stored counterparty `name` in whatever your history search already indexes. Search stays local — the field is already on the record.

### Test your integration

Scan the [production](/setup/send/production) or [staging](/setup/send/staging) QR codes. Match the environment your SDK is pointed at. Each tab says the status to expect.

After a `match`, confirm the counterparty still shows in payment history, and that searching for that name finds it.


# Production

**Scanner:** <https://scan.branta.pro/scan?environment=production>

{% hint style="info" %}
Query param values in `bitcoin:` URIs are URI-encoded.
{% endhint %}

## Match

{% tabs %}
{% tab title="Bitcoin address" %}
`match` — show the counterparty name and logo.

[Open verify page](https://guardrail.branta.pro/v2/verify/Qy4e3KJ9yRs%2BVWq59aSTC6o%2F6vbCnw0v7ZutEs1mxjpGM2i5DgVVl7G0TwFO9CqQ1ws3zNqogQu%2B2%2Bx3U%2BQ8%2FSZtwgjezw%3D%3D#k-099d25=f9b0fd20-b402-4cd2-b68f-3ae3db52dbf5)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-b449beeca14028369dd461eea2310bdb18ee3785%2FProduction-ZK-On-Chain-QR.png?alt=media" alt="" width="563"><figcaption><p><code>bitcoin:bc1q6745z6cy3u0k9nprurh3x804c4r7u3u8vxca2n?branta_id=Qy4e3KJ9yRs%2BVWq59aSTC6o%2F6vbCnw0v7ZutEs1mxjpGM2i5DgVVl7G0TwFO9CqQ1ws3zNqogQu%2B2%2Bx3U%2BQ8%2FSZtwgjezw%3D%3D&#x26;branta_secret=f9b0fd20-b402-4cd2-b68f-3ae3db52dbf5</code></p></figcaption></figure>
{% endtab %}

{% tab title="bolt11" %}
`match` — show the counterparty name and logo.

[Open verify page](https://guardrail.branta.pro/v2/verify/6x8c86cTKdFrl0bCX1DmJvEMtmQUjOKKasBHbvlhj%2FZ0zSp6KCMXrLWpMLfCrwYlDDeb%2Bj0KmxDam5wSXl2wtkkUAU0YZ4TuWWC9zQJ0RpCi1R1M%2Bamr2kJGPsoS5wRmJ4%2BwkQBnTdLpNEXT8BqySNnfsZOSjD3a%2FvsCO2EjKPp7Osekzl%2BpiwJowGyTuXnuBnpHCIEXcj7hVrcCYyXGVnnDCR5AxqTyj%2B3wVXBLIGpb33EUXrL69%2FaLjLgdHaCOdYkIbvQR0AkE7iEWeGezJVKRlfz9sxL3%2BcdpCZnfn%2Ffa1R9%2BEof7C6YZ0ItgSOCcyhS6rUKiDQNLqI0epgDjOi4sd5iQlW1fuKptwo5k2Dj2IYFd1rhnKf%2BPJOJ0r6bHL8fCDYh78bEYuhtczTvCu0XpDSITSrAeF9zvpintzxwLG2ufm4pZtHAY5YI90oSI940JMf1oFL0T8busTOZCTvYLni1Ihz9z4KePhWBqB6u%2Fjo47Lw%3D%3D#k-b1b5c4=3DEFD9BAB71B35696C84E03A2E9A51F69640324BE589F8A7110F7E4A47DACF4D)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-7994c1c58077ef2407e84a5532fa5a399f91bcf6%2FProduction-ZK-Lightning-QR.png?alt=media" alt=""><figcaption><p><code>lightning:lnbc17760n1p4r4flypp5k56kq3v2935rl3glkqu9vngfueud2zj87hjcff3t0kn0yrge0pfqdzjgfexzmn5vysz6gzyv4mx2mr0wpjhygzvd9nksarwd9hxwgz6v4ex7gztdehhwmr9v3nk2gz90psk6urvv5cqzzsxq97zvuqsp5hut3t0l0s5mvp9yr06v4253kqtf452z6c65s6g9sga445hc03v6s9qxpqysgqqm430zkk9uymjgvllr3aha88hc6q59etxasfqswn8r8pfm3dstlpp46azv906xtcj3wzprxup5fxn65a5wymt7zzq9sw9qdzx8rgdhcpk80nrg</code></p></figcaption></figure>
{% endtab %}

{% tab title="Unified" %}
`match` — show the counterparty name and logo. Bitcoin address + `lightning=` bolt11 + `branta_id` / `branta_secret` (the BIP-21 shape POS like BTCPay emit). Pass the full URI through; do not split it before lookup.

[Open verify page](https://guardrail.branta.pro/v2/verify/%2BbcErHkjD6aDfvhegd1CPRgQQwes64aMIqPXCRBVKP88d982zJt7TUHTq%2B11O9ij9HFzXC%2BTvh%2ByFoECrvZKpv%2FVuGGLIA%3D%3D#k-a1f41e=c4ba0501-059e-459b-9b11-64d97f158291\&k-4c6654=DDFEC06A6D08514776F6F22EE1F6DB9D9119A55806E9C1DE0453C2A6376D281E)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-071b8ea06f0e578fc18251f9603b6e01cd24acb7%2FProduction-ZK-Unified-QR.png?alt=media" alt=""><figcaption><p><code>bitcoin:bc1qu3k6geqdjncaarsu2vq56tt8php5vsug9kasmq?lightning=lnbc17760n1p4r4tqupp5yuapqmxldkc8smuwa6t8shkdg9gezulu0vc7htepfsvweph8kqfsdphgfexzmn5vysygetkv4kx7ur9wgsyc6t8dp6xu6twvusy27rpd4cxcegcqzzsxq97zvuqsp53564rg6w4xjqy7jamcfqxyy83a0j8nzfs0wpevs37t5ln49q6hrs9qxpqysgq47hpqmv34g25le8sceq9jdvul2nz7ucyu0vucv56nlfe40x7n3jsu8duxjrn6tgvdspt872crk9zeatafznm9c57m039z7wyx6g3njsqkchkdh&#x26;branta_id=%2BbcErHkjD6aDfvhegd1CPRgQQwes64aMIqPXCRBVKP88d982zJt7TUHTq%2B11O9ij9HFzXC%2BTvh%2ByFoECrvZKpv%2FVuGGLIA%3D%3D&#x26;branta_secret=c4ba0501-059e-459b-9b11-64d97f158291</code></p></figcaption></figure>
{% endtab %}
{% endtabs %}

## Not a match

{% tabs %}
{% tab title="Not found" %}
An unregistered destination. `unknown` — show nothing.

[Open verify page](https://guardrail.branta.pro/v2/verify/bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-e7222bb311ae73b531a7e510ac969fce86f7fe19%2FStaging-Not-Found-QR.png?alt=media" alt=""><figcaption><p><code>bitcoin:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4</code></p></figcaption></figure>
{% endtab %}

{% tab title="Tampered" %}
A QR whose visible address was swapped while `branta_id` / `branta_secret` still point at a registered payment — the address in the `bitcoin:` URI is the **Not found** address above, with params copied from **Bitcoin address**.

`tampered` — warn. Do not show a verified card.

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-8a22c1715c762aa1133579e559dbe52611e2a70d%2FProduction-Tampered-QR.png?alt=media" alt="" width="563"><figcaption><p><code>bitcoin:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4?branta_id=Qy4e3KJ9yRs%2BVWq59aSTC6o%2F6vbCnw0v7ZutEs1mxjpGM2i5DgVVl7G0TwFO9CqQ1ws3zNqogQu%2B2%2Bx3U%2BQ8%2FSZtwgjezw%3D%3D&#x26;branta_secret=f9b0fd20-b402-4cd2-b68f-3ae3db52dbf5</code></p></figcaption></figure>
{% endtab %}
{% endtabs %}


# Staging

**Scanner:** <https://scan.branta.pro/scan?environment=staging>

{% hint style="info" %}
Query param values in `bitcoin:` URIs are URI-encoded.
{% endhint %}

## Match

{% tabs %}
{% tab title="Bitcoin address" %}
`match` — show the counterparty name and logo.

[Open verify page](https://staging.guardrail.branta.pro/v2/verify/6SpYCe23r79x0t8rNvmjWqhrg8hen4xz%2FYSXhNJ9HLSYrTRPnm%2BSwAuf6NOKobnwE%2B3MQBNkyTnCtIWpKKX2E9ZUWVedig%3D%3D#k-181257=05eb145d-b5cb-452a-9256-0bdfd9a15ffa)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-d5bbe7fa6783704657306c544b2f8067a096c81e%2FStaging-ZK-On-Chain-QR.png?alt=media" alt="" width="563"><figcaption><p><code>bitcoin:bc1qgw3dzmhnyvcswc9r0v0z0ajtp8ulm4nuyeahwr?branta_id=6SpYCe23r79x0t8rNvmjWqhrg8hen4xz%2FYSXhNJ9HLSYrTRPnm%2BSwAuf6NOKobnwE%2B3MQBNkyTnCtIWpKKX2E9ZUWVedig%3D%3D&#x26;branta_secret=05eb145d-b5cb-452a-9256-0bdfd9a15ffa</code></p></figcaption></figure>
{% endtab %}

{% tab title="Testnet" %}
`match` — show the counterparty name and logo.

[Open verify page](https://staging.guardrail.branta.pro/v2/verify/fa05KT1L6zIAYx2sHcImF3R5RilwMAXAvx%2F5u2YVBIdvnp30drV7bszFzvpdoA%2FeluN0PXbsxcsD38twzw4%2BL8MFoHxkGQ%3D%3D#k-dc562e=0621110e-1ad6-483d-80b6-78697c9f6896)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-825492f8e22c18d39b3c3c1fcd1e6ddb0c211dff%2FStaging-Testnet-ZK-QR.png?alt=media" alt="" width="563"><figcaption><p><code>bitcoin:tb1qshra2mlujc9wfscvn4d8aqpyqgxzl55853xg7s?branta_id=fa05KT1L6zIAYx2sHcImF3R5RilwMAXAvx%2F5u2YVBIdvnp30drV7bszFzvpdoA%2FeluN0PXbsxcsD38twzw4%2BL8MFoHxkGQ%3D%3D&#x26;branta_secret=0621110e-1ad6-483d-80b6-78697c9f6896</code></p></figcaption></figure>
{% endtab %}

{% tab title="bolt11" %}
`match` — show the counterparty name and logo. Resolves from the invoice. Expires 2027-10-31.

[Open verify page](https://staging.guardrail.branta.pro/v2/verify/FhqG4D2dOn5AaRL7c0Xb0LEcFdXBfJjWUQWXmTTjkTnR0qfx6gAW8CH44IoPb4XQBJ2EB91GSn5VrdoRi5qLfwxi3E%2FHB1vlG1DKb%2FJsYlFlKPH30LFZ0WAS%2FEpaq5e0m3aCw0zOKCx7aWrHq%2FPcKu3ubM6nPPKGYun%2Ffp%2BIRnYBPJ9A0YYFoRg%2BojywIrf8f8pIgHVdM8Air1GMk2t3eQuONx%2B3SV2AteY8O%2B%2FcM15WXyQtw5wMvjLNoaSR6unroJK7WJAwOQT4VC0PGyYfbtNXkQnzW%2FbOvI0HsCjA4Q8X7cBQ5zCacGrzPvFmhWZCVvigsa1jVxUi3fr%2F6ETpk2CjW1bVEWJMeLQavT8wNUdqjM26voj6qkiDdNTnot1uLJ%2BV9zW%2FmKkFIL9X1LoHQwzPwlA%3D#k-fc985d=E1481AC1ABE2ED499DC998798CAE2F51DBA3D78A92E28C8BBFBB52FD3024BBF8)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-87ab7a7cc1398a6053887c16ffe5f3049b96c7e2%2FStaging-Bolt11-QR.png?alt=media" alt=""><figcaption><p><code>lightning:lnbc10u1p4w23tzpp50uc6g4020tt3ffp5xfpp83k0lcv2spytpymuupqrnsj0eth8jqgsdqhgfexzmn5vys8xarpva5kuecxq97zvuqsp5tj2a5fd84lhdddzfqz2lwmjqg7n9gp28yy5vtqd78muyzdt5tmsq9qypsqqcqpf6yv66fkcq609xzk0fcqx82hd7fsjhwrzj8xmq743v5lrtssrj95r94hyeumqeejgqvtxqy7ks7ec0uc5lc5zxg240xtwgzjtwkmh3aqqm8gyny</code></p></figcaption></figure>
{% endtab %}

{% tab title="Ark" %}
`match` — show the counterparty name and logo. Resolves from the address.

[Open verify page](https://staging.guardrail.branta.pro/v2/verify/l%2B3ium%2B9sIBORlcGJBiYICba1HJl04cWRllZz3RWMGHtFb9Df2rxcATCmsMknPOg7wPNQcgMcuUY4i4zFasvc6dZLx%2BGtyJUSCm3u4%2FSknaWUq17O1X7Cd6wrQ%3D%3D#k-e5f00d=38FC1D309D49039A1AA149FAD3CCDCFC236352D3BE5FBB30AA5B8B93DC035F2C)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-a4a872da22bb40f427886186cd16e891dac36b84%2FStaging-Ark-QR.png?alt=media" alt=""><figcaption><p><code>ark1qztwuhx7vpytv4dcfeqjsepx3kxstnarelmry2smrfdgt2dv87fas7gtqkk</code></p></figcaption></figure>
{% endtab %}

{% tab title="Silent payment" %}
`match` — show the counterparty name and logo. Resolves from the address.

[Open verify page](https://staging.guardrail.branta.pro/v2/verify/5zVxjBiT24Hb83d6QUSP4GL3AO0X11%2FkvzpU4mfD0XJojPnXan4cSRIIctCFXT8NY%2FiOLG4ThxIN2xkz31gko36JmjzNsPqC%2FZDeFs8UP16G%2FMca%2B8GwUSOidwvearL8DNTXxCs7Ap5QXAeMZxAYGSqM4BG7gsIcGC875AxU1tLZ%2BPduO6FW9iOeD0DFJe6O#k-97b283=60653447E2ECB325BC2954B8B67873C1781A6B5F540442B493408764A8BA4C6E)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-134f8c6a0f238b03ab1fa293ee1a79aa3d485c1b%2FStaging-Silent-Payment-QR.png?alt=media" alt=""><figcaption><p><code>sp1qqgste7k9hx0qftg6qmwlkqtwuy6cycyavzmzj85c6qdfhjdpdjtdgqjuexzk6murw56suy3e0rd2cgqvycxttddwsvgxe2usfpxumr70xc9pkqwv</code></p></figcaption></figure>
{% endtab %}

{% tab title="Unified" %}
`match` — show the counterparty name and logo. Bitcoin address + `lightning=` bolt11 + `branta_id` / `branta_secret` (the BIP-21 shape POS like BTCPay emit). Pass the full URI through; do not split it before lookup. bolt11 expires 2027-10-31.

[Open verify page](https://staging.guardrail.branta.pro/v2/verify/NxkrlFgIvGg6f8YZmFAf8qTUza8nXfn%2Bb9H3W7czFAo5Lp4cSpgRSmJgx7P9vaOYu7lkP6XXKvTshQfkXxxRrxJ%2BE7zdpA%3D%3D#k-8a42e1=6acf2637-511a-4b89-ba2c-f5914d7e669c\&k-9ce3f9=5A2DDBE00E824C7DC48468798AF492C5532DE68E068D3E53B4BF4680839D6FFD)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-cdfb7072bed825d4c44a1c656cc59e2c6f9c054e%2FStaging-Unified-QR.png?alt=media" alt=""><figcaption><p><code>bitcoin:bc1q6745z6cy3u0k9nprurh3x804c4r7u3u8vxca2n?lightning=lnbc10u1p4w23tzpp5s6jc8gvun27un7g7q9kmh2vak78r83766heesd9fepa5s56hrpsqdqhgfexzmn5vys8xarpva5kuecxq97zvuqsp5gt4k9wwdgf85g066a05zrnlkh3jc2ng3mh9mw6yw7z03l4kmqzys9qypsqqcqpf7pk6xjfksy8sqhv24es2qgtp0e88wvt2gdv2zceealhjwh0memhzktgnfhdvzc9a6kt74w5jf5c8v9t20k38snawrgngr0sjw9a58fqqn9lwtq&#x26;branta_id=NxkrlFgIvGg6f8YZmFAf8qTUza8nXfn%2Bb9H3W7czFAo5Lp4cSpgRSmJgx7P9vaOYu7lkP6XXKvTshQfkXxxRrxJ%2BE7zdpA%3D%3D&#x26;branta_secret=6acf2637-511a-4b89-ba2c-f5914d7e669c</code></p></figcaption></figure>
{% endtab %}
{% endtabs %}

## Not a match

{% tabs %}
{% tab title="Not found" %}
An unregistered destination. `unknown` — show nothing.

[Open verify page](https://staging.guardrail.branta.pro/v2/verify/bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4)

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-e7222bb311ae73b531a7e510ac969fce86f7fe19%2FStaging-Not-Found-QR.png?alt=media" alt=""><figcaption><p><code>bitcoin:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4</code></p></figcaption></figure>
{% endtab %}

{% tab title="Tampered" %}
A QR whose visible address was swapped while `branta_id` / `branta_secret` still point at a registered payment — the address in the `bitcoin:` URI is the **Not found** address above, with params copied from **Bitcoin address**.

`tampered` — warn. Do not show a verified card.

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-54b4f3dd15cd96c604e8a70963332c88268ec60b%2FStaging-Tampered-QR.png?alt=media" alt="" width="563"><figcaption><p><code>bitcoin:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4?branta_id=6SpYCe23r79x0t8rNvmjWqhrg8hen4xz%2FYSXhNJ9HLSYrTRPnm%2BSwAuf6NOKobnwE%2B3MQBNkyTnCtIWpKKX2E9ZUWVedig%3D%3D&#x26;branta_secret=05eb145d-b5cb-452a-9256-0bdfd9a15ffa</code></p></figcaption></figure>
{% endtab %}
{% endtabs %}


# Receive

### 1. Create an account

Sign up at [guardrail.branta.pro](https://guardrail.branta.pro). The Branta dashboard (we call it Guardrail) is where you manage your platform, request approval, and issue API keys.

For testing, the staging dashboard is at [staging.guardrail.branta.pro](https://staging.guardrail.branta.pro/session/new). Staging and production are siloed — see [Environments](/tech/environments).

### 2. Submit a Platform Request

In Guardrail, create a Platform Request. A Branta admin reviews it (a light KYB check — we confirm your business and that the platform brand you're claiming is yours) and approves the platform on your account.

{% hint style="info" %}
Approvals are manual. If you need this turned around quickly for a launch or demo, mention the timeline in the request.
{% endhint %}

### 3. Create an API key

Once your platform is approved, generate an API key from Guardrail.

{% hint style="danger" %}
API keys carry sensitive privileges. Never commit them to source control, ship them in client-side code, or share them in plain text. Rotate immediately if exposed.
{% endhint %}


# Integrations

* [BTCPay Server](/setup/receive/integrations/btcpay-server)
* [Take My Sats](/setup/receive/integrations/take-my-sats)
* [Zaprite](/setup/receive/integrations/zaprite)


# BTCPay Server

Install the [Branta plugin](https://plugin-builder.btcpayserver.org/public/plugins/branta).

[Voltage](https://www.voltage.cloud), [BTCPay Italia](https://www.btcpayserver.it), and [Bitcoin Aruba](https://btc.aw) already have Branta installed.

## 1. Install

Log in to BTCPay Server and click Manage Plugins.

{% hint style="warning" %}
If you don't see Manage Plugins, an admin has to do this for you.
{% endhint %}

Search `Branta` and click Install. BTCPay Server will restart.

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2FimNqkT2IBFXrmiU0jMPH%2FScreenshot%202025-11-06%20140300.png?alt=media&amp;token=e2036d1f-b963-421e-ba15-aeddc8381f18" alt=""><figcaption></figcaption></figure>

Branta appears under Plugins.

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2FBicUPWEtbFChak02WVvK%2FScreenshot%202025-08-30%20at%2009.10.21.png?alt=media&amp;token=b35aac5a-4625-4ae7-9075-fc6b6adbaf0c" alt=""><figcaption></figcaption></figure>

## 2. API key and enable

Under Plugins, click Branta. Paste the API key from your Branta dashboard, turn on Enable Branta, and click Save.

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fz0spn4dt8O4e7wPVOWms%2FScreenshot%202025-11-06%20140810.png?alt=media&amp;token=17d2cb8e-e201-414e-b349-1f19bc246147" alt=""><figcaption></figcaption></figure>

## 3. Advanced settings (optional)

Expand **Advanced** on the settings page to change defaults:

* **Enable Staging** and **Staging API Key** — point the plugin at `staging.guardrail.branta.pro`. Use a staging API key.
* **Show Checkout Info on Verification Page** — include the invoice description on the Branta verify page.
* **Allow Guardrail Verification for** — how long each published destination stays valid. Options: 30 minutes (default), 4 hours, 1 day, 7 days.
* **Show Verify Link at Checkout** — whether `Click to verify with Branta` appears on invoices.

## 4. Verify

Create a test invoice. Checkout shows `Click to verify with Branta`.

You can also [QR scan](https://scan.branta.pro/scan) the invoice.

<figure><img src="https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fw93WqvI1LsSmU1e7IBvn%2Fbtcpay-btc.png?alt=media&amp;token=3ea97d6f-a712-49fb-84e0-91d49ba612a7" alt=""><figcaption></figcaption></figure>


# Take My Sats

Enable Branta under payment settings in [Take My Sats](https://www.takemysats.com/).


# Zaprite

[Official Zaprite blog for connecting Branta](https://blog.zaprite.com/how-to-connect-branta/)


# Custom Integration

POST your payment destinations to Branta from your own code — SDK or raw HTTP.

If none of [BTCPay, Take My Sats, or Zaprite](/setup/receive/integrations) fit, post destinations yourself. Use an SDK, or `POST` the HTTP API.

### Prerequisites

* You've completed [Receive](/setup/receive) setup — account, approved platform, and an API key.
* You know which [environment](/tech/environments) you're hitting (`staging` while testing, `production` for live traffic).
* Hold the API key server-side. Never put it in a browser bundle or mobile binary.

### Use the SDK

Install from the [SDK](/tech/sdk) page.

Every destination is encrypted before it is posted. Store `secret` with the invoice. Put `branta_id` and `branta_secret` on the invoice QR. Link the sender to `verifyUrl`.

`ttl` is seconds until Branta forgets the destination (30 second minimum, 1 year maximum; server default 7 days). `metadata` is stored as a string — Branta does not parse it.

### Raw HTTP

If you are not using an SDK, `POST` `/v2/payments`. Encrypt each destination before you send it — a send lookup of a bare address is `unknown`. The algorithm is on [Receive](/tech/api/receive#zero-knowledge). Full schema is on that page too.

```bash
curl -X POST https://guardrail.branta.pro/v2/payments \
  -H "Authorization: Bearer $BRANTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [
      {
        "value": "<ciphertext>",
        "type": "bitcoin_address",
        "primary": true,
        "zk": true
      }
    ],
    "ttl": 3600,
    "metadata": "order-12345"
  }'
```

### Invoice QR

On-chain Bitcoin needs `branta_id` and `branta_secret` on the URI the sender scans:

| Param           | Source                                             | Description                     |
| --------------- | -------------------------------------------------- | ------------------------------- |
| `branta_id`     | encrypted destination `value` returned by the POST | URL-encoded ciphertext          |
| `branta_secret` | `secret` returned by `addPayment`                  | decryption key — only in the QR |

```
bitcoin:<address>?branta_id=<url_encoded_branta_id>&branta_secret=<secret>
```

The address stays in the URI so the sender knows where to pay. Wallets that do not recognise these params ignore them (BIP-21).

bolt11, Ark, and silent payments use their normal URI. No extra params.

### verifyUrl

`verifyUrl` is the public Branta verify page for this payment. Link it from the invoice.


# Parent Platforms

Publish payments on behalf of many merchants or brands.

A **parent platform** is a service that integrates Branta on behalf of many merchants or brands and `POST`s payments for each.

Pick how you manage API keys:

### [Shared key](/setup/receive/custom-integration/parent-platforms/shared-key)

One Branta platform and one API key covering every brand you serve. Tag each payment with the brand at publish time; Branta renders that name and logo to senders.

### [Per-client keys](/setup/receive/custom-integration/parent-platforms/per-client-keys) (Deprecated)

Each merchant has their own Branta platform and API key. You hold an HMAC secret and sign every publish.

{% hint style="info" %}
Single-tenant or self-hosted deployments like [BTCPay Server](/setup/receive/integrations/btcpay-server) are **not** parent platforms — each BTCPay store is its own Branta platform with its own API key. Parent Platforms apply when one piece of software is calling Branta on behalf of many brands.
{% endhint %}


# Shared key

One Branta platform and one API key. Tag each payment with the brand it belongs to.

One Branta platform and one API key covering every brand you serve. Tag each payment with the brand at publish time; Branta renders that name and logo to senders.

### Onboarding

Complete [Receive](/setup/receive) setup, then ask a Branta admin to turn on shared-key access.

### Integrate

Install from the [SDK](/tech/sdk) page. Tag the brand with `setChildPlatform(name, logoUrl, logoLightUrl)` (or the language equivalent) when building the payment.

Or `POST` `/v2/payments` with your API key in `Authorization: Bearer …` and a top-level `child_platform` object. Encrypt destinations before you send them — a send lookup of a bare address is `unknown`.

```bash
curl -X POST https://guardrail.branta.pro/v2/payments \
  -H "Authorization: Bearer $BRANTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": [
      {
        "value": "<ciphertext>",
        "type": "bitcoin_address",
        "primary": true,
        "zk": true
      }
    ],
    "child_platform": {
      "name": "Acme Coffee",
      "logo_url": "https://example.com/acme-logo.png",
      "logo_light_url": "https://example.com/acme-logo-light.png"
    }
  }'
```

`child_platform.name` is required; `logo_url` and `logo_light_url` are both optional. On lookup, a payment with a tagged brand returns that brand as the primary `platform` / `platform_logo_url` fields, and your own platform's branding under `parent_platform` — senders can optionally render that as a small secondary badge.

Full schema is on the [Receive](/tech/api/receive) reference.


# Per-client keys (Deprecated)

Each merchant has their own API key. You HMAC-sign every publish.

{% hint style="warning" %}
Deprecated. Use [Shared key](/setup/receive/custom-integration/parent-platforms/shared-key) for new integrations.
{% endhint %}

Each merchant has their own Branta platform and their own API key. You hold an HMAC secret and sign every payment publish, proving the request originated from you and not from someone who got a copy of a merchant's API key.

### How requests are authenticated

Every payment publish carries two credentials:

1. **The merchant's API key** in `Authorization: Bearer …`. This tells Branta which merchant's platform the payment belongs to, so the right name and logo render to senders.
2. **The parent's HMAC signature** in `X-HMAC-Signature` and `X-HMAC-Timestamp`. The merchant's API key is configured with a `parent_platform_id`, which tells Branta to validate the request's HMAC against the parent's active API secrets. Requests missing a valid signature are rejected.

The merchant onboards as a normal [Platform](/setup/receive) and, when generating their API key in Guardrail, selects your parent platform from the dropdown. From then on, that key only works when accompanied by your HMAC signature.

### Onboarding

#### 1. Get parent platform access enabled

A Branta admin needs to turn this on for your account. Reach out and ask — without it, the API Secrets section in Guardrail will not be available, and merchants won't be able to select you as a parent when issuing their API keys.

#### 2. Generate an API Secret

Once parent platform access is enabled, an **API Secrets** section appears in Guardrail. Generate a secret there.

The secret is shown **once at creation** — copy it immediately and store it server-side (your secret manager, not source control).

{% hint style="danger" %}
The API Secret is the HMAC signing material for every payment you publish on behalf of every merchant. Treat it like a root credential — store it server-side only, never ship it to clients, and rotate immediately if exposed.
{% endhint %}

You can hold multiple active secrets at the same time, which makes rotation safe: generate the new one, deploy it, then revoke the old one once nothing is signing with it.

#### 3. Integrate

For each merchant you serve:

1. They onboard as a normal [Platform](/setup/receive) (steps 1–3 of that flow), then create an API key in their own Guardrail account and select your parent platform from the dropdown.
2. They share that API key with you (the same way they'd share an API key with any payment service they use).
3. Your service `POST`s their payment destinations to Branta using their API key in `Authorization`, signed with your HMAC secret.

The SDKs sign this when you pass the merchant's API key and your HMAC secret. Install from the [SDK](/tech/sdk) page.

The request body is identical to a regular platform publish (see [Receive](/tech/api/receive)); the only difference is the two extra headers:

* `X-HMAC-Signature` — hex SHA-256 HMAC of the canonical message string, keyed by your API Secret.
* `X-HMAC-Timestamp` — Unix epoch seconds. Branta rejects requests outside a 30-minute window.

The canonical message is the request method, full URL, raw body, and timestamp joined with literal `|` characters, no whitespace:

```
POST|https://guardrail.branta.pro/v2/payments|{json-body}|1716998400
```

If you'd rather sign requests yourself:

```bash
BODY='{"destinations":[{"value":"<ciphertext>","type":"bitcoin_address","primary":true,"zk":true}]}'
TS=$(date +%s)
MSG="POST|https://guardrail.branta.pro/v2/payments|${BODY}|${TS}"
SIG=$(printf '%s' "$MSG" | openssl dgst -sha256 -hmac "$BRANTA_API_SECRET" | awk '{print $2}')

curl -X POST https://guardrail.branta.pro/v2/payments \
  -H "Authorization: Bearer ${MERCHANT_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-HMAC-Signature: ${SIG}" \
  -H "X-HMAC-Timestamp: ${TS}" \
  -d "$BODY"
```


# Tech


# Environments

* **Staging** for testing:
  * [https://staging.guardrail.branta.pro](https://staging.guardrail.branta.pro/session/new)
* **Production** for live traffic:
  * <https://guardrail.branta.pro/>

Each environment is siloed; no data is shared between staging and production.


# SDK

{% tabs %}
{% tab title=".NET" %}
**NuGet:** `Branta` — [github.com/BrantaOps/branta-dotnet](https://github.com/BrantaOps/branta-dotnet)

> Install the latest version of the Branta NuGet package, then read the package README.
> {% endtab %}

{% tab title="JavaScript" %}
**npm:** `@branta-ops/branta` — [github.com/BrantaOps/branta-js](https://github.com/BrantaOps/branta-js)

> Install the latest version of @branta-ops/branta from npm, then read the package README.
> {% endtab %}

{% tab title="Python" %}
**PyPI:** `branta` — [github.com/BrantaOps/branta-python](https://github.com/BrantaOps/branta-python)

> Install the latest version of the branta package from PyPI (`pip install branta`), then read the package README.
> {% endtab %}

{% tab title="Dart" %}
**pub.dev:** `branta` — [github.com/BrantaOps/branta-dart](https://github.com/BrantaOps/branta-dart)

> Install the latest version of the branta package from pub.dev, then read the package README.
> {% endtab %}

{% tab title="Kotlin" %}
**Maven Central:** `pro.branta:branta` — [github.com/BrantaOps/branta-kotlin](https://github.com/BrantaOps/branta-kotlin)

> Install the latest version of pro.branta:branta from Maven Central, then read the package README.
> {% endtab %}

{% tab title="Rust" %}
**crates.io:** `branta` — [github.com/BrantaOps/branta-rust](https://github.com/BrantaOps/branta-rust)

> Install the latest version of the branta crate from crates.io (`cargo add branta`), then read the package README.
> {% endtab %}

{% tab title="Go" %}
**Go module:** `github.com/BrantaOps/branta-go/v4` — [github.com/BrantaOps/branta-go](https://github.com/BrantaOps/branta-go)

> Install the latest version of github.com/BrantaOps/branta-go/v4 (`go get github.com/BrantaOps/branta-go/v4`), then read the package README.
> {% endtab %}

{% tab title="Swift" %}
**Swift Package Manager:** `Branta` — [github.com/BrantaOps/branta-swift](https://github.com/BrantaOps/branta-swift)

> Add <https://github.com/BrantaOps/branta-swift.git> as a Swift package dependency, then read the package README.
> {% endtab %}
> {% endtabs %}


# API


# Send

{% openapi src="/files/dHemYIaHeyaoFDTJ6cFJ" path="/payments/{payment\_string}" method="get" %}
[openapi-send.json](https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-421c3ad23e96b323a589b383add98ea58edf9317%2Fopenapi-send.json?alt=media)
{% endopenapi %}


# Receive

{% openapi src="/files/gQ1HTpwMEPLktk3mMzZ9" path="/payments" method="post" %}
[openapi-receive.json](https://2482615079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWfLyw4XD5FjUVq3GxTZN%2Fuploads%2Fgit-blob-06e433611e02ba20ed3fed42edd674ebb437558f%2Fopenapi-receive.json?alt=media)
{% endopenapi %}

## Zero Knowledge

Encrypt the destination before `POST`. A send lookup of a bare address is `unknown`. The [SDK](https://github.com/BrantaOps/docs/tree/main/sdk.md) encrypts for you. HTTP callers use this algorithm:

```javascript
async function encrypt(value, secret) {
  const keyData = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret));
  const key = await crypto.subtle.importKey('raw', keyData, { name: 'AES-GCM' }, false, ['encrypt']);

  const iv = crypto.getRandomValues(new Uint8Array(12));
  const encrypted = await crypto.subtle.encrypt(
    { name: 'AES-GCM', iv: iv },
    key,
    new TextEncoder().encode(value)
  );

  const combined = new Uint8Array(iv.length + encrypted.byteLength);
  combined.set(iv, 0);
  combined.set(new Uint8Array(encrypted), iv.length);

  return btoa(String.fromCharCode(...combined));
}
```

```javascript
const address = '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa';
const secret = crypto.randomUUID();

await encrypt(address, secret);
// Result:
// LQdBBewrzglmPYwUVoSjBJihA/Br8o+T1ArXGLaAuh7yJiW2dClzSBSUbUH1zhPo1WUBtr7JaFQ7wkK7CG4=
```


# Health Check

Unauthenticated liveness probe — returns `200 OK` whenever the server is up.

* <https://staging.guardrail.branta.pro/up>
* <https://guardrail.branta.pro/up>

### API key health check

Validates an API key (Bearer token in `Authorization`). Returns `200 OK` for an active key, `401 Unauthorized` for a missing, revoked, or expired key. This is what the SDKs' `isApiKeyValid()` / `IsApiKeyValidAsync()` / `is_api_key_valid()` call under the hood.

* `GET https://staging.guardrail.branta.pro/v2/api-keys/health-check`
* `GET https://guardrail.branta.pro/v2/api-keys/health-check`


# Key Rotation

**If you believe your API Key has been compromised, revoke the key in your Branta Dashboard.**

Keys can be set to expire at any date, or never.

Branta will send automated email reminders leading up to the expiration date in the following intervals:

* 30 days before
* 7 days before
* 2 days before


