Quickstart
Not sure where to start? Find below the testing steps for you to start exploring the Treezor API capabilities in Sandbox.
Tip – Rely on Treezor Webhooks and Dashboard
These tools will allow you to better visualize the results of your testing.
Authenticate to your Sandbox
Reading – Related documentation in API Basics
Environments | Credentials | Authentication | Scope & Permissions
Once you have your client_id and client_secret for your Sandbox environment, you can generate your Json Web Token that you will use to authenticate your API requests.
bash
curl -X POST {baseUrl}/oauth/token \
--form 'grant_type="client_credentials"' \ // required
--form 'client_id="<YOUR_CLIENT_ID>"' \ // required
--form 'client_secret="<YOUR_CLIENT_SECRET>"' // required
# --form 'scope="<SCOPE>"' // optional (ex. "admin", "admin read_all")Returns the access_token for you to use in the Authorization header of all your subsequent requests.
json
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "eyJ0eX[...]PcOIkQ"
}
Note – The access token expires after 1 hour
Read how to extend its lifetime in the Authentication article.
Create a User
In this example, your end user is a physical person to whom you will offer banking services thanks to Treezor.
You can use the following request to create a physical user.
bash
curl -X POST {baseUrl}/v1/users \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is a {payload} example:
json
{
"userTypeId":1, // required, 1 is for Physical User
"specifiedUSPerson":0, // required
"title": "M",
"firstname":"Alex",
"lastname":"Oak",
"email":"aoak@example.com", // required, must be unique
"address1":"101 Willow lane", // required to create a Card later on
"phone":"+33102030405" // required to create a Card later on
}Returns the new User with its id (1545392) that you will use for the next steps.
json
{
"users": [
{
"userId": 1545392,
"userTypeId": 1,
"userStatus": "VALIDATED",
"userTag": "",
"parentUserId": 0,
"parentType": "",
"controllingPersonType": 0,
"employeeType": 0,
"specifiedUSPerson": 0,
"title": "M",
"firstname": "Alex",
"lastname": "Oak",
"middleNames": "",
"birthday": "0000-00-00",
"email": "aoak@example.com",
"address1": "101 Willow lane",
"address2": "",
"postcode": "",
"city": "",
"state": "",
"country": "",
"countryName": "",
"phone": "+33102030405",
"mobile": "",
"nationality": "",
"nationalityOther": "",
"placeOfBirth": "",
"birthCountry": "",
"occupation": "",
"incomeRange": "",
"legalName": "",
"legalNameEmbossed": "",
"legalRegistrationNumber": "",
"legalTvaNumber": "",
"legalRegistrationDate": "0000-00-00",
"legalForm": "",
"legalShareCapital": 0,
"entityType": null,
"legalSector": "",
"legalAnnualTurnOver": "",
"legalNetIncomeRange": "",
"legalNumberOfEmployeeRange": "",
"effectiveBeneficiary": 0,
"kycLevel": 0,
"kycReview": 0,
"kycReviewComment": "",
"isFreezed": 0,
"isFrozen": null,
"language": "",
"optInMailing": null,
"sepaCreditorIdentifier": "",
"taxNumber": "",
"taxResidence": "",
"position": "",
"personalAssets": "",
"createdDate": "2024-02-28 12:36:25",
"modifiedDate": "0000-00-00 00:00:00",
"walletCount": 0,
"payinCount": 0,
"totalRows": "1",
"activityOutsideEu": 0,
"economicSanctions": 0,
"residentCountriesSanctions": 0,
"involvedSanctions": 0,
"entitySanctionsQuestionnaire": 0,
"address3": null,
"timezone": null,
"occupationType": "",
"isOnStockExchange": 0,
"secondaryAddress1": "",
"secondaryAddress2": "",
"secondaryAddress3": "",
"secondaryPostcode": "",
"secondaryCity": "",
"secondaryState": "",
"secondaryCountry": "",
"clientId": "929252",
"sanctionsQuestionnaireDate": null,
"codeStatus": "110009",
"informationStatus": "",
"legalSectorType": "",
"sourceOfFunds": ""
}
]
}Note – Treezor API offers a variety of Users to fit your use cases
You could also create other types of users, such as Legal Entities and Anonymous Users. Users can also be linked by hierarchical relations referred to as parent-children relations.
Simulate User KYC validation
In real life, Users must be verified to use Treezor services. This process includes sending documents and declarative data for Treezor to manually approve the User.
In Sandbox, you can use the following request to force the KYC validation, allowing you to proceed with the next steps.
bash
curl -X PUT {baseUrl}/v1/users/{userId} \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is a {payload} example with the .validated suffix to approve the KYC in Sandbox:
json
{
"lastname":"Oak.validated"
}Returns the new User, but you might not see they are verified right away.
You need to make a /v1/users/{userId} call to see the User object with the updated kycLevel and kycReview.
json
{
"userId":1545392,
"kycLevel":"2",
"kycReview":"2"
// [...] some attributes are hidden
}Create a Wallet
Let's create a payment account, which is represented by the Wallet object in the API. We will define the previously created User as its owner.
bash
curl -X POST {baseUrl}/v1/wallets \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is a {payload} example:
json
{
"walletTypeId":10, // required, 10 = Payment Account Wallet
"tariffId": 123, // usually required, fees applied to the Wallet, as defined by your contract with Treezor
"userId":1545392, // required, attach this wallet to the previously created user
"currency":"EUR", // required
"eventName":"AO's Account" // required, name the wallet
}Returns a Wallet object, with its id (826210) and its ready-to-use IBAN:
json
{
"wallets": [
{
"walletId": 2702198,
"walletTypeId": 10,
"walletStatus": "VALIDATED",
"codeStatus": 120005,
"informationStatus": "",
"walletTag": "",
"userId": 1545392,
"userLastname": "Oak.validated",
"userFirstname": "Alex",
"jointUserId": 0,
"tariffId": 136,
"eventName": "AO's Account",
"eventAlias": "ao-s-account-65df2ab48f029",
"eventDate": "2024-03-06",
"eventMessage": "",
"eventPayinStartDate": "2024-02-28",
"eventPayinEndDate": "0000-00-00",
"contractSigned": 0,
"bic": "TRZOFR21XXX",
"iban": "FR7616798000010000270219811",
"urlImage": "",
"currency": "EUR",
"createdDate": "2024-02-28 13:44:36",
"modifiedDate": "0000-00-00 00:00:00",
"payinCount": 0,
"payoutCount": 0,
"transferCount": 0,
"solde": 0,
"authorizedBalance": 0,
"totalRows": 1,
"country": "FR"
}
]
}Note – Treezor API offers a variety of Wallets to fit your use cases
There are different types of wallets, some requiring KYC validation, some that don't.
Credit the Wallet
Let's simulate a payin into a Wallet by emulating an incoming SEPA Transfer. These fictitious funds will then be useful to further test Treezor abilities, such as payouts to external accounts, or Wallet-to-Wallet transfers.
Here is the simulation request, in which you must pass the IBAN of the wallet to credit and the amount (integer) to credit as query parameters.
bash
curl -X POST {baseUrl}/simulation/payin-sct?iban={iban}&amount={amount}' \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \Returns the id of the SCTR, its txId (transaction id) and its payinId.
json
{
"sctrs": [
{
"id": 10116,
"txId": "1zS0fKXhAuzDnNBL",
"payinId": 1287763,
"returnReasonCode": null
}
]
}Note – Discover all the ways to credit a Wallet
Treezor offers a large range of payins for you to credit wallets. Learn more in the How to credit wallets article.
Check the Wallet Balance
Let's make sure the Wallet was properly credited by checking its Balance.
Use the following request to retrieve a given Wallet Balance, with the corresponding walletId expected as a query parameter.
bash
curl -X GET {baseUrl}/v1/balances?walletId=826210 \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \Returns the Balance object, with both the Authorized Balance (authorizedBalance) and Balance (currentBalance).
json
{
"balances": [
{
"walletId": 826210,
"currentBalance": 50, // Actual Balance, as credited in the previous step
"authorizations": 0, // Currently pending authorizations
"authorizedBalance": 50, // Balance, minus pending authorizations
"currency": "EUR", // Currency of the balance
"calculationDate": "2024-02-01 15:52:40" // When the Balance was last actualized
}
]
}Tip – Balance History is available
The dedicated Balance History endpoint gives the Balance evolution over time.
Create a Beneficiary
To send money to bank accounts outside your Treezor environment, you must create a Beneficiary beforehand.
bash
curl -X POST {baseUrl}/v1/beneficiaries \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is an example of {payload}:
json
{
"userId":123456, // required, user ID allowed to use the beneficiary
"name":"Chris Oak", // Name of the Beneficiary
"tag":"oak-1982", // Custom field you're free to populate
"nickName":"C. Oak checking", // Alias of the Beneficiary
"address":"Woods Bank",
"iban":"FR7616798000010000012345678", // required, IBAN of the Beneficiary
"bic":"TRZOFR21XXX", // required, BIC of the Beneficiary
"usableForSct":true // required, if the Beneficiary can be used for SCT
}Returns the Beneficiary object, with its id allowing you to send funds to it using a Payout.
json
{
"id": 11XXXX8,
"tag": "oak-1982",
"userId": 22XXXX6,
"nickName": "C. Oak checking",
"name": "Chris Oak",
"address": "Woods Bank",
"iban": "2XXXXXXXX X X 7XXXXXXXXX5 X X 75XXXXXXXX6 X X 1XXXXX4",
"bic": "BNPAFRPP",
"sepaCreditorIdentifier": "",
"sddB2bWhitelist": [],
"sddCoreBlacklist": [],
"usableForSct": true,
"sddCoreKnownUniqueMandateReference": [],
"isActive": true
}Send funds to an external account
This sends funds from the created Wallet, to the created Beneficiary using a SEPA transfer.
bash
curl -X POST {baseUrl}/v1/payouts \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is an example of {payload} with an amount ending in 1.25 for the simulation:
json
{
"walletId":826210, // required, the wallet to debit
"beneficiaryId":{beneficiaryId}, // required, id of the beneficiary created in the previous step
"amount":11.25, // required, must end with 1.25
"currency":"EUR" // required
}Returns a Payout object with its id.
json
{
"payoutId": <integer>,
"payoutTag": "<string>",
"payoutStatus": "<string>",
"payoutTypeId": <integer>,
"payoutType": "<string>",
"walletId": <integer>,
"payoutDate": "<string>",
"walletEventName": "<string>",
"userId": <integer>,
"bankaccountId": <integer>,
"beneficiaryId": <integer>,
"amount": "<string>",
"currency": "<string>"
// [...] some attributes are hidden
}Tip – SEPA Direct Debit also available
You could also use Direct Debit to debit funds from the Wallet to an external account.
Send funds to another Wallet
You can also transfer funds from one Wallet to another in your Treezor environment.
bash
curl -X POST {baseUrl}/v1/transfers \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
-d '{payload}'Here is a {payload} example:
json
{
"walletId":826210, // required, source wallet for the transfer
"beneficiaryWalletId":123456, // required, destination wallet for the transfer
"amount":21.25, // required
"currency":"EUR" // required
}Returns a Transfer object.
json
{
"transfers": [
{
"transferId": 4269222,
"transferStatus": "VALIDATED",
"transferTag": "",
"walletId": 826210,
"walletTypeId": 10,
"beneficiaryWalletId": 2301937,
"beneficiaryWalletTypeId": 10,
"transferDate": "0000-00-00",
"walletEventName": "Account A",
"walletAlias": "account-63346a643a7fa",
"beneficiaryWalletEventName": "Main account",
"beneficiaryWalletAlias": "main-account-64ad18c128f29",
"amount": "21.25",
"currency": "EUR",
"label": "",
"transferTypeId": 1,
"createdDate": "2024-02-07 14:17:51",
"modifiedDate": "2024-02-07 14:17:51",
"totalRows": null,
"foreignId": null,
"partnerFee": null,
"codeStatus": "150005",
"informationStatus": null,
"metadata": null
}
]
}You can now recheck the balance of the Wallet.
Create a Card to make payments
If you already have a cardPrint provided once your Card Program is set up, you can test the creation of Virtual Card and/or Physical Cards.
Let's take the example of the Virtual Card creation.
bash
curl -X POST {baseUrl}/v1/cards/CreateVirtual \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content: application/json' \
-d '{
"userId":1545392, // required, card owner
"walletId":826210, // required, wallet to which the card will be associated
"permsGroup":"TRZ-CU-016", // required, defines a set of permissions for the card
"cardPrint":"{cardPrint}" // required, as a string, defines your card program and card design
}'Here is an example of {payload}:
json
{
"userId":1545392, // required, card owner
"walletId":826210, // required, wallet to which the card will be associated
"permsGroup":"TRZ-CU-016", // required, defines a set of permissions for the card
"cardPrint":"{cardPrint}" // required, as a string, defines your card program and card design
}Returns a Card object with its id, expiration date, CVV, etc.
json
{
"cardId": "10xxxx4",
"userId": "22xxxx7",
"walletId": "2xxxxx1",
"walletCardtransactionId": "2xxxxx1",
"expiryDate": "2023-06-30",
"CVV": "757",
"physical": "0"
// [...] some attributes are hidden
}Note – A lot of options come with your Card Product
You can set withdrawals and payments limits, options for payments, restrictions based on countries, business categories, and merchants. You can also digitize cards with Apple Pay, Google Pay and Samsung Pay.
Simulate a Card Transaction
Now that you've created a Virtual Card, you may simulate a Card Transaction.
bash
curl -X POST {baseUrl}/simulation/cardtransactions \
--header 'Authorization: Bearer {accessToken}' \
--header 'Content-Type: application/json' \
--data-raw '{payload}'Here is a {payload} example:
json
{
"publicToken": "103020378",
"date": "2022-02-12 13:00:00",
"amount": 15.90,
"mcc": "8574",
"merchantId": "3256",
"merchantName": "Merchant Name",
"paymentStatus": "A",
"paymentCode": "100000000000004"
}The request returns a 201 HTTP Status Code without any content.
Note – Disclaimers about this emulation
- No impact on Wallet Balances: A
balance.updatewebhook is sent, but values are set to0. - No refunds and negative amount settlements support yet.