Round up

In this section, you will learn how to manage a round-up donation and round-up sources, the source of transactions to round up (e.g. credit/debit card, bank account). This documentation is divided into three parts: an example UI flow with the most important calls, a detailed flowchart, and the API references.

UI Example

The user starts by selecting a charity and the amount they wish to donate.

Step-by-Step Process:

1. Initiate Pre-Subscription:
   A front-end call is made without user authentication to initiate a pre-subscription for the selected charity and amount with type 'round_up'.
   Endpoint: POST /v1/pub/company/:company_id/pre-subscriptions

   

2. Retrieve Payment Methods:
   A front-end call is made with consumer user authentication to retrieve the payment methods already created in cents.
   Endpoint: GET /v1/auth/consumer-user/company/:id_company/payment-methods

3. Display Payment Methods:
   The system displays the list of available payment methods to the user (including also payment methods not stored in cents yet).

   

4. Add New Payment Method:
   If the consumer user selects a payment method not yet stored in cents, a front-end consumer user authenticated call is made to add the payment method.
   Endpoint: POST /v1/auth/consumer-user/company/:company_id/payment-methods

5. Select Round-Up Sources:

   • Check if Process is Instantiated from Specific Sources: Determine if the process is instantiated from specific sources.
     • If no, the list of available round-up sources is shown, so the consumer user can select one
     • If yes, this step is skipped
   • Retrieve Round-Up Sources: a front-end consumer user authenticated call is made to retrieve round-up sources. Endpoint: GET /v1/auth/consumer-user/company/:company_id/round-up-sources
   • Add New Round-Up Source: If the selected round-up source is not stored in Cents, a front-end consumer user authenticated call is made to add it. Endpoint: POST /v1/auth/consumer-user/company/:company_id/round-up-sources

6. Confirm the subscription: The consumer user has to confirm the subscription making a front-end consumer user authenticated call with type 'round_up'.
   Endpoint: POST /v1/auth/consumer-user/company/:company_id/subscriptions

7. Handle Donation Payment:
   There are two possible scenarios based on who will make the call to retrieve transactions to pay: the company or Cents.

   • Cents Handles the Call:
     If Cents handles the call, cents notify the company when there are new transactions, making a custom company call with transaction details.
   • Company Handles the Call:
     If the company handles the call, the company pings cents to retrieve transactions to do:
     Endpoint: GET /v1/auth/company/pre-transactions?to-pay=true, and then handle the donation payment.

8. Automatic Pre-Transactions:
   Cents automatically create pre-transactions every month.

9. Transaction Handling: There are two possible scenarios based on who will handle the donation payment: the company or Cents.

   • Cents Handles the Transaction:
     If Cents handles the transaction, they notify the company when there are new transactions, making a company call with transaction details.
   • Company Handles the Transaction:
     If the company handles the transaction, the company pings cents to retrieve transactions to do:
     Endpoint: GET /v1/auth/company/pre-transactions?to-pay=true, and then handle the donation payment.

10.Manage the Payment and Create the Transaction:
Finally, the company handles the donation payment, then a back-end call is made to create the transaction.
Endpoint: POST /v1/auth/company/consumer-users/:consumer_user_id/transactions

This flow ensures that the donation process is secure, with appropriate steps for user authentication and transaction handling, depending on whether the company or Cents handles the payment.

How to upload transactions of round-up sources?

To accurately compute the round-up donation amounts, it is imperative that companies submit the transactions from the designated round-up sources. This ensures that Cents possesses the most current and precise data necessary for calculating the round-up amounts.

To facilitate this, companies must utilize the endpoint POST /v1/auth/company/consumer-users/:consumer_user_id/round-up-sources/:round_up_source_id/transactions. This endpoint allows for the submission of multiple transaction entries in a single request, streamlining the process and ensuring efficiency.

Detailed Flow

API references

• Company API: for transactions section
• Consumer User API: for subscriptions, payment methods and round-up sources sections