How to integrate with BC API as corporation

Onboarding

Essential steps before calling BC API:

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.

2. You should receive your corporationId, balanceId and certificate from Sparados. Optionally you can also receive personalized visuals and their Ids for your cards.

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.

Values used in BC API

Date format

We use ISO 8601 standard: year-month-day-T-hour-minute-second-Z.

where T is constant separating the date from the time and Z is Zulu time (Greenwich Mean Time (GMT)).

Example: 2023-05-22T10:00:01.953Z

Minor values

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.

Currency

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.

We always use UUID format for IDs in our project.

How to assign a card?

You should use POST /secure/approvals and provide data below. Required fields are signed with *.

rules.budgetMinor *	Amount in minor that user can spend using a card provided in the currency of account/balance.
rules.validityPeriod *	Validity of a card in UTC format.
rules.timezone *	BC API will adjust startDate and EndDate to exact time in provided timezone.
limits.amountMinor	Additional periodic limit value in minor provided in the currency of account/balance.
limits.timeUnit	Available values: daily, weekly, monthly.
limits.type	Available values: general, ecommerce, atm, foreign_amount. Types are descibed below the table.
purpose.ecommerce *	Now it should be always as true.
purpose.allowChangeRequest *	True - user can send a request to change limits on card. False - user can't send a request to change limits on card.
user.email *	E-mail on which will be sent information about assigned card.
user.prefix *	Prefix of a phone number of a user that can be used for authorization purpose.
user.phone *	Phone number of a user that can be used for authorization purpose.
balance.Id *	Id of a balance created for you corporation.
card.description	Description displayed on a card visual in user app.
card.visual.Id	Id of visual provided by Sparados. Null - default Sparados visual.

Additional limits

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).

There are four types of additional limits:

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. Possible values: amount in minor or null.

2. Online payment limit - periodic limit on e-commerce payments. Possible values: 0, amount in minor or null.

3. ATM limit - periodic limit on ATM withdrawals. Possible values: 0, amount in minor or null.

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. Possible values: 0, amount in minor or null.

Possible time units for all additional limits:

daily,
weekly,
monthly.

Possible values:

0 - disabled. End user won't be able to perform online payments, withdraw from ATM or transactions in foreign currencies.

Value in minor - limited to requested value.

Null - unlimited. End user will be able to perform online payments, withdraw from ATM or transactions in foreign currencies.

What is the difference between approval and reapproval?

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/.

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.

What actions can I perform on approval?

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.

If user requests changes and corporation decide to edit original approval, reapproval of user will be cancelled.

Until reapproval is accepted, the terms of an original approval apply.

Statuses of approvals:

CREATED	Occur only when mobile user request changes on reapproval.
ACCEPTED	When an Approval is created. It changes to DELIVERED status after registration is complete and card is redeemed by end-user.
CANCELED	When an Approval or Reapproval with status CREATED, ACCEPTED or PREPARED is cancelled by corporation.
REJECTED	When a Reapproval with status CREATED is rejected by corporation.
EXPIRED	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).
PREPARED	When approval has been ACCEPTED, redeemed by the end-user and is waiting for card generation. Card is generated on startDate of Approval.
DELIVERED	When mobile user redeemed card. This is the state of approval in which transactions can be made with a card.
FINISHED	When an Approval with status DELIVERED exceeds the end date of assignment.
REAPPROVED	When a reapproval is created for a given Approval that is in Accepted/Delivered status.
LOCKED	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.

Statuses of an Approval:

Statuses of a Reapproval:

Actions available on approvals:

Created: Accept, Reject, Edit, Cancel.
Accepted: Cancel.
Preprared: Cancel.
Delivered: Lock, Unassign, Edit.
Locked: Unlock.
Rejected: —
Expired: —
Finished: —

How to take away card from end-user?

If user already redeem card (status of approval is Delivered) use PUT /secure/approvals/{id}/unassign method.

If user hasn't redeem card (status of approval is Accepted or Prepared) use PUT /secure/approvals/{id}/cancel method.

How to quickly increase or decrease available limit on a card?

You should use PUT /secure/approvals/{id}/increase_budget method.

To add another 10 EUR put the value:

"additionalBudgetMinor": 1000

To substract 10 EUR put the value:

"additionalBudgetMinor": -1000

Where can I see the transactions made by the issued cards?

Currently the only available way to see transactions is to login to Corporate Panel and go to Transaction history section.

What e-mails are sent to the end user?

E-mails can be adjusted to your corporation and sent in different language. Contact Sparados for details.

Email name	Sending reason
BC_USER_PENDING_TERMS_AND_CONDITIONS	Sent while new terms and conditions are applied to the issuer to end users.
BC_USER_CARD_EXPIRING	Sent 1 day before card expiration to end user.
BC_USER_PENDING_CARD	Sent to end user when new card was assigned and is waiting for redemption.
BC_USER_NEW_CARD	Sent to end user when new card was redeemed.
BC_USER_CARD_EXPIRED	Sent to end user when approval is finished.
BC_USER_CARD_DELETED	Sent to end user while card/approval was uassigned or deleted by corporation.
BC_USER_CARD_LOCKED	Sent to end user when card was locked by corporation.

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