Finmid Buyer API
The Buyer API from Finmid — 4 operation(s) for buyer.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/finmid:finmid-buyer-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: B2B Payments Buyer API
version: v2.3
servers:
- url: https://sandbox.finmid.com
description: Sandbox
- url: https://api.finmid.com
description: Live
security:
- apiKeyScheme: []
tags:
- name: Buyer
paths:
/api/v2/b2b-payments/buyers:
post:
tags:
- Buyer
operationId: create-buyer-v2
summary: Create Buyer
description: 'Let''s create/onboard a new buyer. For this you''ll need 2 things:
1. Create a new ID for this buyer (should map to your internal identifier)
2. The buyer''s legal information. ⚠️ Note that one of either business_registration_number or tax_number **must** be provided on creation.
> 📘
>
> You should create a buyer entity for every buyer on your platform that can be part of a lending transaction.'
requestBody:
content:
application/json:
schema:
required:
- id
- legal_name
- legal_address
- email
type: object
properties:
id:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1payment-requests~1{id}~1cancel/put/parameters/0/schema/allOf/0'
- description: 'Custom ID of the buyer, should map to your internal identifier. Must consist only of a-z, A-Z, 0-9 and .-_ characters, and length should not exceed 100 characters.
'
example: buyer-123
legal_name:
allOf:
- type: string
maxLength: 100
- description: 'Business name of the buyer (not necessarily the brand name). This should be the name as stated in official business registers.
'
example: Tante Emma GmbH
business_registration_number:
allOf:
- type: string
maxLength: 100
- description: 'Registration number of the buyer from the commercial register.
'
example: HRB123456B
tax_number:
allOf:
- type: string
maxLength: 100
- description: 'Identification number assigned to the buyer by local tax office. > ⚠️ This field must be provided in case the business registration number is omitted.
'
example: 12/345/67890
email:
allOf:
- type: string
format: email
pattern: ^(?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])$
- description: Email address of the buyer.
example: emma@example.com
phone:
allOf:
- type: string
pattern: ^\+[0-9]+$
minLength: 4
maxLength: 30
- description: Phone number of the buyer. Must be provided in the international format, e.g. `+49123456789`.
example: '+49123456789'
legal_address:
allOf:
- type: object
properties:
address_line_1:
description: First line of the address. This is usually a street name and house number combination.
type: string
maxLength: 100
address_line_2:
description: Second address line for any required additions to the first line. A typical example is c/o information.
type: string
maxLength: 100
postal_code:
description: Postal code of the address.
type: string
maxLength: 20
city:
description: City of the address.
type: string
maxLength: 100
state:
description: State of the address (if applicable).
type: string
maxLength: 100
country:
description: Country code (ISO 3166-1 alpha-3, e.g. `DEU`, `USA`).
type: string
example: DEU
enum:
- ABW
- AFG
- AGO
- AIA
- ALA
- ALB
- AND
- ARE
- ARG
- ARM
- ASM
- ATA
- ATF
- ATG
- AUS
- AUT
- AZE
- BDI
- BEL
- BEN
- BES
- BFA
- BGD
- BGR
- BHR
- BHS
- BIH
- BLM
- BLR
- BLZ
- BMU
- BOL
- BRA
- BRB
- BRN
- BTN
- BVT
- BWA
- CAF
- CAN
- CCK
- CHE
- CHL
- CHN
- CIV
- CMR
- COD
- COG
- COK
- COL
- COM
- CPV
- CRI
- CUB
- CUW
- CXR
- CYM
- CYP
- CZE
- DEU
- DJI
- DMA
- DNK
- DOM
- DZA
- ECU
- EGY
- ERI
- ESH
- ESP
- EST
- ETH
- FIN
- FJI
- FLK
- FRA
- FRO
- FSM
- GAB
- GBR
- GEO
- GGY
- GHA
- GIB
- GIN
- GLP
- GMB
- GNB
- GNQ
- GRC
- GRD
- GRL
- GTM
- GUF
- GUM
- GUY
- HKG
- HMD
- HND
- HRV
- HTI
- HUN
- IDN
- IMN
- IND
- IOT
- IRL
- IRN
- IRQ
- ISL
- ISR
- ITA
- JAM
- JEY
- JOR
- JPN
- KAZ
- KEN
- KGZ
- KHM
- KIR
- KNA
- KOR
- KWT
- LAO
- LBN
- LBR
- LBY
- LCA
- LIE
- LKA
- LSO
- LTU
- LUX
- LVA
- MAC
- MAF
- MAR
- MCO
- MDA
- MDG
- MDV
- MEX
- MHL
- MKD
- MLI
- MLT
- MMR
- MNE
- MNG
- MNP
- MOZ
- MRT
- MSR
- MTQ
- MUS
- MWI
- MYS
- MYT
- NAM
- NCL
- NER
- NFK
- NGA
- NIC
- NIU
- NLD
- NOR
- NPL
- NRU
- NZL
- OMN
- PAK
- PAN
- PCN
- PER
- PHL
- PLW
- PNG
- POL
- PRI
- PRK
- PRT
- PRY
- PSE
- PYF
- QAT
- REU
- ROU
- RUS
- RWA
- SAU
- SDN
- SEN
- SGP
- SGS
- SHN
- SJM
- SLB
- SLE
- SLV
- SMR
- SOM
- SPM
- SRB
- SSD
- STP
- SUR
- SVK
- SVN
- SWE
- SWZ
- SXM
- SYC
- SYR
- TCA
- TCD
- TGO
- THA
- TJK
- TKL
- TKM
- TLS
- TON
- TTO
- TUN
- TUR
- TUV
- TWN
- TZA
- UGA
- UKR
- UMI
- URY
- USA
- UZB
- VAT
- VCT
- VEN
- VGB
- VIR
- VNM
- VUT
- WLF
- WSM
- YEM
- ZAF
- ZMB
- ZWE
- XKX
- description: Legal address of the buyer.
required:
- address_line_1
- postal_code
- city
- country
example:
address_line_1: Musterstraße 1
postal_code: '11225'
city: Musterstadt
state: Saarland
country: DEU
required: true
responses:
'200':
description: The buyer was created successfully.
content:
application/json:
schema:
type: object
required:
- id
- status
- legal_name
- legal_address
properties:
id:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1payment-requests~1{id}~1cancel/put/parameters/0/schema/allOf/0'
- description: ID of the buyer.
example: buyer-123
status:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers~1list/get/parameters/0/schema/items'
- description: Current status of the buyer.
example: PENDING
legal_name:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/legal_name/allOf/0'
- description: Legal name of the buyer's business.
example: Tante Emma GmbH
business_registration_number:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/business_registration_number/allOf/0'
- description: Business registration number of the buyer.
example: HRB123456B
tax_number:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/tax_number/allOf/0'
- description: 'Identification number assigned to the buyer by local tax office.
'
example: 12/345/67890
email:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/email/allOf/0'
- description: Email address of the buyer.
example: emma@example.com
phone:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/phone/allOf/0'
- description: Phone number of the buyer in the international format (e.g. `+49123456789`).
example: '+49123456789'
legal_address:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/legal_address/allOf/0'
- description: Legal address of the buyer.
required:
- address_line_1
- postal_code
- city
- country
example:
address_line_1: Musterstraße 1
postal_code: '11225'
city: Musterstadt
state: Saarland
country: DEU
'400':
description: The request is invalid and failed validation.
content:
application/json:
schema:
allOf:
- type: object
required:
- code
- description
properties:
code:
allOf:
- type: string
enum:
- validation_error
- server_error
- buyer_invalid
- seller_invalid
- platform_invalid
- payment_request_invalid
- line_item_invalid
- buyer_conflict
- seller_conflict
- payment_request_conflict
- business_conflict
- business_not_found
- document_already_exists
- incoming_webhook_conflict
- mcc_not_eligible
- offer_group_not_active
- offer_group_not_found
- platform_check_already_consumed
- platform_check_not_required
- platform_check_unavailable
- platform_checks_not_enabled
- description: Code that represents the kind of error.
description:
allOf:
- type: string
- description: A more detailed description of the error.
- type: object
properties:
code:
type: string
enum:
- validation_error
description:
example: legal_name must not be blank
'401':
description: Missing or invalid API key. Could not authenticate API request.
'409':
description: Buyer exists already.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/400/content/application~1json/schema/allOf/0'
- type: object
properties:
code:
type: string
enum:
- buyer_conflict
description:
example: Cannot create this buyer because it exists already
'500':
description: An unexpected server error occurred. You should try again later or contact finmid support.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/400/content/application~1json/schema/allOf/0'
- properties:
code:
type: string
enum:
- server_error
description:
example: Our server was hit by a meteorite 💥.
examples:
server_error:
value:
code: server_error
description: Internal processing error
/api/v2/b2b-payments/buyers/list:
get:
tags:
- Buyer
operationId: get-buyers-for-platform
summary: Get Buyers
description: Returns a list of buyers. Cursor-based pagination is supported and you can make use of filter parameters to change sorting or limit the results to only buyers with certain status..
parameters:
- name: status
in: query
required: false
schema:
type: array
description: 'List of buyer status. Providing one or more status only includes buyers that have one of the provided status.
'
items:
type: string
enum:
- PENDING
- ACTIVE
- INACTIVE
- REJECTED
- SUSPENDED
- name: sort_by
in: query
required: false
schema:
description: Sorting of the results.
type: string
enum:
- CREATED_ASC
- CREATED_DESC
- name: cursor
in: query
required: false
schema:
description: A cursor used for pagination.
example: cGktMTIzNDV8MjAyMi0wNC0yOFQwNjowOToxNyswMDowMAo=
type: string
- name: limit
in: query
required: false
schema:
description: Limits the amount of results per page.
example: 20
type: integer
format: int32
default: 100
minimum: 1
maximum: 100
responses:
'200':
description: A result set containing details of buyers.
content:
application/json:
schema:
type: object
properties:
metadata:
type: object
properties:
next_cursor:
type: string
description: A cursor pointing to the beginning of the next page.
example: ddTkVYVHxmMzA1ZjBlNi00YzM2LTQwZmEtOTI5YS0yZjJiODJlYjU2ZjR8MjAyMi0xMC0yOFQxMDoxMDoyOS4zMTkzMDlafA
previous_cursor:
type: string
description: A cursor pointing to the beginning of the previous page.
example: ccUFJFVklPVVN8ZjhjODRmYzctZDIyMS00NzYxLThlMTktN2QxYTM5ZTIyZDgxfDIwMjItMTEtMDJUMTM6NTE6MTkuMzI3MTk1Wnw
data:
description: List of Buyers.
type: array
items:
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/200/content/application~1json/schema'
'401':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/401'
'500':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/500'
/api/v2/b2b-payments/buyers/{id}:
get:
tags:
- Buyer
operationId: get-buyer-v2
summary: Get Buyer
description: For getting a certain buyer's details, you'll only need the buyer's ID specified on creation.
parameters:
- name: id
description: ID of the buyer as specified on buyer creation.
in: path
required: true
schema:
$ref: '#/paths/~1api~1v2~1b2b-payments~1payment-requests~1{id}~1cancel/put/parameters/0/schema/allOf/0'
responses:
'200':
description: Details of the requested buyer.
content:
application/json:
schema:
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/200/content/application~1json/schema'
'401':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/401'
'404':
description: No buyer found for the given ID.
content:
application/json:
schema:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/400/content/application~1json/schema/allOf/0'
- type: object
properties:
code:
type: string
enum:
- buyer_invalid
description:
example: Buyer with ID buyer-000 does not exist
'500':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/500'
patch:
tags:
- Buyer
x-tags:
- PatchBuyer
operationId: update-buyer-v2
summary: Update Buyer
description: 'Update a buyer if certain data changes on your platform. For this you''ll need:
1. The buyer''s ID specified on creation
2. The data you want to change'
parameters:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers~1{id}/get/parameters/0'
requestBody:
content:
application/json:
schema:
type: object
properties:
legal_name:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/legal_name/allOf/0'
- description: New legal name of the business.
example: Onkel Ernie GmbH
email:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/email/allOf/0'
- description: New email address of the buyer.
example: ernie@example.com
phone:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/phone/allOf/0'
- description: New phone number of the buyer.
example: '+49987654321'
legal_address:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/requestBody/content/application~1json/schema/properties/legal_address/allOf/0'
- description: New legal address of the buyer.
example:
address_line_1: Mustergasse 1
postal_code: '12345'
city: Musterstadt
state: Niedersachsen
country: DEU
required: true
responses:
'200':
description: Updated buyer details.
content:
application/json:
schema:
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/200/content/application~1json/schema'
'401':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/401'
'404':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers~1{id}/get/responses/404'
'500':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/500'
/api/v2/b2b-payments/buyers/{id}/payment-limit:
get:
tags:
- Buyer
operationId: get-buyer-limit-v2
summary: Get Buyer Limit
description: 'Get estimated buyer limit in a target currency.
> 📘
>
> Note: this limit is an estimate and subject to change depending on a specific payment request parameters. To verify if specific purchase can be financed please use Check Payment Request API'
parameters:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers~1{id}/get/parameters/0'
- name: currency
in: query
required: false
schema:
allOf:
- description: Three-letter currency code (ISO 4217). Supported currencies `EUR`, `GBP`, and `USD`.
type: string
example: EUR
responses:
'200':
description: Estimated limit for the buyer.
content:
application/json:
schema:
type: object
required:
- estimated_remaining_limit
- currency
- total_limit
- used_limit
- pending_requests_amount
properties:
estimated_remaining_limit:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1payment-requests/post/requestBody/content/application~1json/schema/properties/total_amount/allOf/0'
- description: Estimated available amount which could be approved for payment request for the buyer.
example: 9000
total_limit:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1payment-requests/post/requestBody/content/application~1json/schema/properties/total_amount/allOf/0'
- description: Estimated maximum amount of all open buyer's payment requests.
example: 10000
used_limit:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1payment-requests/post/requestBody/content/application~1json/schema/properties/total_amount/allOf/0'
- description: Sum of all pending and reserved buyer's payment requests.
example: 1000
pending_requests_amount:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1payment-requests/post/requestBody/content/application~1json/schema/properties/total_amount/allOf/0'
- description: Sum of all reserved but not pending for repayment buyer's payment requests.
example: 500
currency:
allOf:
- $ref: '#/paths/~1api~1v2~1b2b-payments~1buyers~1{id}~1payment-limit/get/parameters/1/schema/allOf/0'
- description: Three-letter currency code (ISO 4217). Supported currencies `EUR` and `GBP`
example: EUR
'401':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/401'
'404':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers~1{id}/get/responses/404'
'500':
$ref: '#/paths/~1api~1v2~1b2b-payments~1buyers/post/responses/500'
components:
securitySchemes:
apiKeyScheme:
type: apiKey
in: header
name: X-API-KEY
x-provenance:
method: searched
source: https://docs.finmid.com/reference
harvested: '2026-10-14'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://docs.finmid.com/reference/cancel-payment-request-v2.md
- https://docs.finmid.com/reference/create-buyer-v2.md
- https://docs.finmid.com/reference/create-payment-request-payout.md
- https://docs.finmid.com/reference/create-payment-request-v2.md
- https://docs.finmid.com/reference/create-seller-v2.md
- https://docs.finmid.com/reference/get-buyer-limit-v2.md
- https://docs.finmid.com/reference/get-buyer-v2.md
- https://docs.finmid.com/reference/get-buyers-for-platform.md
- https://docs.finmid.com/reference/get-payment-request-v2.md
- https://docs.finmid.com/reference/get-payment-requests-v2.md
- https://docs.finmid.com/reference/get-seller-v2.md
- https://docs.finmid.com/reference/get-sellers-for-platform.md
- https://docs.finmid.com/reference/get-tasks.md
- https://docs.finmid.com/reference/simulate-buyer-v2.md
- https://docs.finmid.com/reference/simulate-payment-request-repayment-v2.md
- https://docs.finmid.com/reference/simulate-seller-v2.md
- https://docs.finmid.com/reference/update-buyer-v2.md
- https://docs.finmid.com/reference/update-payment-request-v2.md
- https://docs.finmid.com/reference/update-seller-bank-account-v2.md
- https://docs.finmid.com/reference/update-seller-v2.md
- https://docs.finmid.com/reference/upload-payment-request-documents.md
merge:
pages: 21
deduped: 119
conflicts_kept_first: 0