API Reference

Comprehensive documentation for the TangentoPay REST API.

Getting Started with the API

Learn how to set up and use the TangentoPay API for custom integrations. This reference provides endpoint details, examples, and best practices.

The TangentoPay API empowers developers to create tailored payment experiences, from collecting funds to managing disbursements and services. It's RESTful, JSON-based, and supports quick integration via SDKs. Start in minutes with our endpoints and scale to production seamlessly.

Questions? Email dev-support@tangentopay.com or join our Slack community for code reviews and tips.

Prerequisites

A verified TangentoPay account (Individual or Company).
Completed KYC/KYB verification to access live mode.
A created service in the dashboard: This generates your API Key and API User credentials.
Familiarity with HTTP requests (e.g., via cURL or SDKs).
Optional: Install SDKs for your language (npm for JS, pip for Python).

Note

Review the Preliminary Knowledge section for authentication, request formats, and rules. Always test in sandbox mode (append ?test=true to base URL) before going live.

Security Note

Store API keys securely (e.g., environment variables); never expose in client-side code.

What You Can Do with the API

The API covers core operations for building financial applications:

1. Collect Payments

Initiate Payment: Leverage hosted checkout pages for minimal setup.
Direct Payment: Collect details client-side and process server-side for custom UIs.

2. Disburse Funds

Create single or bulk payouts, including withdrawals and refunds.

3. Manage Services

4. Monitor and Analyze

Retrieve transactions, balances, and logs. Export reports for compliance.

Authentication

The TangentoPay API uses Bearer Token authentication. Pass your secret key in the Authorization header.

Authorization: Bearer sk_live_1234567890abcdef

Base URL

All API requests should be made to the following base URL:

https://api.tangentopay.com/v1

Preliminary Knowledge

API Credentials

API Key: A secret string generated per service; used for authentication.
API User: The associated username for Basic Auth fallback.

Authentication Methods

PreferredBearer Token in headers (Authorization: Bearer {api_key}).
AlternativeBasic Auth with API User and Key.

Example Header:

Authorization: Bearer sk_live_12345abcde

Request Structure

Base URL: https://api.tangentopay.com/v1
Headers: Content-Type: application/json, Authorization: Bearer {key}, Idempotency-Key: {unique_string} (optional)
Body: JSON format (e.g., {"amount": 1000, "recipient": "+237..."}); use snake_case keys.

Response Structure

Success (2xx): Returns JSON with data and status.
Error (4xx/5xx): Returns error object with code and message.

Example Success Response:


{
  "status": "success",
  "data": {
    "transaction_id": "txn_123abc",
    "amount": 5000,
    "currency": "XAF"
  }
}

Rate Limits

Standard: 100 requests/minute per service.
Burst: Up to 20 requests/second during spikes.
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Exceeding limits returns 429 Too Many Requests. Contact support to request higher limits.

Endpoints Overview

Detailed endpoint documentation is available per category:

Payouts

POST /payouts, GET /payouts/{id} — Disbursements to Mobile Money, banks.

Top-ups

POST /topups — Add funds to payout wallet via Mobile Money.

Payments

POST /payments/initiate, /payments/direct — Collect via hosted or direct flows.

Services

POST /services, GET /services, PUT /services/{id} — Manage integrations.

Logs

GET /logs — Query API call history with filters.

Error Handling

Errors return standardized JSON with an HTTP status, error code, and message.

Common Error Codes:

400 Bad Request401 Unauthorized403 Forbidden404 Not Found429 Too Many Requests500 Internal Error

Example Error Response:


{
  "status": "error",
  "error": {
    "code": "invalid_amount",
    "message": "Amount must be greater than 0"
  }
}

Tip

Always check the error code field for programmatic handling, and display the message to users where appropriate.

Webhooks

Configure webhook URLs in your dashboard to receive real-time notifications for events like payment completion, payout success, or failures.

Events: payment.completed, payout.completed, payout.failed, topup.completed, payment.failed.
Security: Verify webhook signatures using the X-Tangento-Signature header.
Retries: Failed deliveries are retried up to 5 times with exponential backoff.

Example Webhook Payload:


{
  "event": "payment.completed",
  "data": {
    "transaction_id": "txn_abc123",
    "amount": 5000,
    "currency": "XAF",
    "status": "success"
  },
  "timestamp": "2025-01-15T10:30:00Z"
}

SDKs & Libraries

Official SDKs simplify integration. Install via package managers and start building in minutes.

JavaScript / Node.js

npm install @tangentopay/sdk

Python

pip install tangentopay

PHP

composer require tangentopay/sdk