API Key Permissions

Use this route to find out which API routes are enabled for your api_key. The response lists every documented route, grouped by the same sections as this documentation, and tells you with true or false whether your account can use each one.

It lets your integration adapt to the products enabled on your account without manual configuration. For example, you can show the Pix option at checkout only when POST v3/pix is enabled.

When to use

When starting your integration, to confirm which products are already enabled on your account.
When building your checkout or dashboard, to show only the available payment methods and features.
When investigating an error, to check whether the route you called is enabled for your account.

GETv3/api_key/permissions

Request Headers

This route takes no query or body parameters.

Header	Type	Description
api_key	string	Required. Your API key. The permissions returned belong to the account linked to this key, in the environment the request is made to (Sandbox or Production).

Warning

Check permissions with the api_key of the environment you are going to use. A result obtained in Sandbox does not apply to Production, and vice versa.

Response Object

The response is an object where each key is a documentation section. Inside each section, the keys are the HTTP methods (GET, POST, PUT, PATCH). Inside each method, the keys are the API route path, for example v3/sub_sellers, and the values are boolean. Sections, methods and routes are sorted alphabetically. Keys keep the same names in every language.

Section	Type	Documentation section
sub_sellers	object	Partners
cards	object	Cards
transactions	object	Transactions
checkouts	object	Checkouts
webhooks	object	Webhooks
antifraud	object	Antifraud Integration
3ds	object	3DS Integration
crossborder	object	Cross Border
financial	object	Financial
conciliation	object	Reconciliation

How to read the response

true: the route is enabled for your account in this environment.
false: the route is not enabled. To enable it, please contact our support team.
Route not in the response: consider it not enabled, as if it were false.
New routes: the response gains new routes and sections as we launch products. Check only the routes your integration uses, without expecting the list to always be the same.

Enablement rules

The tables below show when each route is enabled. Routes that require enablement by Marlim become available once the product is contracted and configured on your account.

sub_sellers

Key	Enabled when
`POST v3/sub_sellers` Create partner	Requires partners to be enabled.
`GET v3/sub_sellers` Retrieve partners	Requires partners to be enabled.
`PUT v3/sub_sellers/:sub_seller_id` Update partner	Requires partners to be enabled.
`PATCH v3/sub_sellers/:sub_seller_id/files` Upload documents	Requires partners to be enabled.

cards

Key	Enabled when
`POST v3/cards` Create card	Always enabled.
`GET v3/cards/:card_id` Retrieve card	Always enabled.

transactions

For accounts with Cross Border enabled, every route in this section returns false, except GET v3/card_hash_key. See crossborder.

Key	Enabled when
`GET v3/installments` Installments	The account rates are configured.
`POST v3/transactions` Create card transaction	Requires card payments to be enabled.
`POST v3/pix` Create Pix transaction	Requires Pix to be enabled.
`GET v3/transactions` Retrieve transactions	Always enabled.
`POST v3/transactions/:transaction_id/refund` Refund transaction	Always enabled.
`GET v3/card_hash_key` Card Hash Key	Always enabled.
`POST v3/transactions/authorize` Authorize transaction	Sandbox only and requires pre-authorization to be enabled.
`POST v3/transactions/:transaction_id/capture` Capture transaction	Same rule as Authorize transaction.
`POST v3/transactions/:transaction_id/cancel` Cancel transaction	Same rule as Authorize transaction.

checkouts

Key	Enabled when
`POST v3/link_payment` Create payment link	Requires Payment Link to be enabled.
`GET v3/link_payment/:link_hash` Link data	Always enabled.

webhooks

Key	Enabled when
`GET v3/webhooks/:transaction_id` Retrieve webhooks	Always enabled.
`POST v3/webhooks/:transaction_id` Reprocess webhook	Always enabled.

antifraud

Key	Enabled when
`PATCH v3/antifraud` Emulate antifraud review	Test `api_key` only (Sandbox).

3ds

Key	Enabled when
`GET v3/3ds/sessions` Create 3DS session	Always enabled.

crossborder

Key	Enabled when
`GET v3/crossborder/installments` Installments	Requires Cross Border to be enabled.
`GET v3/crossborder/quotes/preview` Quote preview	Requires Cross Border to be enabled.
`POST v3/crossborder/transactions` Create transaction	Requires Cross Border to be enabled.
`GET v3/crossborder/transactions` Retrieve transactions	Requires Cross Border to be enabled.
`POST v3/crossborder/transactions/:transaction_id/refund` Refund transaction	Requires Cross Border to be enabled.

Accounts with Cross Border

When Cross Border is enabled, transactions, lookups and refunds go through the routes in this section. The routes in the transactions section return false and, if called, answer 403. The exception is GET v3/card_hash_key, which stays enabled to create the card_hash used in POST v3/crossborder/transactions.

financial

Key	Enabled when
`GET v3/financial/balance` Get balance	Requires the financial dashboard to be enabled.
`GET v3/financial/withdrawals` List withdrawals	Requires the financial dashboard to be enabled.
`GET v3/financial/conciliations` List reconciliations	Requires the financial dashboard to be enabled.
`GET v3/financial/conciliation` Get reconciliation	Requires the financial dashboard to be enabled.
`GET v3/financial/statement` Statement	Requires the financial dashboard to be enabled.
`POST v3/financial/withdrawal` Request withdrawal	Requires balance management to be enabled.
`GET v3/financial/withdrawal/:withdrawal_id` Get withdrawal	Requires balance management to be enabled.

conciliation

Key	Enabled when
`POST v3/conciliation` Bank reconciliation	Production `api_key` only (Production).

Sandbox and Production

The same account may get different responses in each environment. The routes below depend on the environment, regardless of the account enablement:

Key	Sandbox	Production
`POST v3/transactions/authorize` Authorize transaction	Based on the account enablement.	Always `false`. Pre-authorization is not yet supported in Production.
`POST v3/transactions/:transaction_id/capture` Capture transaction	Based on the account enablement.	Always `false`.
`POST v3/transactions/:transaction_id/cancel` Cancel transaction	Based on the account enablement.	Always `false`.
`PATCH v3/antifraud`	`true`	Always `false`. In Production, the antifraud review is performed by Marlim.
`POST v3/conciliation`	Always `false`.	`true`

Tip

Permissions only change when Marlim updates your account configuration, and our technical or product team lets you know when that happens. So you can cache the result for a long period (for example, 24 hours) and call this route again when you are notified, instead of calling it on every transaction.

Error Object

When the api_key is missing or invalid, the route returns an error and no permissions.

Attribute	Type	Description
errors	object	Object with the error found while processing the request.
errors[type]	string	Type of error. On this route, always `api_key`.
errors[message]	string	Detailed error message.

Status	When it happens
`401`	The `api_key` was not sent in the header.
`403`	The `api_key` is invalid, disabled, not allowed for API v3, or does not match the environment (test key in Production or production key in Sandbox).

Examples

WARNING

The values used in the examples below are for illustration only and must not be used to make requests to Marlim's APIs.

Account permissions
Missing api_key
Invalid api_key

Request

curl -X GET "https://api.marlim.co/v3/api_key/permissions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response200

{
  "3ds": {
    "GET": {
      "v3/3ds/sessions": true
    }
  },
  "antifraud": {
    "PATCH": {
      "v3/antifraud": false
    }
  },
  "cards": {
    "GET": {
      "v3/cards/:card_id": true
    },
    "POST": {
      "v3/cards": true
    }
  },
  "checkouts": {
    "GET": {
      "v3/link_payment/:link_hash": true
    },
    "POST": {
      "v3/link_payment": true
    }
  },
  "conciliation": {
    "POST": {
      "v3/conciliation": true
    }
  },
  "crossborder": {
    "GET": {
      "v3/crossborder/installments": false,
      "v3/crossborder/quotes/preview": false,
      "v3/crossborder/transactions": false
    },
    "POST": {
      "v3/crossborder/transactions": false,
      "v3/crossborder/transactions/:transaction_id/refund": false
    }
  },
  "financial": {
    "GET": {
      "v3/financial/balance": true,
      "v3/financial/conciliation": true,
      "v3/financial/conciliations": true,
      "v3/financial/statement": true,
      "v3/financial/withdrawal/:withdrawal_id": false,
      "v3/financial/withdrawals": true
    },
    "POST": {
      "v3/financial/withdrawal": false
    }
  },
  "sub_sellers": {
    "GET": {
      "v3/sub_sellers": true
    },
    "PATCH": {
      "v3/sub_sellers/:sub_seller_id/files": true
    },
    "POST": {
      "v3/sub_sellers": true
    },
    "PUT": {
      "v3/sub_sellers/:sub_seller_id": true
    }
  },
  "transactions": {
    "GET": {
      "v3/card_hash_key": true,
      "v3/installments": true,
      "v3/transactions": true
    },
    "POST": {
      "v3/pix": false,
      "v3/transactions": true,
      "v3/transactions/:transaction_id/cancel": false,
      "v3/transactions/:transaction_id/capture": false,
      "v3/transactions/:transaction_id/refund": true,
      "v3/transactions/authorize": false
    }
  },
  "webhooks": {
    "GET": {
      "v3/webhooks/:transaction_id": true
    },
    "POST": {
      "v3/webhooks/:transaction_id": true
    }
  }
}

Request

curl -X GET "https://api.marlim.co/v3/api_key/permissions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response401

{
  "errors": {
    "type": "api_key",
    "message": "All requests need a api_key."
  }
}

Request

curl -X GET "https://api.marlim.co/v3/api_key/permissions" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{}'

Response403

{
  "errors": {
    "type": "api_key",
    "message": "This api_key is not valid."
  }
}

Request Headers​

Response Object​

Enablement rules​

sub_sellers​

cards​

transactions​

checkouts​

webhooks​

antifraud​

3ds​

crossborder​

financial​

conciliation​

Sandbox and Production​

Error Object​

Examples​

Request Headers

Response Object

Enablement rules

sub_sellers

cards

transactions

checkouts

webhooks

antifraud

3ds

crossborder

financial

conciliation

Sandbox and Production

Error Object

Examples