Services

All requests require your API key in the X-API-Key header. Paths are relative to the environment endpoint.

Service	Method	Resource
Onboard new merchant	POST	`/services/apexrest/partnerapi/v2/merchant`
Onboard additional merchant account	POST	`/services/apexrest/partnerapi/v2/account`
Upload onboarding document	POST	`/services/apexrest/partnerapi/v2/merchant/<onboardingReference>/<fileType>/<fileReference>/document`
Finalize onboarding	POST	`/services/apexrest/partnerapi/v2/merchant/<onboardingReference>/complete`
Retrieve merchant keys	GET	`/services/apexrest/partnerapi/v1/merchant/keys`
Retrieve merchant status	GET	`/services/apexrest/partnerapi/v1/merchant/status`
Retrieve configured payment methods	GET	`/services/apexrest/partnerapi/v1/paymentMethods`

Onboard new merchant

Onboards a new merchant at Buckaroo with the relevant data.

Method	Resource
POST	`/services/apexrest/partnerapi/v2/merchant`

Request header

Content-Type: application/json
X-API-Key: <your key>

Request body

{
  "isTest": false,
  "partnerReference": "e5d957191987902cb1d80d5b43c528136d90c06c9c2f5556bbe341f2e6d41f5f",
  "webshopURL": "https://test.site",
  "secretKey": "optional64LongSelfDefinedKey",
  "paymentMethods": [
    "iDEAL"
  ],
  "deliveryStreet": "someStreet",
  "deliveryHouseNumber": "1",
  "deliveryPostalCode": "0000AA",
  "deliveryCity": "Traiectum",
  "deliveryISOCountryCode": "NL",
  "terminalProducts": [
    {
      "code": "N4",
      "acquisitionMethod": "L",
      "leaseTerm": 3,
      "quantity": 1,
      "storeName": "someName",
      "storeStreet": "someStreet",
      "storeHouseNumber": "1",
      "storePostalCode": "0000AA",
      "storeCity": "Traiectum",
      "storeISOCountryCode": "NL"
    },
    {
      "code": "N4",
      "acquisitionMethod": "B",
      "quantity": 1,
      "storeName": "someName",
      "storeStreet": "someStreet",
      "storeHouseNumber": "1",
      "storePostalCode": "0000AA",
      "storeCity": "Traiectum",
      "storeISOCountryCode": "NL"
    },
    {
      "code": "_A0577",
      "acquisitionMethod": "B",
      "quantity": 2
    }
  ],
  "company": {
    "name": "testName",
    "streetAndNumber": "teststreet 1",
    "postalCode": "1000 AA",
    "city": "Traiectum",
    "cocRegisteredCountryCode": "DE",
    "legalEntityTypeIsUnincorporatedAssociation": "false",
    "legalEntityType": "Aktiengesellschaft (AG)",
    "cocNumber": "04060983",
    "sbiCode": "13245",
    "vatNumber": "NL808888614.B01",
    "primaryIBAN": "NL02INGB8635612388",
    "primaryIBANAscription": "Buckaroo, Traiectum",
    "secondaryIBAN": "NL70RABO3135536696",
    "secondaryIBANAscription": "Buckaroo, Traiectum"
  },
  "contact": {
    "firstName": "test the",
    "lastName": "tester",
    "email": "[email protected]",
    "password": "Welkom123!",
    "phone": "+31713864315",
    "language": "nl_NL"
  },
  "legalPersons": [
    {
      "isDirector": true,
      "isSignatory": true,
      "isUBO": true,
      "firstName": "test the",
      "lastName": "tester",
      "jobTitle": "CEO",
      "streetAndNumber": "astreet 45",
      "postalCode": "0000 AA",
      "city": "Traiectum",
      "countryCode": "NL",
      "nationalityCountryCode": "NL",
      "dateOfBirth": "1980-07-01",
      "placeOfBirth": "Traiectum",
      "countryCodeOfBirth": "NL",
      "percentageOfShares": 60,
      "email": "[email protected]",
      "phone": "+31713864315",
      "verifiedByMerchant": true
    }
  ]
}

General fields

Field	Description	Type	Required	Notes
`partnerReference`	Unique ID of the partner.	String	Yes	Max. 255 characters.
`webshopURL`	URL of the company being onboarded.	String	Yes	Always include `https://`. Max. 255 characters.
`secretKey`	Secret key for the Buckaroo payment API.	String	No	Max. 64 characters.
`paymentMethods`	Payment methods the company wants to use.	String array	Yes for online, no for POS	See payment method values.
`deliveryStreet`	Delivery address for terminal products and accessories.	String	Yes, if a terminal product or accessory is included	Max. 255 characters.
`deliveryHouseNumber`	Delivery address for terminal products and accessories.	String	Yes, if a terminal product or accessory is included	Max. 25 characters.
`deliveryHouseNumberExtension`	Delivery address for terminal products and accessories.	String	Yes, if a terminal product or accessory is included	Max. 25 characters.
`deliveryAdditionalAddressLine`	Delivery address for terminal products and accessories.	String	Yes, if a terminal product or accessory is included	Max. 25 characters.
`deliveryPostalCode`	Delivery address for terminal products and accessories.	String	Yes, if a terminal product or accessory is included	Max. 25 characters.
`deliveryCity`	Delivery address for terminal products and accessories.	String	Yes, if a terminal product or accessory is included	Max. 255 characters.
`deliveryISOCountryCode`	Delivery address for terminal products and accessories.	String	Yes, if a terminal product or accessory is included	Max. 3 characters.

Payment method values

The following values can be used in paymentMethods. The available list may differ per partnership.

iDEAL
iDEAL QR
Bancontact
Bancontact WIP
Bancontact WIP One-Click
Creditcards & Debitcards
Mastercard
Visa
Maestro
V PAY
Carte Bancaire
Carte Bleue
Dankort
Apple Pay
PayPal
Belfius
KBC payment button
Sofort
EPS
Giropay
Payconiq
Billink
Billink België
Billink Nederland
Riverty
Bank Transfer
Bank Overschrijvingen
Direct Debit (SEPA)
PayPerEmail
Credit Management
VVV Cadeaukaart
Payment Domain
Payout per transaction

Terminal product fields (optional)

Field	Description	Type	Required	Notes
`code`	Product code.	String	Yes	Possible values are communicated separately. Max. 32 characters.
`acquisitionMethod`	Type of acquisition: buy or lease.	String	Yes	`B` (buy) or `L` (lease).
`leaseTerm`	Length of the lease period.	Integer	Yes, if `acquisitionMethod` is `L`	`null`, `1`, `3` or `5`.
`quantity`	Quantity.	Integer	Yes
`storeName`	Store the terminal product and accessories are delivered to.	String	Yes, if a transaction service, terminal product or accessory is included	Max. 255 characters.
`storeStreet`	Store address.	String	Yes, if a transaction service, terminal product or accessory is included	Max. 255 characters.
`storeHouseNumber`	Store address.	String	Yes, if a transaction service, terminal product or accessory is included	Max. 25 characters.
`storeHouseNumberExtension`	Store address.	String	Yes, if a transaction service, terminal product or accessory is included	Max. 25 characters.
`storeAdditionalAddressLine`	Store address.	String	Yes, if a transaction service, terminal product or accessory is included	Max. 25 characters.
`storePostalCode`	Store address.	String	Yes, if a transaction service, terminal product or accessory is included	Max. 25 characters.
`storeCity`	Store address.	String	Yes, if a transaction service, terminal product or accessory is included	Max. 255 characters.
`storeISOCountryCode`	Store address.	String	Yes, if a transaction service, terminal product or accessory is included	Max. 3 characters.

Company fields

Field	Description	Type	Required	Notes
`name`	Name of the company being onboarded.	String	Yes	Max. 255 characters.
`streetAndNumber`	Street and house number of the company address.	String	Yes	Max. 255 characters.
`postalCode`	Postal code of the company address.	String	Yes	Max. 20 characters.
`city`	City of the company address.	String	Yes	Max. 40 characters.
`cocRegisteredCountryCode`	Country where the company is registered with the Chamber of Commerce.	String	Yes	ISO 3166 country code. Max. 255 characters.
`cocNumber`	Chamber of Commerce number (or KBO number) of the company.	String	Yes	Max. 255 characters.
`legalEntityType`	Legal form of the company.	String	Yes	Allowed values depend on `cocRegisteredCountryCode`. See legal entity types.
`vatNumber`	VAT number of the company.	String	No	Max. 255 characters.
`sbiCode`	SBI code describing the company's activities.	String	No	Max. 5 characters.
`primaryIBAN`	IBAN of the company's primary bank account.	String	Yes	Max. 255 characters.
`secondaryIBAN`	IBAN of the company's invoice bank account.	String	No	Max. 34 characters.
`secondaryIBANAscription`	Account holder name of the secondary bank account.	String	No	Max. 255 characters.

Legal entity types

Allowed values for legalEntityType, depending on cocRegisteredCountryCode:

Besloten vennootschap (B.V.)
Commanditaire vennootschap (C.V.)
Coöperatie
Eenmanszaak
Maatschap
Naamloze vennootschap (N.V.)
Stichting
Vennootschap onder Firma (V.O.F.)
Vereniging
Besloten vennootschap met beperkte aansprakelijkheid (BVBA)
Commanditaire vennootschap op aandelen (Comm. VA)
Coöperatieve vennootschap met onbeperkte en hoofdelijke aansprakelijkheid (CVOA)
Coöperatieve vennootschap met beperkte aansprakelijkheid (CVBA)
Economisch samenwerkingsverband (ESV)
Europese coöperatieve vennootschap (SCE)
Europese vennootschap (SE)
Europese economisch samenwerkingsverband (EESV)
Feitelijke vereniging
Landbouwvennootschap (L.V.)
Vereniging zonder winstoogmerk
Aktiengesellschaft (AG)
Eingetragene Genossenschaft (eG)
Eingetragener Verein (e.V.)
Europäische Wirtschaftliche Interessensvereinigung (EWIV)
Gemeinnützige Gesellschaft mit beschränkter Haftung (gGmbH)
Gesellschaft bürgerlichen Rechts (GbR)
Gesellschaft mit beschränkter Haftung (GmbH)
Kommanditgesellschaft auf Aktien (KGaA)
Kommanditgesellschaft (KG)
Nicht eingetragener Verein
Offene Handelsgesellschaft (OHG)
Partnerschaftsgesellschaft (PartGG)
Stiftung des privaten Rechts
Versicherungsverein auf Gegenseitigkeit
Einzelfirma
Unternehmergesellschaft mit beschränkter Haftung (UG)
Société à Responsabilité Limitée (SARL)
Entreprise Unipersonnelle à Responsabilité Limitée (EURL)
Société Anonyme (SA)
Société par Actions Simplifiées (SAS)
Société par Actions Simplifiées Unipersonnelle (SASU)
Société Civile Professionnelle (SCP)
Auto-entrepreneur (AE)
Entreprise Agricole à Responsabilité Limitée (EARL)
Entreprise Individuelle (EI)
Entreprise Individuelle à Responsabilité Limitée (EIRL)
Groupement Agricole d'Exploitation en Commun (GAEC)
Groupement Foncier Agricole (GFA)
Microentreprise
Société en Commandite par Actions (SCA)
Société Civile d'Exploitation Agricole (SCEA)
Société Civile Immobilière (SCI)
Société en Commandite Simple (SCS)
Société d'Exercice Libéral à Forme Anonyme (SELAFA)
Société d'Exercice Libéral à Responsabilité Limitée (SELARL)
Société d'Exercice Libéral par Actions Simplifiée (SELAS)
Other

Contact fields

Field	Description	Type	Required	Notes
`firstName`	First name of the contact.	String	Yes	Max. 40 characters.
`lastName`	Last name of the contact.	String	Yes	Max. 80 characters.
`email`	Email address where the contact receives the onboarding email.	String	Yes	Max. 80 characters.
`password`	Password for the contact's first login to the onboarding portal.	String	Usually not required	Max. 255 characters.

Legal persons fields (optional)

"Required" applies when the legalPersons array is used.

Field	Description	Type	Required	Notes
`isDirector`	Whether the person is a director.	Boolean	Yes	`true` / `false`
`isSignatory`	Whether the person is a signatory.	Boolean	Yes	`true` / `false`
`isUBO`	Whether the person is an ultimate beneficial owner (UBO).	Boolean	Yes	`true` / `false`
`firstName`	First name of the person.	String	Yes	Max. 40 characters.
`lastName`	Last name of the person.	String	Yes	Max. 80 characters.
`jobTitle`	Job title of the person.	String	No	Max. 255 characters.
`streetAndNumber`	Street and house number of the person's address.	String	No	Max. 255 characters.
`postalCode`	Postal code of the person's address.	String	No	Max. 20 characters.
`city`	City of the person's address.	String	No	Max. 40 characters.
`countryCode`	Country code of the person's address.	String	No	Max. 3 characters.
`nationalityCountryCode`	Country code of the person's nationality.	String	No	Max. 3 characters.
`dateOfBirth`	Date of birth of the person.	Date	Yes
`placeOfBirth`	Place of birth of the person.	String	No	Max. 255 characters.
`countryCodeOfBirth`	Country code of the person's place of birth.	String	No	Max. 3 characters.
`percentageOfShares`	Percentage of shares the person holds.	Decimal	No	0 to 100.
`email`	Email address of the person.	String	No	Max. 80 characters.
`phone`	Phone number of the person.	String	No	Max. 40 characters.
`verifiedByMerchant`	Whether the merchant has verified this information.	Boolean	Yes	`true` / `false`

Response

The response contains an onboardingReference and, if documents are needed to complete the onboarding, a list of them. Upload each document to its endpoint with Upload onboarding document.

Example success response:

{
  "onboardingReference": "2ee5f5f5-c976-4c3c-a6a6-0204bd091ea1",
  "expectedDocumentsToCompleteOnboarding": [
    {
      "endpoint": "/services/apexrest/partnerapi/v2/merchant/2ee5f5f5-c976-4c3c-a6a6-0204bd091ea1/connectionAgreement/6bc85fe3-2622-4494-b3b3-1a8b6ffc8751/document?partnerReference=e5d957191987902cb1d80d5b43c528136d90c06c9c2f5556bbe341f2e6d41f5f",
      "documentType": "connectionAgreement",
      "documentDescription": "Signed connection agreement"
    },
    {
      "endpoint": "/services/apexrest/partnerapi/v2/merchant/2ee5f5f5-c976-4c3c-a6a6-0204bd091ea1/cocExtract/a8643542-9a1c-43d3-a7e7-e9ebbfc0590e/document?partnerReference=e5d957191987902cb1d80d5b43c528136d90c06c9c2f5556bbe341f2e6d41f5f",
      "documentType": "cocExtract",
      "documentDescription": "Extract chamber of commerce"
    },
    {
      "endpoint": "/services/apexrest/partnerapi/v2/merchant/2ee5f5f5-c976-4c3c-a6a6-0204bd091ea1/bankStatement/b2ad3ae1-5062-4b8b-b676-88b51570d093/document?partnerReference=e5d957191987902cb1d80d5b43c528136d90c06c9c2f5556bbe341f2e6d41f5f",
      "documentType": "bankStatement",
      "documentDescription": "Bank Statement for NL02INGB8635612388"
    },
    {
      "endpoint": "/services/apexrest/partnerapi/v2/merchant/2ee5f5f5-c976-4c3c-a6a6-0204bd091ea1/bankStatement/cf06e843-4574-4bff-9797-457e3b05d73e/document?partnerReference=e5d957191987902cb1d80d5b43c528136d90c06c9c2f5556bbe341f2e6d41f5f",
      "documentType": "bankStatement",
      "documentDescription": "Bank Statement for NL70RABO3135536696"
    },
    {
      "endpoint": "/services/apexrest/partnerapi/v2/merchant/2ee5f5f5-c976-4c3c-a6a6-0204bd091ea1/legalPerson/ad541b0c-da65-4beb-8787-4ca22a533613/document?partnerReference=e5d957191987902cb1d80d5b43c528136d90c06c9c2f5556bbe341f2e6d41f5f",
      "documentType": "legalPerson",
      "documentDescription": "Copy Identification for test the tester (.legalPersons[0])"
    }
  ]
}

Example error response:

{ "errors": [".paymentMethods: Product Bancontact does not exist"] }

Onboard additional merchant account

Onboards an additional merchant account for a merchant that has already been onboarded.

Method	Resource
POST	`/services/apexrest/partnerapi/v2/account`

Request header

Content-Type: application/json
X-API-Key: <your key>

Request body

Identical to Onboard new merchant, with these differences:

The request is validated against an existing merchant with the same cocNumber and cocRegisteredCountryCode.
legalPersons is optional.

Response

Identical to Onboard new merchant.

Upload onboarding document

Uploads a document required to complete the merchant onboarding. The full resource URL for each document is returned in expectedDocumentsToCompleteOnboarding by Onboard new merchant or Onboard additional merchant account.

Method	Resource
POST	`/services/apexrest/partnerapi/v2/merchant/<onboardingReference>/<fileType>/<fileReference>/document?partnerReference=<partnerReference>`

onboardingReference is the reference returned by Onboard new merchant or Onboard additional merchant account.

Request header

Content-Type: <content type of the file>
Content-Transfer-Encoding: base64
X-API-Key: <your key>

Supported content types

application/pdf
image/jpeg
image/gif
image/png
image/tiff
application/vnd.ms-powerpoint
application/vnd.openxmlformats-officedocument.presentationml.presentation
application/msword
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/vnd.ms-excel
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Request body

The file content, Base64-encoded.

Response

Example success response: HTTP status 200.

Example error response:

{ "errors": [".onboardingReference: Onboarding reference does not exist"] }

Finalize onboarding

Marks the onboarding as complete after all documents requested in the response of Onboard new merchant or Onboard additional merchant account have been uploaded.

Method	Resource
POST	`/services/apexrest/partnerapi/v2/merchant/<onboardingReference>/complete?partnerReference=<partnerReference>`

onboardingReference is the reference returned by Onboard new merchant or Onboard additional merchant account.

Request header

X-API-Key: <your key>

Request body

Empty.

Response

Example success response: HTTP status 200.

Example error response:

{ "errors": ["No documents were found related to onboarding"] }

Retrieve merchant keys

Retrieves the merchant's API keys.

Method	Resource
GET	`/services/apexrest/partnerapi/v1/merchant/keys?onboardingReference=<onboardingReference>&partnerReference=<partnerReference>`

Request header

X-API-Key: <your key>

Response

Example success response:

{
  "webSiteKey": "abcdef",
  "plazaUserName": "username",
  "plazaUserKey": "abc"
}

Example error response:

{ "errors": ["Keys not available, check onboarding status."] }

Retrieve merchant status

Retrieves the merchant's onboarding status.

Method	Resource
GET	`/services/apexrest/partnerapi/v1/merchant/status?onboardingReference=<onboardingReference>&partnerReference=<partnerReference>`

Request header

X-API-Key: <your key>

Response

Example success response:

{
  "status": "Waiting for Merchant",
  "readyForKYCInput": true,
  "keysRetrieved": false,
  "keysAvailable": true,
  "merchantGUID": "someKey"
}

Example error response:

{ "errors": [".partnerReference: Invalid partnerReference"] }

Retrieve configured payment methods

Retrieves the active payment methods for a merchant, including pricing.

Method	Resource
GET	`/services/apexrest/partnerapi/v1/paymentMethods?partnerReference=<partnerReference>`

Request header

X-API-Key: <your key>

Response

Example success response:

{
  "paymentMethods": [
    {
      "priceParts": [
        { "gatewayFee": 0.23, "description": "Debitcards Consumers (EU)", "currencyISOCode": "EUR", "commissionPercentage": 1.2 },
        { "gatewayFee": 0.23, "description": "Refund: Debitcards Consumers (EU)", "currencyISOCode": "EUR", "commissionPercentage": 1.2 },
        { "gatewayFee": 0.23, "description": "Creditcards Consumers (EU)", "currencyISOCode": "EUR", "commissionPercentage": 1.8 },
        { "gatewayFee": 0.23, "description": "Refund: Creditcards Consumers (EU)", "currencyISOCode": "EUR", "commissionPercentage": 1.8 },
        { "gatewayFee": 0.23, "description": "Business- + Non EU Cards", "currencyISOCode": "EUR", "commissionPercentage": 2.8 },
        { "gatewayFee": 0.23, "description": "Refund: Business- + Non EU Cards", "currencyISOCode": "EUR", "commissionPercentage": 2.8 }
      ],
      "name": "Creditcards and Debitcards",
      "label": "Creditcards and Debitcards"
    },
    {
      "priceParts": [],
      "name": "Sofort",
      "label": "Sofort"
    },
    {
      "priceParts": [
        { "gatewayFee": 0.26, "description": "iDEAL", "currencyISOCode": "EUR", "commissionPercentage": 0 }
      ],
      "name": "iDEAL",
      "label": "iDEAL"
    },
    {
      "priceParts": [
        { "gatewayFee": 0.37, "description": "Bancontact", "currencyISOCode": "EUR", "commissionPercentage": 0 }
      ],
      "name": "Bancontact",
      "label": "Bancontact"
    },
    {
      "priceParts": [
        { "gatewayFee": 0.1, "description": "PayPal", "currencyISOCode": "EUR", "commissionPercentage": 0 },
        { "gatewayFee": 0.23, "description": "Refunds (Processing)", "currencyISOCode": "EUR", "commissionPercentage": 0 }
      ],
      "name": "PayPal",
      "label": "PayPal"
    },
    {
      "priceParts": [
        { "gatewayFee": 0.23, "description": "Bank Transfer", "currencyISOCode": "EUR", "commissionPercentage": 0 }
      ],
      "name": "Bank Transfer",
      "label": "Bank Transfer"
    }
  ]
}

Example error response:

{ "errors": [".partnerReference: Invalid partnerReference"] }