Skip Navigation
Log In Sign Up

Payments

·

The Payments API allows you to track and manage financial transactions within the Tupel platform. Payments represent money movement for both disbursements (sending funds) and repayments (collecting funds).

Payment Types

Tupel handles different types of payment transactions:

  • DEBIT - Money sent out (disbursements to loan recipients)
  • CREDIT - Money collected (repayments against loans)

Each payment is associated with a reason that provides additional context for the transaction.

Payment Lifecycle

A typical payment in Tupel follows this lifecycle:

  1. Initiation: A payment is created with a PENDING status
  2. Processing: The payment is processed through the banking system
  3. Completion: The payment reaches its final status (SETTLED or FAILED)

Payment Status

Payments can have the following statuses:

  • PENDING - The payment has been initiated but not yet completed
  • SETTLED - The payment has been successfully processed
  • FAILED - The payment failed to process

Multi-Currency Support

Tupel provides comprehensive support for multi-currency transactions:

  • Each payment has an original currency and amount
  • For reporting consistency, payments include a normalized_currency and normalized_amount
  • Foreign exchange details are captured in the fx_rate object, including:
  • Source and target currencies
  • Bid, ask, and mid-market rates
  • Timestamp of the rate

Available Endpoints

Endpoint Description
Retrieve a Payment Get details about a specific payment
List All Payments Get a paginated list of payments with filtering options

Best Practices

  • Regularly monitor payment statuses to ensure successful processing
  • Implement webhooks to receive real-time notifications of payment status changes
  • Use appropriate filtering when listing payments to improve performance
  • Store the payment UID in your system for future reference
  • For reconciliation, combine date filters with status and type filters
  • Loans - Payments are typically associated with loans
  • Entities - Organizations related to payments
  • Recipients - Destinations for disbursement payments
  • Payment Methods - Sources for repayment collections

Common Use Cases

Tracking Loan Disbursements

When a loan is created and funds are disbursed, a DEBIT payment is created:

# Retrieve the disbursement payment
curl -X GET "https://tupel.com/api/payments/8rJ7i/" \
  -u <YOUR_ORG_ID>:<YOUR_API_KEY>

Monitoring Repayments

Track payments made against loans:

# List all settled repayments
curl -X GET "https://tupel.com/api/payments/?status=SETTLED&type=CREDIT" \
  -u <YOUR_ORG_ID>:<YOUR_API_KEY>

Reconciliation and Reporting

Generate filtered lists of payments for reconciliation:

# Get all payments for a date range
curl -X GET "https://tupel.com/api/payments/?created_from=2023-01-01T00:00:00Z&created_to=2023-01-31T23:59:59Z" \
  -u <YOUR_ORG_ID>:<YOUR_API_KEY>

Currency Conversion Analysis

Examine foreign exchange details for cross-currency transactions:

# List payments with currency conversion
curl -X GET "https://tupel.com/api/payments/?currency=EUR&normalized_currency=USD" \
  -u <YOUR_ORG_ID>:<YOUR_API_KEY>