Connect provider with the tenant's client credentials

curl --request POST \
  --url https://payments.sandbox.lerian.net/v1/admin/providers/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://payments.sandbox.lerian.net/v1/admin/providers/connect"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://payments.sandbox.lerian.net/v1/admin/providers/connect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://payments.sandbox.lerian.net/v1/admin/providers/connect"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "account_verified": true,
  "provider_type": "<string>",
  "status": "<string>",
  "company_id": "<string>",
  "provider_account_id": "<string>",
  "webhook_signing_key": "<string>",
  "webhook_subscription_registered": true,
  "webhook_url": "<string>"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

{
  "code": "<string>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Connect provider with the tenant's client credentials

Proves the tenant’s stored client_id/client_secret can mint a provider access token, persists it, verifies that the credential resolves to exactly one usable provider account, and resolves the provider company_id.

X-Organization-Id IS REQUIRED. It names the Midaz organization whose legalDocument (CNPJ) becomes the provider company_id, and that organization owns the tenant’s provider account. An absent, blank or non-canonical value answers 400 PBP-0025 before anything reaches the provider. Connecting again with a different organization overwrites the company_id: the last connect wins.

Send an EMPTY JSON OBJECT as the body: . The body carries nothing — the provider implements the client_credentials grant only, so there is no authorization code to exchange and no redirect to honour — but it is still required, so omitting it entirely answers 400, and so does null. Any unknown field is rejected rather than ignored.

Account verification is a fresh read of the provider’s account list, never a cached one, and it does not populate any runtime cache: it observes. It answers 422 when the provider side is misconfigured in a way an operator can fix — no default account, more than one, or a default that is locked or not active — and 502 when the provider breaks its own contract or the account does not belong to the credential that would pay for it.

account_verified reports whether the check actually ran. It is false, with the connection still established, on a deployment where the provider’s Common Methods base URL is not configured; provider_account_id is then absent. A false here means nothing proved that the credential resolves to one usable account, and at the provider a wrong account does not error — it settles.

MULTI-TENANT DEPLOYMENTS ONLY: the answer also carries webhook_url and webhook_signing_key. webhook_url is this tenant’s own inbound address; the connection token it carries is what tells the service which tenant a delivery belongs to. webhook_signing_key is the key the provider computes the HMAC-SHA256 of each delivery body with and sends in the x-webhook-baas-signature header. It is a SIGNING KEY, not a bearer token: it must never be placed in an Authorization header. Register the two together at the provider.

THE SIGNING KEY IS SHOWN EXACTLY ONCE AND IS NOT RECOVERABLE AFTERWARDS. It is stored only in encrypted form, and no endpoint returns it again — record it when you read it. Calling connect again does not re-show it: it ROTATES the connection, issuing a new webhook_url and a new webhook_signing_key and putting the previous pair into a bounded GRACE WINDOW.

THE PREVIOUS URL AND KEY KEEP AUTHENTICATING FOR THAT WINDOW. Its length is WEBHOOK_CONNECTION_GRACE_WINDOW_SEC, 1800 seconds by default, and it exists so the provider’s in-flight retries — already signed with the retired key and addressed to the retired URL — are not dropped while you register the new pair. The retired pair stops authenticating when the window closes. If the URL or the signing key may have been exposed, cancel the connection first, then connect to issue a fresh pair.

BECAUSE OF THAT ROTATION, THIS OPERATION IS NOT IDEMPOTENT AND DOES NOT ACCEPT AN IDEMPOTENCY KEY. Sending Idempotency-Key is accepted and ignored; it does NOT replay a previous answer. Retrying a connect whose response you never saw issues a NEW connection and supersedes the one the provider may already be using — which then serves only until its grace window closes — so retry only when you are ready to register the new pair at the provider.

Both fields are ABSENT in single-tenant deployments, where no per-tenant connection exists and deliveries keep arriving on the shared webhook route under the globally configured key.

POST

admin

providers

connect

Connect provider with the tenant's client credentials

curl --request POST \
  --url https://payments.sandbox.lerian.net/v1/admin/providers/connect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://payments.sandbox.lerian.net/v1/admin/providers/connect"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({})
};

fetch('https://payments.sandbox.lerian.net/v1/admin/providers/connect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://payments.sandbox.lerian.net/v1/admin/providers/connect"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "account_verified": true,
  "provider_type": "<string>",
  "status": "<string>",
  "company_id": "<string>",
  "provider_account_id": "<string>",
  "webhook_signing_key": "<string>",
  "webhook_subscription_registered": true,
  "webhook_url": "<string>"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

{
  "code": "<string>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Organization-Id

string

Midaz organization whose legalDocument (CNPJ) is provisioned as the provider company_id. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0025. Declared optional on the schema so that refusal keeps its own code.

Body

application/json

The body is of type object.

Response

account_verified

boolean

required

provider_type

string

required

status

string

required

company_id

string

provider_account_id

string

webhook_signing_key

string

webhook_subscription_registered

boolean

Whether the subscription pointing the provider at webhook_url was written at the provider. ABSENT means no per-tenant webhook connection was issued, so there was nothing to register. TRUE means the provider has been told. FALSE means the connect SUCCEEDED and the delivery URL is already live on our side, but the provider has not been told yet: it is not a failed connection, the credentials in this body are valid, and the health poller retries the registration on its own. Wait for that retry rather than reconnecting, which would rotate the signing key you just received.

webhook_url

string

Boletos API

Payments API

Dashboards API

Admin API

Webhooks API

Error handling

Connect provider with the tenant's client credentials

Authorizations

Headers

Body

Response