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/{destinationAddress}/{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":"QZhFl0ksUmSa23Y2MeS6fIQhZoQtsxtmbZQutIwCEev2YAAAAAEBQeD9c4pd7MFG9tP+BflD4xRP1n1UErzusJGNlFOPZZDnYwAAAGQAIgm377laOT2e4B9kRvNi5c9W1e7lWwDmEY2zZ+KMapReIogvmMjwOWWFpaBAJY7nrx+mWLErMjdHIHpjS/7mK3CVQZhFl0ksUmSa23Y2MeS6fIQhZoQtsxtmbZQutIwCEev2QQFV1LEfV++FLP8nFJrwSrfFbnQtFrBR38QPKK1n2/3MYwAAAIQiQQSJ1+W00y91iIwk6yB2U0LmcPwmFpacux/Qbj0zJNVB4P1zil3swUb20/4F+UPjFE/WfVQSvO6wkY2UU49lkOci26g2NuqioUucwhlmmk+Ct/5tCM3UMYtb+jfVHUepv08i8ngcwAIMMAyEw7m/vjjOuJSfLBztYeKfJckP+FPrg+RB0wBgwz3z2UfQcdTg4XX/tv+44nRBkThaSd2dMM3Mva1jAAAAQiKc0ONefyM6HAP2IPfFAkuvNcIp34GtYTxiKZa8HcTaN0EBVdSxH1fvhSz/JxSa8Eq3xW50LRawUd/EDyitZ9v9zEHtphctl+26E0kcUmPNOWxopFA2w3fHROrIcU1Zplz1GGMAAABCItuoNjbqoqFLnMIZZppPgrf+bQjN1DGLW/o31R1Hqb9PIvJ4HMACDDAMhMO5v744zriUnywc7WHinyXJD/hT64PkQRfyHmfZQeCl3nb07KJxsueVpJ7eW3H0l7lPy3gQAoKwYwAAAIQiSKiM7Tyy7n6Bh/zMTXDa2Ox1u48Btdv835TvDOT8rqRB7aYXLZftuhNJHFJjzTlsaKRQNsN3x0TqyHFNWaZc9RginNDjXn8jOhwD9iD3xQJLrzXCKd+BrWE8YimWvB3E2jdBAVXUsR9X74Us/ycUmvBKt8VudC0WsFHfxA8orWfb/cxBD9S6+uUGcoBPldZR+dH/pZaHExYNjlPvK8fBFPw+BTpjAAAAQiLbqDY26qKhS5zCGWaaT4K3/m0IzdQxi1v6N9UdR6m/TyL870L0WSu1AKbgP9sMgO9nnl3OPLs8GrmGEIuGZRzLEkHTRniJSAiN3agkRSnVSbUFaZQWMfJTUbWL0ULy8/Rx9WMAAADGIgsL/dB9cBJVpS3/YmxKabevc+QgYYV7SwRTdULE5OpSQQ/UuvrlBnKAT5XWUfnR/6WWhxMWDY5T7yvHwRT8PgU6IkiojO08su5+gYf8zE1w2tjsdbuPAbXb/N+U7wzk/K6kQe2mFy2X7boTSRxSY805bGikUDbDd8dE6shxTVmmXPUYIpzQ415/IzocA/Yg98UCS681winfga1hPGIplrwdxNo3QQFV1LEfV++FLP8nFJrwSrfFbnQtFrBR38QPKK1n2/3MQbXTcey/0egXa6kukSuc1xpvpa8xuVOwzKd8M6Z/5KxBYwAAAKYAIvzvQvRZK7UApuA/2wyA72eeXc48uzwauYYQi4ZlHMsSIkOL/2CI6oEhIt4HtDKcWFPxyp4r/o1lwkM8RRTzuPg3IkOL/2CI6oEhIt4HtDKcWFPxyp4r/o1lwkM8RRTzuPg3ItKZE/frm3bwoSJ9CzRGW3rfIjZFLiBzQZfkDaeQ8fANQdNGeIlICI3dqCRFKdVJtQVplBYx8lNRtYvRQvLz9HH1QWEZrts3eqnpn4s1SUHflF2mKsF6zLqXH7qps32IhGaCYAAAAAhAk0gAAAAAAEEKdTgizHP/LsdThtD+AwMFWx/MeELw+nKnncJTaoktx2MAAABkACLyeBzAAgwwDITDub++OM64lJ8sHO1h4p8lyQ/4U+uD5CKIL5jI8DllhaWgQCWO568fplixKzI3RyB6Y0v+5itwlUFhGa7bN3qp6Z+LNUlB35RdpirBesy6lx+6qbN9iIRmgkF3s1EtnyN25bvjPfp8eFi4IDmXeTtyTGGrSkF0wZrSS2AAAAAIAAAAAAAAAABBZKnImF9NQkvJl8JNKcPGDruXe4ll72URRKwqvnu2WUBjAAAAZAAi8ngcwAIMMAyEw7m/vjjOuJSfLBztYeKfJckP+FPrg+QiiC+YyPA5ZYWloEA...
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.