DOCSEARCHbyAlgolia
Submit Docs

Cents Donations Documentation

website·Indexed 32 days ago

https://docs.centsdonations.com

Documentation for Cents, including the CentsJS Widget for donation integration and the Cents Payment Gateway API v1.0.0. Covers use cases for financial institutions and D2C companies, including round-up donations, recurring donations, and cause selection workflows.

Tokens
50.5K
Snippets
150
Records
286
Agent score
46%

What's inside Cents

  1. Overview of the CentsJS Widget for Payment Gateways

    The CentsJS Widget is a JavaScript library used to integrate charitable giving into payment flows. It manages the user interface and backend communications for collecting donations. Key operational details include:

    • Integration Speed: Can be integrated in less than one day with a few lines of JavaScript.
    • Donation Processing: Donations are only processed when an order is fulfilled.
    • Fulfillment Notification: The partner must notify Cents via a webhook when an order is fulfilled to trigger the donation splitting among causes.

  2. Overview of Cents Consumer User API functional groups

    The Cents Consumer User API (v1.0.0) is organized into five primary functional groups, all of which require authentication to protect user privacy and financial data:

    1. Info: Access personal details, contact information, and user preferences.
    2. Transactions: Manage and retrieve transaction history and create new transactions associated with a company.
    3. Subscriptions: View, create, and edit user subscriptions across different companies.
    4. Payment Methods: Manage registered payment options, including credit cards, debit cards, prepaid cards, main accounts, and saving accounts.
    5. Round-up Sources: Specifically manage payment methods used for the 'round-up' feature (spare change contributions) within a company.

  3. Overview of Cents API environments and testing

    The Cents API provides three distinct server environments to support different stages of development and deployment: Production, UAT (User Acceptance Testing), and SIT (System Integration Testing). Developers can use the interactive 'Try it out' feature within the documentation to test endpoints directly and verify input/output schemas before implementation.

  4. Understand the Cents Platform integration architecture

    The Cents platform integration is implemented using a combination of APIs and front-end components. Front-end components are integrated directly into the user's application to provide the User Interface and manage communications with the Cents API, ensuring a seamless integration experience.

  5. Retrieve a transaction by ID

    Retrieve detailed information about a specific transaction using the GET /auth/company/transactions/:id endpoint. This endpoint returns transaction data including amounts, currency, charity details, consumer information, and the current transaction status.
    GET /auth/company/transactions/{id}

  6. Retrieve a specific subscription within a company

    Use the GET /auth/consumer-user/company/:company_id/subscriptions/:id endpoint to retrieve detailed information about a specific subscription made within a company. This endpoint requires both the company's unique ID and the subscription's unique ID as path parameters.
    curl -X GET "https://<api-domain>/auth/consumer-user/company/{company_id}/subscriptions/{id}"

  7. Retrieve charity details via Payment Gateway API

    Use the GET /auth/payment-gateway/charities/:id endpoint to retrieve detailed information about a specific charity. This includes its internal Cents ID, payment provider IDs (Stripe and Nexi), sector restrictions (blacklists/whitelists), operational areas, categories, and causes with multi-language translations.
    GET /auth/payment-gateway/charities/{id}

  8. Authenticate consumer users using Company-Generated JWT

    In this JWT scenario, the company acts as the token issuer:

    1. Token Creation: The company generates a JWT using their private key, including claims about the consumer-user.
    2. Token Submission: The company sends the generated JWT to the Cents Donations API.
    3. Token Issuance: The API verifies the JWT and issues an access token for the consumer-user.

  9. Retrieve a specific round-up source transaction within a company

    Use the GET /auth/consumer-users/company/:company_id/round-up-sources/:round_up_source_id/transactions/:transaction_id endpoint to retrieve detailed information about a specific transaction associated with a round-up source for a given company.

    Path Parameters

    • company_id (string, required): Unique ID of the company in scope.
    • round_up_source_id (string, required): Unique ID of the round-up source within the company scope.
    • transaction_id (string, required): Unique ID of the transaction within the company scope.

    Response Fields (200 OK)

    • id (uuid): Cents ID of the transaction.
    • external_id (string): Payment gateway ID, prefixed with the payment gateway's unique name identifier.
    • company_id (uuid): Cents ID of the company.
    • order_amount (float): Transaction amount.
    • total_amount (float): Transaction amount.
    • currency (string): Transaction currency.
    • charity_id (uuid): Cents ID of the charity.
    • donation_cause (string): Cause unique name within the charity's namespace.
    • donation_amount (integer): Donation amount in the smallest currency unit (e.g., 1000 represents 10.00€).
    • donation_percentage (integer): Donation percentage (e.g., 3 for 3%).
    • donation_currency (string): Donation currency.
    • created_date (date): Transaction creation date.
    • updated_date (date): Transaction update date.
    • consumer_user_id (string): Cents ID of the consumer user.
    • consumer_user_full_name (string): Name of the consumer user.
    • consumer_user_email (email): Email of the consumer user.
    • consumer_user_email_anonymized (boolean): Flag indicating if the email is anonymized.
    • consumer_user_phone (string): Phone number of the consumer user.
    • billable_address (object): Contains street_address, city, region_state, zip_code, and country (all required strings).
    • payment_method (uuid): ID of the payment method used.
    • transaction_status (string): Current status. Possible values: pre_transaction, draft, to_be_payed, paid, refunded, disputed, failed.
    • refunded_amount (float): Amount that has been refunded.
    • reconciliation_id (string): External ID generated by the company to reconcile the transaction with the pre-transaction.
    curl -X GET "https://<api-domain>/auth/consumer-users/company/{company_id}/round-up-sources/{round_up_source_id}/transactions/{transaction_id}"

  10. Cents Company API functional overview

    The Cents Company API (v1.0.0) is organized into six primary functional groups. Some endpoints are public for non-sensitive information, while others require authentication to manage sensitive data:

    1. Info: Company details (Authenticated).
    2. Charities: Information about associated charities, causes, impact areas, and company-selected charities (Public or Authenticated).
    3. Transactions: Management of individual transactions and pre-transactions, including creation and updates (Authenticated).
    4. Subscriptions: Management of consumer user subscriptions, including creation, editing, and retrieval (Authenticated).
    5. Consumer Users: Management of consumer user profiles, including creation and editing (Authenticated).
    6. Round-up Sources: Management of payment methods for round-up transactions (e.g., credit cards, debit cards, prepaid cards, main accounts, and saving accounts) (Authenticated).

  11. Retrieve a consumer user round-up source transaction

    Retrieve detailed information about a specific transaction for a consumer user's round-up source using the GET method. The response includes transaction amounts, currency, charity details, donation amounts (in the smallest currency unit), and the transaction status.
    GET /auth/company/consumer-users/:consumer_user_id/round-up-sources/:round_up_source_id/transactions/:transaction_id

  12. Understand Cents Platform integration architecture

    The Cents platform integration is implemented using a combination of APIs and front-end components. Front-end components are integrated directly into the user's application to provide the User Interface and manage communications with the Cents API, ensuring a seamless integration experience.