REST API, version 2026-03-01
All requests go to https://api.tapped.so over TLS 1.3. Authenticate with a bearer token in the Authorization header. Every write endpoint is idempotent; pass an Idempotency-Key header and retries are safe.
Create a charge
Authorises and captures a charge in one call. For tap transactions, use the /v1/taps endpoint, it includes the EMV cryptogram envelope.
POST /v1/charges
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
amount | integer | required | In minor units. 4850 = 48.50. |
currency | iso_4217 | required | Three-letter code. Must match submerchant's settlement currency. |
submerchant | string | required | Handle of the sub-merchant receiving the funds. |
capture_mode | enum | optional | tap (default) · pre-auth · manual. |
metadata | object | optional | Free-form key/value pairs, returned on the object unchanged. |
Retrieve a charge
Fetches a charge by its canonical ID. Returns the full object including the latest authorisation, capture, and settlement references.
GET /v1/charges/:id
Path parameter: id, the charge ID (begins with ch_).
List charges
Returns a paginated list of charges, most recent first. Filter by submerchant, status, date range, or metadata.
GET /v1/charges
Capture a tap
The workhorse endpoint. Submits an EMV cryptogram and gets back an authorised charge. Median round-trip is ~400 ms; p99 is 720 ms.
POST /v1/taps
| Field | Type | Required | Notes |
|---|---|---|---|
amount | integer | required | Minor units. |
currency | iso_4217 | required | |
submerchant | string | required | |
device | string | required | Handle of the provisioned tap device (phone or terminal). |
tip | integer | optional | Minor units. Added to amount pre-auth. |
reference | string | optional | Your POS reference; round-trips to the settlement report. |
Create an authorisation
Authorises a hold without capturing. Useful for rentals, hotel incidentals, and field-services pre-auths where the final amount is known at job close, not job start.
POST /v1/authorisations
Capture an authorisation
Moves money against a previously-created authorisation. Capture amount must be ≤ the authorised amount; unused portion releases automatically.
POST /v1/authorisations/:id/capture
Create a sub-merchant
Registers a sub-merchant with the appropriate acquirer. KYB and risk screening run asynchronously; listen for the submerchant.kyb.completed webhook or poll status.
POST /v1/submerchants
| Field | Type | Required | Notes |
|---|---|---|---|
display_name | string | required | Shown on statements and receipts. |
country | iso_3166_a2 | required | Settlement jurisdiction. |
mcc | string | required | ISO 18245 four-digit merchant category code. |
business | object | required | Legal entity details: legal_name, tax_id, incorporation_country. |
owners | array | required | Any beneficial owner with 25 %+ ownership. |
Retrieve a sub-merchant
Returns the full sub-merchant record including current KYB status, risk flags, acquirer references, and payout schedule.
GET /v1/submerchants/:id
List payouts
Returns a paginated list of payouts, most recent first. Each payout includes the constituent settlements and the bank wire reference.
GET /v1/payouts
List disputes
Every chargeback, pre-arbitration, and arbitration across every market. Includes the scheme deadline and the list of required evidence fields for the host scheme.
GET /v1/disputes
Submit dispute evidence
Upload evidence for an open dispute. Accepts structured fields and signed PDF/image attachments. Submissions are checked against scheme rulebooks before transmission.