Contribution Collection System (Billing)

The Humance SDK integrates seamlessly with fintech partners to handle user contributions to projects. This system ensures secure fund transfers and real-time reconciliation between the Humance platform and partner ecosystems.

How the Contribution Flow Works

1. Transaction Creation:

• When a user selects a project and confirms a contribution amount, the SDK sends a request to the Humance API to create a transaction.

• The API generates a unique transaction ID and returns it in the response.

API Request:

PUT https://humance.io/company/integration/contributions/create
Content-Type: application/json
API-Key: <Your API Key>
API-Secret: <Your API Secret Key>

Payload:

{
    "project_id": 4,
    "amount": 100.20,
    "user_hash": "hashed_user_email"
}

Response:

{
    "transaction_id": "abc123xyz456",
    "status": "pending"
}

2. Funds Transfer by Fintech Partner:

• After the transaction is created, the partner bank transfers the specified contribution amount to a dedicated account in their ecosystem.

• The transfer metadata must include the transaction ID for traceability.

Example Transfer Metadata:

transaction_id: abc123xyz456
amount: $100.20

Completion Notification:

• Once the funds are successfully transferred, the partner bank notifies Humance by sending a PUT request to the PUT /contributions/{transaction_id} endpoint.

• This notification updates the transaction status to "completed" in the Humance backend.

PUT Request:

PUT https://humance.io/company/integration/contributions/abc123xyz456
Content-Type: application/json
API-Key: <Your API Key>
API-Secret: <Your API Secret Key>

Payload:

{
    "status": "completed"
}

4. Transaction Status Update:

• The Humance backend processes the request and updates the transaction status to "completed".

• A confirmation response is returned to the partner bank.

Response:

{
    "transaction_id": "abc123xyz456",
    "status": "completed",
    "message": "Transaction successfully updated"
}

---

Integration Guidelines

To integrate the contribution collection system, fintech partners must:

1. Include the Transaction ID in Transfers:

   • Ensure that the unique transaction_id provided by the Humance API is included in the fund transfer metadata for reconciliation.

2. Authorize All Requests:

   • Use your API-Key and API-Secret in the headers for every request to authenticate and validate your company.

3. Send a Completion Notification:

   • After successfully transferring funds, send a PUT request to the PUT /contributions/{transaction_id} endpoint to mark the transaction as completed.

4. Handle Errors and Retries:

   • Implement retry logic in case the PUT the request fails temporarily.

---

Example Use Case

1. A user contributes $50 to a reforestation project via the SDK.

2. The SDK sends a transaction creation request to the Humance API, which generates transaction_id: tx789xyz123.

3. The partner bank transfers $50 to the dedicated Humance account and includes transaction_id: tx789xyz123 in the metadata.

4. The partner bank confirms the transfer by sending:

   PUT /contributions/tx789xyz123

   With the payload:

   {
       "status": "completed"
   }

5. The Humance backend updates the transaction status to "completed", finalizing the contribution.

---

Best Practices

• Real-Time Synchronization:

  • Ensure fund transfers and completion notifications occur immediately after transaction creation to maintain accuracy.

• Error Handling:

  • Monitor and retry failed transfers or notifications. Use logging mechanisms to track issues.

• Unique Transaction IDs:

  • Always include the transaction ID in all communications and fund transfers to avoid mismatches.