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>",
  "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>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

Connect provider with the tenant's client credentials

Connects the tenant to the banking provider. It checks that the provider client credentials configured for the tenant can obtain an access token, stores that token, and resolves the provider company_id from the organization named in X-Organization-Id. On a deployment that verifies provider accounts, it also verifies that the credentials resolve to exactly one usable provider account, and account_verified in the answer says whether the account was verified. The tenant’s provider client credentials must be configured before this call.

X-Organization-Id is required. It names the Midaz organization whose legalDocument (CNPJ) becomes the provider company_id; that organization owns the tenant’s provider account. A request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025 and nothing is sent to the provider. Connecting again with a different organization replaces the company_id: the last successful connect wins.

Send an empty JSON object as the body: . The body is required: a request with no body, or with null, is refused with 400, and any field in it is rejected.

Account verification failures: 422 means the account setup at the provider must be corrected — there is no default account, there is more than one, or the default account is locked or not active. 502 means the provider returned an invalid answer, or the account does not belong to the credentials that would pay for it.

account_verified reports whether the provider account was verified. When it is true, provider_account_id identifies the verified account. When it is false, the connection is established but the account was NOT verified on this deployment and provider_account_id is absent: a successful connection is not evidence that the credentials resolve to the correct account. Do not treat the account as validated; contact support to have verification enabled.

MULTI-TENANT DEPLOYMENTS ONLY: the answer also carries webhook_url and webhook_signing_key. webhook_url is this tenant’s inbound address for provider deliveries, and the token it contains identifies the tenant. webhook_signing_key is the key the provider uses to compute the HMAC-SHA256 of each delivery body, sent in the x-webhook-baas-signature header. It is a signing key, not a bearer token: never place it in an Authorization header. The two are registered together at the provider; webhook_subscription_registered reports whether this call registered them. Both fields are absent in single-tenant deployments.

THE SIGNING KEY IS SHOWN EXACTLY ONCE. No endpoint returns it again, so record it when you read it. Calling connect again ROTATES the connection: it issues a new webhook_url and a new webhook_signing_key, and the previous pair keeps authenticating deliveries for a grace window so that deliveries already in flight are not lost.

If the webhook URL or the signing key may have been exposed, call connect again with the same X-Organization-Id. A successful call rotates both. The exposed pair keeps working until its grace window closes, 30 minutes by default. After a failed call, the exposed pair stays in use.

THIS OPERATION IS NOT IDEMPOTENT. An Idempotency-Key header is ignored and does not replay a previous answer. Retrying a connect whose response you did not receive issues a new connection and replaces the one the provider may already be using, which then authenticates only until its grace window closes.

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>",
  "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>",
  "message": "<string>",
  "title": "<string>",
  "details": {}
}

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.

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 credentials in this body are valid, but the provider was not told where to deliver events, so deliveries to webhook_url may not arrive yet. Depending on the cause, the registration is retried automatically or needs an operator. Do not reconnect: that rotates the signing key you just received. If deliveries do not start, call POST /v1/admin/providers/webhooks/{provider_type}/resubscribe or contact support.

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