TODA Twin Micropayment Proxy

Micropayments have traditionally been challenging to achieve, as the cost of executing and settling each transaction often exceeded the value of the transactions themselves. With its tiered integrity line architecture, clients can configure their TODA Twin to execute very small-valued payments without the burden of an excessive globally-settled ledger system.

The TODA Twin system features a dedicated micropayment subsystem purpose-dedicated for API-to-API (or machine-to-machine) payments. The TODA Twins serve both client and server HTTP proxies to attach and receive necessary payment.

Instead of directly making requests to a service provider's server, the end client instead makes the same request, but delivers it to their twin's outgoing payment proxy. They specify the payment type hash, payee address hash, and payment amount in this URL, as well as the desired destination URL. The API provider similarly does not route incoming API requests directly to their server, but routes them to the incoming payment proxy of their TODA twin. The service provider's twin is configured to only accept payments which meet the requisite type and amount. If these criteria are met, the TODA Twin forwards the request to the configured service provider URL.

The end client's TODA Twin proxy sits between the end client and the incoming payment proxy configured by the service provider. This proxy functions as a convenience to the end client, by attaching TODA payment automatically, in-line with the request. It accepts any HTTP method, and all request particulars are included in the forwarded request.

Specification

Requests made to the outgoing payment proxy are of the form: {METHOD} https://{twinUrl}/pay/{paymentTypeHash}/{amount}/{destinationUrl}

The destination URL should represent the URI component encoding of the incoming proxy of the service provider.

For example: POST https://41f0439.endusercorp.biz.todaq.net/pay/4112261cfaa3fcb9a120aa4b231819403e5110ced4f8eae5312f5adb57b8260411/15/https%3A%2F%2F4112261c.serviceprovider.biz.twin.todaq.net%2Fpaywall

The proxy will forwarded the POST request, along with the requested payment, to the destination URL.

An example request forwarded from the outgoing payment proxy:

"request-id":"a391333e-ff71-4867-85f5-ebe0e2cce855"
"request":"POST /paywall/foobar"
"accept":"application/json, text/plain, */*"
"content-type":"application/json"
"user-agent":"lynx"
"content-length":"12"
"accept-encoding":"gzip, compress, deflate, br","connection":"close"
"x-toda-pay-41f24cd8a33139a6e10fa6fb1feec8531b65979c893a1dbb3b78c93a725561ed6f":"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...
body: <binary>

The service provider's TODA Twin proxy sits between incoming requests and their server. The proxy only permits requests to continue to the server if they contain the required payment.

Configuration

Three configuration parameters are required to be specified in the TODA Twin backend configuration:

• targetUrl e.g. https://service.provider.example/secured/resource
• targetPayType e.g. 4111861cfaa3fcb9a120aa4b231819403e5110ced4f8eae5312f5adb57b8260411
• targetPayQuantity e.g. 15

Incoming requests

Incoming requests which contain attached TODA payment information added by the Outgoing Proxy are to be directed at the path /paywall/. They may be of any HTTP method.

All original headers, HTTP method, and body are forwarded to the service provider's secured resource. The TODA-specific headers are filtered prior to forwarding.

End client

The end client is the user, script, or machine initiating an HTTP API call to some service provider's API.

Service provider

The service provider is the entity who is securing a resource ('secured resource') by requiring payment in TODA before permitting access

Secured resource

The secured resource is any HTTP endpoint served by the service provider which can only be accessed through their configured Incoming Payment Proxy

TODA Twin Outgoing Payment Proxy

The outgoing payment proxy is an endpoint on the TODA Twin belonging to the end client, which automatically appends TODA payment to an outgoing HTTP request.

TODA Twin Incoming Payment Proxy

The incoming payment proxy is an endpoint on the TODA Twin belonging to the service provider, which only forwards incoming requests if they meet the required payment.

Overpayment

Requests containing excessive payment are permitted access to the secured resource. The excess payment is deposited to the payee.

Underpayment

Requests containing insufficient payment are not permitted access to the secured resource. The payment is not deposited to the payee.

Service provider endpoint security

The Incoming Payment Proxy will only permit paid requests to be forwarded to the secured resource. However, it is the service provider's responsibility to ensure the secured resource is configured to only accept requests which have been so forwarded (and have not bypassed the proxy through some other network route).

Settlement

Payments are settled upon receipt, in-line with the API request.

Data format and Logging

TODA files are attached using HTTP extension headers, prefixed with X-TODA-Pay, and encoded in Base64 in order to meet character encoding constraints. These headers, although large, are safe to log and do not contain any secrets or personal information. Although TODA files are bearer tokens, the bearer is established by the controller of secret cryptographic keys maintained in the TODA Twin, rather than access to the raw bytes of the TODA file.

Proxy pass-through

HTTP headers (including content-type, etc.), HTTP method, HTTP body, and encoded URL are all passed through the two TODA Twin proxies, and the request result is streamed back transparently. Some additional headers may be added, and in some cases the user agent string may be modified.

Background

The TAPP Paywall API enables API developers (with a first focus on video content providers and supporting API and AI services) to monetize their APIs through micropayments using TODAQ Twins. A TODAQ Twin acts as a secure proxy for handling payments between parties without traditional transaction fees overwhelming small amounts, and removing the need for back office administration, billing, invoicing, collections, and cash cycle time delays. Portable, verifiable records of all transactions are automatically maintained and accessible. This system supports API-to-API or machine-to-machine interactions, making it ideal for paywalling digital streamed content like, videos, data, or articles and paywalling supporting digital services such as AI video data labelling, AI video caption generation, AI reels and shorts generation, and more.

Here's how it operates at a high level:

• Service Provider's Side (Content Developer): You set up a Twin as an incoming payment proxy. This Twin is configured to require a specific payment type and amount before forwarding requests to your secured content endpoint. The secured endpoint typically generates temporary access (e.g., signed URLs) to your content stored on a CDN or similar storage. Each piece of content can have its own dedicated Twin to collect earnings.
• Consumer's Side: The consumer uses their own charged-up Twin as an outgoing payment proxy. They direct requests through this proxy, specifying the payment details and the provider's paywall URL. If the payment meets the requirements, the provider's Twin forwards the request, and the consumer receives access to the content (e.g., a signed URL).
• Funds Charge Up and Bank Transfers: A Twin can be charged up with USD funds through Stripe, Apple Pay, Google Pay, and USD ACH and bank wire. Received funds can be transferred by a provider or their customers to their bank account of choice through USD ACH and wire transfer. Speak to your TODAQ representative.
• Payment Flow: Payments are attached inline with HTTP requests using special headers. The system handles overpayments (excess goes to the provider) and rejects underpayments. Settlements occur immediately upon successful receipt, ensuring real-time micropayments without global ledger overhead.
• Security Considerations: The provider's internal endpoints for generating access remain hidden; only the Twin's paywall URL is shared publicly. All HTTP methods, headers, and bodies are passed through transparently, but providers must secure their endpoints to prevent bypass.

This setup ensures content is only accessible after payment, with Twins managing the cryptography and proxying to keep things efficient and secure.

Steps for Each Party

Steps for the Content Developer (Service Provider)

As the content developer, you'll configure Twins to act as paywalls for your content. This involves setting up secure content delivery and integrating with the Twin API.

1. Set Up Secure Content Access:

   • Choose a method to generate temporary, signed URLs for your content hosted on a CDN (e.g., AWS CloudFront's Signed URLs). This ensures content can't be accessed directly without authorization.
   • Implement a hidden script or endpoint (e.g., on AWS Lambda or your domain) that generates a new signed URL for a specific content ID upon request. This endpoint should not be publicly accessible and should respond to HTTP requests (typically GET) with the signed URL.
     • Example endpoint: GET https://your.domain/secure/produce-new-signed-url/<content-id>
     • Response: A signed URL like https://your.cdn.domain/<content-id>?Signature=...

2. Contact Account Engineer for Content-Twin Creation Endpoint

   • A new endpoint for your enterprise configuration will be created to reflect flows resulting from payment to paywalled twins
   • Follow instructions as provided to POST to this endpoint and retrieve content-specific twin addresses and keys.
   • Be prepared to supply a targetUrl specifying the endpoint which will return the one-time content link, and the targetPayQuantity, the amount to be paid for the item.

3. Integrate and Test the Paywall:

   • List your content publicly using only the Twin's paywall URL (e.g., https://<twin-hostname>/paywall), not your internal hidden URL.
   • Ensure your hidden endpoint handles forwarded requests from the Twin (any HTTP method, but commonly GET). Check server logs for issues like unexpected headers or methods.
   • Test end-to-end: Simulate a consumer payment and verify the signed URL is returned only after payment.
   • Monitor earnings via the Twin's API (e.g., call /dq with your API key to get balance details).

4. Handle Security and Edge Cases:

   • Secure your hidden endpoint against direct access (e.g., via IP restrictions or authentication).
   • If issues arise (e.g., 404 or 401 errors), check for URL encoding in consumer requests, proxy headers, or security blocks on your side.
   • Reconfigure Twins if needed to update hidden URLs without exposing them.

5. Monitor Balances:

   • Query your Twins’ balance via the API (e.g., call /dq with your API key to view available notes).

6. Retrieve Transaction Records:

   • Query your Twins' transaction history via the API (e.g. call /binder with your API key to view available history).

7. Consolidate Funds:

   • If you have multiple pieces of paywalled content or API endpoint services we recommend you implement the TAPP micro-distribution payouts so each of your paywall Twins automatically transfer funds into a Master Treasury Twin. Speak to your representative about setting up distributions.

8. Publish Paywalls:

   • Expose your paywall URLs in a catalogue format such as JSON, so they can select the appropriate URL to pay (e.g. [{name: 'How to Improve Your Squash Game', paywall: 'https://41238582304.squash.biz.todaq.net/paywall'} ...])
   • With your JSON API Paywall Catalog published and easy to find for any interested customer, they can instantly pay-as-they go for your content or API service as long as the request is properly formed with a valid payment. They do not need to be signed up as a customer, reducing abandonment friction and increasing your market size.

9. Transfer Funds to Bank Account:

• Login into the TAPP Banking Gateway to initiate funds transfer. Speak to your TODAQ representative.

Steps for the Consumer

As the consumer, you'll use your pre-charged Twin to pay for and access paywalled content.

1. Set Up Your Twin:

   • Ensure you have a TODA Twin charged with sufficient balance in the required payment type. You can charge it via compatible services (refer to Twin documentation for setup).

2. Construct the Payment Request:

   • Obtain the provider's paywall URL (e.g., https://<provider-twin-hostname>/paywall).
   • URL-encode the paywall URL (e.g., convert / to %2F, : to %3A).
   • Build the request URL using your Twin's outgoing proxy:
     • Format: {METHOD} https://<your-twin-hostname>/pay/<payment-type-hash>/<amount>/<encoded-provider-paywall-url>?apiKey=<your-api-key>
     • Example (assuming GET): GET https://<your-twin-hostname>/pay/<hash>/0.05/https%3A%2F%2F<provider-twin-hostname>%2Fpaywall?apiKey=...
   • Include any necessary headers or body if the provider's endpoint requires them.

3. Send the Request and Retrieve Content:

   • Execute the request (e.g., via curl, script, or application). Your Twin will attach the payment automatically.
   • If successful, the response will include access to the content (e.g., a signed URL).
   • Handle errors: 401 might indicate authentication issues; 404 could mean a misconfigured URL or endpoint.

4. Monitor Balances:

   • Query your Twins’ balance via the API (e.g., call /dq with your API key to view available notes).

5. Retrieve Transaction Records:

   • Query your Twins' transaction history via the API (e.g. call /binder with your API key to view available history).

FAQs

What if the payment amount is more or less than required? Overpayments are accepted, and the excess is deposited to the provider's Twin. Underpayments are rejected, and no access is granted—the payment isn't processed.

How do I handle different HTTP methods? The Twins pass through any HTTP method (GET, POST, etc.) used in the original request. Providers should ensure their hidden endpoint supports the expected method; consumers should match the provider's requirements.

Why am I getting a 401 Unauthorized error? This could be due to an invalid API key, incorrect URL formatting, or authentication issues on the provider's side. Double-check your API key and ensure the paywall path (/paywall) is included and properly encoded.

What about 404 Not Found errors? Often caused by URL encoding issues, extra parameters, or the provider's endpoint not handling the request. Providers: Check server logs. Consumers: Verify encoding and test with a known working paywall URL.

How secure is this setup? Twins handle payments cryptographically, and internal endpoints remain hidden. Providers must secure their resources to prevent direct access. Payment headers must not include personal data or secrets.

Can I test without real payments? Start with small test Twins and low amounts. Use curl or scripts to simulate requests. Providers: Set up 1-2 Twins initially for end-to-end verification.

How do I scale for multiple content items? Create a separate Twin per content piece to isolate earnings. Automate Twin creation via API for larger scales.

What if the request is blocked by security? Provider-side security (e.g., firewalls) might block proxied requests due to headers or user agents. Adjust configurations to allow Twin-forwarded traffic.

How are payments settled? Settlements happen inline upon receipt—no delays. Balances update immediately in the Twins.

Can consumers monitor their spending? Yes, via the Twin's /dq API endpoint, which returns all quantitative note balances.