Payments

Payments

For (periodical) buy-Orders to be processed, the investor needs to have enough Cash in their InvestorAccount. This Cash is then reserved for the appropriate order.

The GiroProvider receives payments from investors on its OmnibusBankAccount. These payments are allocated to the corresponding InvestorAccount on the CashLedger the next day in accordance with the daily CAMTFile.

Because payment providers have their own infrastructure, the GiroPro API doesn’t have any endpoints that handle payments directly. It does, however, offer an endpoint for configuring direct-debit payments.

DirectDebit

Direct debit authorizes the GiroProvider to charge the investor’s bankAccount. This is set up to only work for periodical buy-Orders where each order gets its own DirectDebitContractItem. This item contains the parameters of the authorization. For each DirectDebitContractItem GiroPro attempts to collect the specified amount from the associated bankAccount. When successful the associated Order is executed. GiroPro offers multiple endpoints regarding direct-debit for periodical buy-Orders. These endpoints manage DirectDebitContractItems.

DirectDebitContractItem

GiroPro uses DirectDebitContractItems to keep track of all direct-debit authorizations. These contracts contain all relevant information regarding the buy-Order, BankAccount information and possible related Documents. A DirectDebitContractItem looks like this:

{
  "active": true, // whether or not this Contract is still used
  "labelId": "357a12a1-a12a-12ab-a123-a12a1a1ab357",
  "investorAccountId": "4563a12a1-a12a-12ab-a123-a12a1a1ab456",
  "bankAccountId": "321ba1a1a21a-321a-ba21-a21a-1a21a321",
  "productId": "e6084172-fffc-483f-86d2-0f73b3f3e6db",
  "assetId": "0b36a2f1-c487-4f84-a418-79b6441f329b", // id of asset to buy
  "instructedAmount": 100, // amount of asset to buy in EUR
  "mandateIdentification": "",
  "mandateDateOfSignature": "2025-05-13", // creation date
  "directDebitRecurrence": {
    "rRuleString": "RRULE:FREQ=MONTHLY;BYMONTHDAY=10", // discription of frequency 
    "startDate": "2025-05-13T07:43:53.024Z" // start date
  },
  "documents": [] // possible related documents
}

Creating a DirectDebitContractItem

GiroPro offers one endpoint for the creation of a DirectDebitContractItem.

POST /DirectDebitContractAdd

The /DirectDebitContractAdd endpoint creates and returns a new DirectDebitContractItem specified in the request body:

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/DirectDebitContractAdd';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json', 
    'content-type': 'application/json',
    authorization: 'bearer <token>'
  },
  body: JSON.stringify(<DirectDebitContractItem>)
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

This call would using the DirectDebitContractItem above would return a PengineResult containing the newly created DirectDebitContractItem:

{
  "success": true,
  "httpStatusCode": 201,
  "errors": [],
  "totalCount": 0,
  "items": [
    {
      "return_type": "DirectDebitContractAggregatedItem",
      "id": "9aa41ea2-0dde-42ab-a1c5-3628b1b1d5f5",
      "labelId": "357a12a1-a12a-12ab-a123-a12a1a1ab357",
  		"investorAccountId": "4563a12a1-a12a-12ab-a123-a12a1a1ab456",
  		"bankAccountId": "321ba1a1a21a-321a-ba21-a21a-1a21a321",
      "iban": "NL12ABCD0123456789",
      "bic": "ABCDNL1A",
      "accountOwnerName": "KlaasSpanjaard",
      "productId": "e6084172-fffc-483f-86d2-0f73b3f3e6db",
      "assetId": "0b36a2f1-c487-4f84-a418-79b6441f329b",
      "active": true,
      "instructedAmount": 100.0,
      "mandateIdentification": "",
      "mandateDateOfSignature": "2025-05-13",
      "directDebitRecurrence": {
        "rRuleString": "RRULE:FREQ=MONTHLY;BYMONTHDAY=10",
        "startDate": "2025-05-13T07:43:53.024Z",
        "nextDate": "2025-06-10T00:00:00Z"
      },
      "isFirst": false,
      "nextDirectDebitDate": "2025-06-10T00:00:00Z",
      "documents": []
    }
  ]
}

Retrieving DirectDebitContractItems

To retrieve the DirectDebitContractItems GiroPro offers two endpoints.

GET /DirectDebitContractGetById/

The /DirectDebitContractGetById/ endpoint returns a single DirectDebitContractItem for the provided labelId and directDebitContractId.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/DirectDebitContractGetById/<labelId>/<directDebitContractId>';
const options = {
  method: 'GET', 
  headers: {
    accept: 'application/json',
    authorization: 'bearer <token>'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Calling this endpoint returns a PengineResult containing a single DirectDebitContractItem.

GET /DirectDebitContracts/

The /DirectDebitContracts/ endpoint returns all DirectDebitContractItems that match the provided query parameters:

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/DirectDebitContracts/<labelId>?skip=0&limit=5&query[0].column=investorAccountId&query[0].value=<investorAccountId>&query[0].comparisonType=exact';
const options = {
  method: 'GET', 
  headers: {
    accept: 'application/json',
    authorization: 'bearer <token>'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

This call returns a PengineResult containing a maximum of 5 DirectDebitContractItems that match the provided query.

When to use

The /DirectDebitContractGetById/ endpoint is best used before making changes to a specific DirectDebitContractItem.

The /DirectDebitContracts/ endpoint is used to retrieve all DirectDebitContracts for a specific User, Investor or InvestorAccount.

Changing DirectDebitContractItems

When we make changes to a periodical buy-Order we should also update the associated DirectDebitContractItem. GiroPro offers one endpoint for this.

PUT /DirectDebitContractUpdate

The /DirectDebitContractUpdate endpoint allows for changes to be made on an existing DirectDebitContractItem. It is highly recommended to first retrieve the DirectDebitContractItem through the /DirectDebitContractGetById/ endpoint and then make the desired changes to this item before making the call with the modified DirectDebitContractItem.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/DirectDebitContractUpdate';
const options = {
  method: 'PUT',
  headers: {
    accept: 'application/json', 
    'content-type': 'application/json',
  	authorization: 'bearer <token>'
  },
  body: <DirectDebitContractItem>
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

When to use

We use the /DirectDebitContractUpdate endpoint when we want to make changes to a periodical buy-Order. This includes deletion of this order. In the case of deletion we do a call with the relevant DirectDebitContractItem where the active property is set to false.

---

PeriodicalSellContracts

Much like how the periodical buy-Order uses DirectDebitContracts, the periodical sell-Order uses PeriodicalSellContracts.

PeriodicalSellContractItem

GiroPro uses PeriodicalSellContractItems to keep track of the periodical sell-Orders. These contracts contain all relevant information regarding the sell-Order, BankAccount information and possible related Documents. A PeriodicalSellContractItem looks like this:

{
  "id": "725dabf2-ad95-4084-92e6-24e1935bfc2b", // ID of the PeriodicalSellContractItem
  "labelId": "357a12a1-a12a-12ab-a123-a12a1a1ab357",
  "investorAccountId": "4563a12a1-a12a-12ab-a123-a12a1a1ab456",
  "assetId": "0b36a2f1-c487-4f84-a418-79b6441f329b", // ID of to-sell asset
  "orderType": "Sell", // orderType (should be, and defaults to, Sell)
  "active": true, // when false the order is no longer being processed
  "amount": 1, // net amount of EUR sold each period
  "periodicalSellRecurrence": {
    "rRuleString": "RRULE:FREQ=MONTHLY;UNTIL=20270209T000000Z", // rule determining the frequency at which the sale is executed
    "startDate": "2025-12-21",
    "nextDate": "2025-12-21"
  },
  "documents": [], // related documents
  "documentsTotalCount": 0, // number of related documents
  "deletedDocumentIds": [], // IDs of deleted related documents
  "asset": {}, // the asset that is being sold (only when returned)
  "investorAccount": {}, // only when returned
  "investmentAccount": {}, // only when returned
}

Creating a PeriodicalSellContractItem

GiroPro offers one endpoint for the creation of a PeriodicalSellContractItem.

POST /PeriodicalSellContractAdd

The /PeriodicalSellContractAdd endpoint creates and returns a new PeriodicalSellContractItem specified in the request body:

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/PeriodicalSellContractAdd';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json', 
    'content-type': 'application/json',
    authorization: 'bearer <token>'
  },
  body: JSON.stringify(<PeriodicalSellContractItem>)
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

This call would using the PeriodicalSellContractItem above would return a PengineResult containing the newly created PeriodicalSellContractItem.

Retrieving PeriodicalSellContractItems

To retrieve the DirectDebitContractItems GiroPro offers two endpoints.

GET /PeriodicalSellContractGetById/

The /PeriodicalSellContractGetById/ endpoint returns a single PeriodicalSellContractItem for the provided labelId and PeriodicalSellContractId.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/PeriodicalSellContractGetById/<labelId>/<periodicalSellContractId>';
const options = {
  method: 'GET', 
  headers: {
    accept: 'application/json',
    authorization: 'bearer <token>'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Calling this endpoint returns a PengineResult containing a single PeriodicalSellContractItem.

GET /PeriodicalSellContracts/

The /PeriodicalSellContracts/ endpoint returns all PeriodicalSellContractItems that match the provided query parameters:

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/PeriodicalSellContracts/<labelId>?skip=0&limit=5&query[0].column=investorAccountId&query[0].value=<investorAccountId>&query[0].comparisonType=exact';
const options = {
  method: 'GET', 
  headers: {
    accept: 'application/json',
    authorization: 'bearer <token>'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

This call returns a PengineResult containing a maximum of 5 PeriodicalSellContractItems that match the provided query.

When to use

The /PeriodicalSellContractGetById/ endpoint is best used before making changes to a specific PeriodicalSellContractItem.

The /PeriodicalSellContracts/ endpoint is used to retrieve all PeriodicalSellContracts for a specific User, Investor or InvestorAccount.

Changing PeriodicalSellContractItems

When we make changes to a periodical sell-Order we should also update the associated PeriodicalSellContractItem. GiroPro offers one endpoint for this.

PUT /PeriodicalSellContractUpdate

The /PeriodicalSellContractUpdate endpoint allows for changes to be made on an existing PeriodicalSellContractItem. It is highly recommended to first retrieve the PeriodicalSellContractItem through the /PeriodicalSellContractGetById/ endpoint and then make the desired changes to this item before making the call with the modified PeriodicalSellContractItem.

const url = 'https://api.dev.giropro.pengine.com/PENGINE/Aggregator/SubjectAggregator/PeriodicalSellContractUpdate';
const options = {
  method: 'PUT',
  headers: {
    accept: 'application/json', 
    'content-type': 'application/json',
  	authorization: 'bearer <token>'
  },
  body: <PeriodicalSellContractItem>
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

When to use

We use the /PeriodicalSellContractUpdate endpoint when we want to make changes to a periodical sell-Order. This includes deletion of this order. In the case of deletion we do a call with the relevant PeriodicalSellContractItem where the active property is set to false.