# How to integrate with BC API as corporation

#### <span style="color: #1c1e3f;">Onboarding</span>

<span style="color: #1c1e3f;">Essential steps before calling BC API: </span>

<span style="color: #1c1e3f;">1. This API requires Mutual TLS authentication. You can use the same certificate for all mTLS-secured APIs exposed by Verestro. If you don't have one, follow this instruction: [Connecting to server-to-server APIs](https://bookstack.verestro.dev/books/connecting-to-our-services/page/connecting-to-server-to-server-apis).</span>

<span style="color: #1c1e3f;">2. You should receive your corporationId, balanceId and certificate from Sparados. Optionally you can also receive personalized visuals and their Ids for your cards.</span>

<span style="color: #1c1e3f;">3. Now you can assign cards for your corporation members. Remember to save approvalId on your side because it will be needed in case of editing it.</span>

#### <span style="color: #1c1e3f;">Values used in BC API</span>

<span style="color: #1c1e3f;">**Date format**</span>

<span style="color: #1c1e3f;">We use ISO 8601 standard: year-month-day-T-hour-minute-second-Z.</span>

<span style="color: #1c1e3f;">where T is constant separating the date from the time and Z is Zulu time (Greenwich Mean Time (GMT)).</span>

<span style="color: #1c1e3f;">Example: 2023-05-22T10:00:01.953Z</span>

<span style="color: #1c1e3f;">**Minor values** </span>

<span style="color: #1c1e3f;">All numeric values used in our API are in minor. If you want to e.g. assign card with limit 100.50 EUR you have to send us 100500. Currency is not needed - it's always the same as currency of account/balance.</span>

<span style="color: #1c1e3f;">**Currency**</span>

<span style="color: #1c1e3f;">Card/approval is always created in the currency of account. Account can have only one currency although it is possible to make transactions in other currencies.</span>

<span style="color: #1c1e3f;">**ID**</span>

<span style="color: #1c1e3f;">We always use UUID format for IDs in our project.</span>

#### <span style="color: #1c1e3f;">How to assign a card? </span>

<span style="color: #1c1e3f;">You should use **POST /secure/approvals** and provide data below. Required fields are signed with \*.</span>

<table border="1" id="bkmrk-rules.budgetminor%C2%A0-%C2%A0" style="border-collapse: collapse; width: 100%; height: 484.344px;"><tbody><tr style="height: 46.5938px;"><td style="width: 35.8643%; height: 46.5938px;"><span style="color: #1c1e3f;">**rules.budgetMinor \***</span></td><td style="width: 64.2593%; height: 46.5938px;"><span style="color: #1c1e3f;">Amount in minor that user can spend using a card provided in the currency of account/balance.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">**rules.validityPeriod \***</span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">Validity of a card in UTC format.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">**rules.timezone \***</span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;"> BC API will adjust startDate and EndDate to exact time in provided timezone.</span></td></tr><tr style="height: 46.5938px;"><td style="width: 35.8643%; height: 46.5938px;"><span style="color: #1c1e3f;">limits.amountMinor </span></td><td style="width: 64.2593%; height: 46.5938px;"><span style="color: #1c1e3f;">Additional periodic limit value in minor provided in the currency of account/balance.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">limits.timeUnit </span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">Available values: daily, weekly, monthly.</span></td></tr><tr style="height: 46.5938px;"><td style="width: 35.8643%; height: 46.5938px;"><span style="color: #1c1e3f;">limits.type</span></td><td style="width: 64.2593%; height: 46.5938px;"><span style="color: #1c1e3f;">Available values: general, ecommerce, atm, foreign\_amount. Types are descibed below the table.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">**purpose.ecommerce \***</span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">Now it should be always as true. </span></td></tr><tr style="height: 46.5938px;"><td style="width: 35.8643%; height: 46.5938px;"><span style="color: #1c1e3f;">**purpose.allowChangeRequest \***</span></td><td style="width: 64.2593%; height: 46.5938px;"><span style="color: #1c1e3f;">True - user can send a request to change limits on card.</span>  
<span style="color: #1c1e3f;">False - user can't send a request to change limits on card.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">**user.email \***</span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">E-mail on which will be sent information about assigned card.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">**user.prefix \***</span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">Prefix of a phone number of a user that can be used for authorization purpose.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">**user.phone \***</span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">Phone number of a user that can be used for authorization purpose.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">**balance.Id \***</span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">Id of a balance created for you corporation.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">card.description</span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">Description displayed on a card visual in user app.</span></td></tr><tr style="height: 29.7969px;"><td style="width: 35.8643%; height: 29.7969px;"><span style="color: #1c1e3f;">card.visual.Id </span></td><td style="width: 64.2593%; height: 29.7969px;"><span style="color: #1c1e3f;">Id of visual provided by Sparados. Null - default Sparados visual.</span></td></tr></tbody></table>

<span style="color: #1c1e3f;">**Additional limits**</span>

<span style="color: #1c1e3f;">It's possible to set additional limits on a card. If they are left null our card issuing service sets a default value that is high enough to not be easily spent (legal need).</span>

<span style="color: #1c1e3f;">There are four types of additional limits:</span>

<span style="color: #1c1e3f;">1. **General limit** - periodic limit on all kinds of transactions. This value should be greater than remaining additional limits because it affects them. E.g. if the ATM limit is set to 100 EUR and the general limit is set to 50 EUR, the end user will be able to withdraw only 50 EUR from the ATM. <span style="text-decoration: underline;">Possible values:</span> amount in minor or null.</span>

<span style="color: #1c1e3f;">2. **Online payment limit** - periodic limit on e-commerce payments. <span style="text-decoration: underline;">Possible values</span>: 0, amount in minor or null.</span>

<span style="color: #1c1e3f;">3. **ATM limit** - periodic limit on ATM withdrawals. <span style="text-decoration: underline;">Possible values</span>: 0, amount in minor or null.</span>

<span style="color: #1c1e3f;">4. **Foreign transaction limit** - periodic limit on transactions in a different currency from account currency. Limit is given in the currency of balance and it will be recalculated taking into account exchange rates and commission. <span style="text-decoration: underline;">Possible values</span>: 0, amount in minor or null.</span>

<span style="color: #1c1e3f;">**Possible time units for all additional limits:**</span>

- <span style="color: #1c1e3f;">daily,</span>
- <span style="color: #1c1e3f;">weekly,</span>
- <span style="color: #1c1e3f;">monthly.</span>

<span style="color: #1c1e3f;">**Possible values:**</span>

<span style="color: #1c1e3f;">0 - disabled. End user won't be able to perform online payments, withdraw from ATM or transactions in foreign currencies.</span>

<span style="color: #1c1e3f;">Value in minor - limited to requested value.</span>

<span style="color: #1c1e3f;">Null - unlimited. End user will be able to perform online payments, withdraw from ATM or transactions in foreign currencies.</span>

#### <span style="color: #1c1e3f;">What is the difference between approval and reapproval?</span>

<span data-preserver-spaces="true" style="color: #1c1e3f;">**Approval** is created by the corporation in the process of assigning a card. We don't name it simply a card because a card is generated when the end-user redeems a card and the start date of approval occurs. Approval is created earlier, right after calling endpoint **PUT /secure/approvals/**.</span>

<span style="color: #1c1e3f;">**Reapproval** can be created by the corporation while editing data on approval (using method **PUT /secure/approvals/{id}**) in status Delivered or by mobile user when they request a higher limit or change of validity end date. Requesting changes can be disabled by putting the value false in purpose.allowChangeRequest field while creating an approval.</span>

#### <span style="color: #1c1e3f;">What actions can I perform on approval?</span>

<span style="color: #1c1e3f;">When reapproval is accepted it changes its status to Delivered and replaces previous approval. It's essential to save its ID because from the moment of acceptance it's valid Id of this approval. Status of original Approval changes to Reapproved.</span>

<span style="color: #1c1e3f;">If user requests changes and corporation decide to edit original approval, reapproval of user will be cancelled.</span>

<span style="color: #1c1e3f;">Until reapproval is accepted, the terms of an original approval apply.</span>

<span style="color: #1c1e3f;">Statuses of approvals:</span>

<table id="bkmrk-status-description-c" style="width: 87.5309%; height: 577.781px;"><tbody><tr style="height: 57.75px;"><td style="width: 15.5148%; height: 57.75px;" width="110"><span style="color: #1c1e3f;">CREATED</span>

</td><td style="width: 84.3441%; height: 57.75px;" width="598"><span style="color: #1c1e3f;">Occur only when mobile user request changes on reapproval.</span>

</td></tr><tr style="height: 80.1719px;"><td style="width: 15.5148%; height: 80.1719px;" width="110"><span style="color: #1c1e3f;">ACCEPTED</span>

</td><td style="width: 84.3441%; height: 80.1719px;" width="598"><span style="color: #1c1e3f;">When an Approval is created. **It changes to DELIVERED status after registration is complete and card is redeemed by end-user.**</span>

</td></tr><tr style="height: 57.7812px;"><td style="width: 15.5148%; height: 57.7812px;" width="110"><span style="color: #1c1e3f;">CANCELED</span>

</td><td style="width: 84.3441%; height: 57.7812px;" width="598"><span style="color: #1c1e3f;">When an Approval or Reapproval with status CREATED, ACCEPTED or PREPARED is cancelled by corporation.</span>

</td></tr><tr style="height: 35.3906px;"><td style="width: 15.5148%; height: 35.3906px;" width="110"><span style="color: #1c1e3f;">REJECTED</span>

</td><td style="width: 84.3441%; height: 35.3906px;" width="598"><span style="color: #1c1e3f;">When a Reapproval with status CREATED is rejected by corporation.</span>

</td></tr><tr style="height: 80.1719px;"><td style="width: 15.5148%; height: 80.1719px;" width="110"><span style="color: #1c1e3f;">EXPIRED</span>

</td><td style="width: 84.3441%; height: 80.1719px;" width="598"><span style="color: #1c1e3f;">When a Reapproval with the status CREATED is not accepted/rejected or status of Approval is ACCEPTED but the card has not been redeemed by mobile user within the given Approval time (until the end of the ValidTo date).</span>

</td></tr><tr style="height: 57.7812px;"><td style="width: 15.5148%; height: 57.7812px;" width="110"><span style="color: #1c1e3f;">PREPARED</span>

</td><td style="width: 84.3441%; height: 57.7812px;" width="598"><span style="color: #1c1e3f;">When approval has been ACCEPTED, redeemed by the end-user and is waiting for card generation. Card is generated on startDate of Approval.</span>

</td></tr><tr style="height: 57.7812px;"><td style="width: 15.5148%; height: 57.7812px;" width="110"><span style="color: #1c1e3f;">DELIVERED</span>

</td><td style="width: 84.3441%; height: 57.7812px;" width="598"><span style="color: #1c1e3f;">When mobile user redeemed card. This is the state of approval in which transactions can be made with a card.</span>

</td></tr><tr style="height: 35.3906px;"><td style="width: 15.5148%; height: 35.3906px;" width="110"><span style="color: #1c1e3f;">FINISHED</span>

</td><td style="width: 84.3441%; height: 35.3906px;" width="598"><span style="color: #1c1e3f;">When an Approval with status DELIVERED exceeds the end date of assignment.</span>

</td></tr><tr style="height: 35.3906px;"><td style="width: 15.5148%; height: 35.3906px;" width="110"><span style="color: #1c1e3f;">REAPPROVED</span>

</td><td style="width: 84.3441%; height: 35.3906px;" width="598"><span style="color: #1c1e3f;">When a reapproval is created for a given Approval that is in Accepted/Delivered status.</span>

</td></tr><tr style="height: 80.1719px;"><td style="width: 15.5148%; height: 80.1719px;"><span style="color: #1c1e3f;">LOCKED</span>

</td><td style="width: 84.3441%; height: 80.1719px;"><span style="color: #1c1e3f;">This is a status of a **card (not an approval)** but we display it on the diagram below to show that Delivered is the only state of a approval on which we have action to lock and unlock card. </span>

</td></tr></tbody></table>

####   


<span style="color: #1c1e3f;">Statuses of an Approval:</span>

<span style="color: #1c1e3f;"> </span>

<span style="color: #1c1e3f;">[![image-1686858492185.png](https://bookstack.verestro.dev/uploads/images/gallery/2023-06/scaled-1680-/image-1686858492185.png)](https://bookstack.verestro.dev/uploads/images/gallery/2023-06/image-1686858492185.png)</span>

<span style="color: #1c1e3f;">Statuses of a Reapproval:</span>

<span style="color: #1c1e3f;">[![image-1686858497780.png](https://bookstack.verestro.dev/uploads/images/gallery/2023-06/scaled-1680-/image-1686858497780.png)](https://bookstack.verestro.dev/uploads/images/gallery/2023-06/image-1686858497780.png)</span>

<span style="color: #1c1e3f;">Actions available on approvals:</span>

- <span style="color: #1c1e3f;">Created: Accept, Reject, Edit, Cancel. </span>
- <span style="color: #1c1e3f;">Accepted: Cancel.</span>
- <span style="color: #1c1e3f;">Preprared: Cancel.</span>
- <span style="color: #1c1e3f;">Delivered: Lock, Unassign, Edit.</span>
- <span style="color: #1c1e3f;">Locked: Unlock.</span>
- <span style="color: #1c1e3f;">Rejected: —</span>
- <span style="color: #1c1e3f;">Expired: — </span>
- <span style="color: #1c1e3f;">Finished: — </span>

####   


#### <span style="color: #1c1e3f;">How to take away card from end-user?</span>

<span style="color: #1c1e3f;">If user already redeem card (status of approval is Delivered) use **PUT /secure/approvals/{id}/unassign** method. </span>

<span style="color: #1c1e3f;">If user hasn't redeem card (status of approval is Accepted or Prepared) use **PUT /secure/approvals/{id}/cancel** method.</span>

#### <span style="color: #1c1e3f;">How to quickly increase or decrease available limit on a card?</span>

<span style="color: #1c1e3f;">You should use **PUT /secure/approvals/{id}/increase\_budget** method.  
</span>

<span style="color: #1c1e3f;">To add another 10 EUR put the value: </span>

```json
"additionalBudgetMinor": 1000
```

<span style="color: #1c1e3f;">To substract 10 EUR put the value:</span>

```json
"additionalBudgetMinor": -1000
```

#### <span style="color: #1c1e3f;">Where can I see the transactions made by the issued cards?</span>

<span style="color: #1c1e3f;">Currently the only available way to see transactions is to login to Corporate Panel and go to Transaction history section.</span>

#### <span style="color: #1c1e3f;">What e-mails are sent to the end user?</span>

<span style="color: #1c1e3f;">E-mails can be adjusted to your corporation and sent in different language. Contact Sparados for details.</span>

<table class="confluenceTable" id="bkmrk-email-name-sending-r" style="width: 100%; height: 288.766px;"><tbody><tr style="height: 35.4px;"><td bgcolor="#1C1E3F" style="width: 40.4067%; height: 35.4px;" width="353"><span style="color: #ecf0f1;">**Email name**</span>

</td><td bgcolor="#1C1E3F" style="width: 59.5685%; height: 35.4px;" width="353"><span style="color: #ecf0f1;">**Sending reason**</span></td></tr><tr style="height: 46.5938px;"><td class="confluenceTd mceSelected" style="width: 40.4067%; height: 46.5938px;"><span style="color: #1c1e3f;">**BC\_USER\_PENDING\_TERMS\_AND\_CONDITIONS**</span></td><td class="confluenceTd mceSelected" style="width: 59.5685%; height: 46.5938px;"><span style="color: #1c1e3f;">Sent while new terms and conditions are applied to the issuer to end users.</span></td></tr><tr style="height: 29.7969px;"><td class="confluenceTd mceSelected" style="width: 40.4067%; height: 29.7969px;"><span style="color: #1c1e3f;">**BC\_USER\_CARD\_EXPIRING**</span></td><td class="confluenceTd mceSelected" style="width: 59.5685%; height: 29.7969px;"><span style="color: #1c1e3f;">Sent 1 day before card expiration to end user.</span></td></tr><tr style="height: 29.7969px;"><td class="confluenceTd mceSelected" style="width: 40.4067%; height: 29.7969px;"><span style="color: #1c1e3f;">**BC\_USER\_PENDING\_CARD**</span></td><td class="confluenceTd mceSelected" style="width: 59.5685%; height: 29.7969px;"><span style="color: #1c1e3f;">Sent to end user when new card was assigned and is waiting for redemption.</span></td></tr><tr style="height: 29.7969px;"><td class="confluenceTd mceSelected" style="width: 40.4067%; height: 29.7969px;"><span style="color: #1c1e3f;">**BC\_USER\_NEW\_CARD**</span></td><td class="confluenceTd mceSelected" style="width: 59.5685%; height: 29.7969px;"><span style="color: #1c1e3f;">Sent to end user when new card was redeemed.</span></td></tr><tr style="height: 29.7969px;"><td class="confluenceTd mceSelected" style="width: 40.4067%; height: 29.7969px;"><span style="color: #1c1e3f;">**BC\_USER\_CARD\_EXPIRED**</span></td><td class="confluenceTd mceSelected" style="width: 59.5685%; height: 29.7969px;"><span style="color: #1c1e3f;">Sent to end user when approval is finished.</span></td></tr><tr style="height: 46.5938px;"><td class="confluenceTd mceSelected" style="width: 40.4067%; height: 46.5938px;"><span style="color: #1c1e3f;">**BC\_USER\_CARD\_DELETED**</span></td><td class="confluenceTd mceSelected" style="width: 59.5685%; height: 46.5938px;"><span style="color: #1c1e3f;">Sent to end user while card/approval was uassigned or deleted by corporation.</span></td></tr><tr style="height: 46.5938px;"><td class="confluenceTd mceSelected" style="width: 40.4067%; height: 46.5938px;"><span style="color: #1c1e3f;">**BC\_USER\_CARD\_LOCKED**</span></td><td class="confluenceTd mceSelected" style="width: 59.5685%; height: 46.5938px;"><span style="color: #1c1e3f;">Sent to end user when card was locked by corporation.</span></td></tr></tbody></table>

@swagger="[https://q4b-bc-api.upaidtest.pl/api-secure.yaml](https://q4b-bc-api.upaidtest.pl/api-secure.yaml)"