--- title: Tap Payments API Integration on Truto slug: tappayments category: Payment Gateway canonical: "https://truto.one/integrations/detail/tappayments/" --- # Tap Payments API Integration on Truto **Category:** Payment Gateway **Status:** Generally available ## MCP-ready AI tools Truto exposes 72 tools for Tap Payments that AI agents can call directly. - **create_a_tap_payments_authorize** — Create an authorization hold on a card in Tap. Returns the authorize object including id, object, status, amount, currency, live_mode, api_version, method, transaction, reference, response, card, customer, source, redirect, post, auto, merchant, metadata, and payment_agreement. - **update_a_tap_payments_authorize_by_id** — Update an existing Tap authorization by id. Only description, metadata, and receipt may be modified; all other fields remain unchanged. Returns the updated authorize object including id, status, amount, currency, live_mode, api_version, transaction, customer, source, card, redirect, post, and auto details. Required: id. - **tap_payments_authorize_download** — Download Tap authorize records filtered by date range and merchant IDs. Returns the authorize records as a downloadable file. - **create_a_tap_payments_authorize_download** — Create a Tap authorize download request to export authorize records matching specified filter criteria. Returns a downloadable file of matched authorize records; response format is content-type-specific (text/plain or application/json). - **create_a_tap_payments_charge** — Create a charge in Tap to collect payment from a customer. Returns the created charge object including id, status, amount, currency, customer, card, source, and transaction details. Required: amount, currency, customer, source, redirect. - **list_all_tap_payments_charge** — List charges in Tap with optional filters for period, status, customers, and currency. Returns each charge record including id, status, amount, currency, customer, card, source, and transaction details. - **update_a_tap_payments_charge_by_id** — Update an existing Tap charge. Only description and metadata can be modified. Returns the updated charge object including id, status, amount, currency, customer, card, source, and transaction details. - **tap_payments_charge_download** — Download charges from Tap as a bulk report, filtered by period, merchants, status, currency, and more. Returns charge records including id, status, amount, currency, customer, source, card, and transaction details. The response format can be JSON or plain text via the accept header. - **create_a_tap_payments_charge_download** — Create a charge download report in Tap by posting filter criteria such as period, merchants, status, currency, payment methods, and customers. Returns charge records including id, status, amount, currency, customer, reference, card, transaction, and merchant details. - **create_a_tap_payments_refund** — Create a refund against an existing Tap charge, supporting full or partial refund amounts. Returns the refund object including id, status, amount, currency, charge_id, created, date, reference, response, gateway, and transaction details. Required: charge_id, amount, currency, reason. - **tap_payments_refund_download** — Download refund records from Tap. Returns refund objects including id, status, amount, currency, charge_id, created, date, reference, response, gateway, and transaction details. - **create_a_tap_payments_refund_download** — Create a refund download report in Tap by posting filter criteria such as merchants, period, status, currency, and dispute flags. Returns refund records including id, object, amount, charge_id, currency, status, created, date, reference, transaction, gateway, and reason. - **create_a_tap_payments_business** — Create a new business in Tap. Returns the created business object including id, name, type, entity, contact_person, and brands. Required: name, type, entity, brands. Pass an idempotent string to prevent duplicate creation. - **list_all_tap_payments_business** — List businesses in Tap with optional filtering by business_id, idempotent key, brand, entity, and user details. Returns business records including id, name, type, entity, contact_person, and brands. - **list_all_tap_payments_destination** — List all destinations in Tap. Returns: id. Max 50 destinations per call. - **get_single_tap_payments_destination_by_id** — Get a single Tap destination by its unique identifier. Returns: id, amount, currency. Required: destination_id. - **create_a_tap_payments_merchant** — Create a new merchant in Tap linked to a business entity, brand, and optional branch or wallet. Returns the merchant record including display_name, business_id, business_entity_id, brand_id, wallet_id, charge_currenices, bank_account, and settlement_by. Required: display_name, business_id, business_entity_id, brand_id. - **list_all_tap_payments_merchant** — List all merchants in Tap for a given business, optionally filtered by business_id and date period. Returns merchant records including display_name, business_id, business_entity_id, brand_id, wallet_id, charge_currenices, bank_account, and settlement_by. - **create_a_tap_payments_invoice** — Create a new invoice in Tap. Returns the created invoice object including its id, draft status, due and expiry dates, mode, customer, order, notifications, reference, and redirect configuration. Required: due, expiry, customer, order. - **list_all_tap_payments_invoice** — List invoices in Tap filtered by date period, reference, or track status. Returns invoice records including id, draft, due, expiry, mode, customer, order, and reference. Supports ordering by field and direction. - **update_a_tap_payments_invoice_by_id** — Update an existing Tap invoice. Returns the updated invoice object including its id, draft status, due and expiry dates, mode, customer, order, notifications, and reference. Required: invoice_id, due, expiry, customer, order. - **create_a_tap_payments_dispute_download** — Create a dispute download request in Tap for a specified date period and optional list of merchant IDs. Returns dispute data as a downloadable file whose content is either application/json or text/plain depending on the accept header — the payload is file content and not a structured record. Required: period. - **create_a_tap_payments_file** — Create a file in Tap by uploading a document. Returns the created file object including id, filename, purpose, title, type, size, url, and links. Required: purpose, file, title, expires_at, file_link_create. - **create_a_tap_payments_customer** — Create a new customer in Tap. Returns the created customer object including id, first_name, last_name, email, and phone. Required: first_name. - **list_all_tap_payments_customer** — List customers in Tap. Returns a paginated collection of customer records, each including id, first_name, last_name, email, and phone. - **get_single_tap_payments_customer_by_id** — Get a Tap customer by customer_id. Returns the customer object including id, first_name, last_name, email, and phone. Required: customer_id. - **update_a_tap_payments_customer_by_id** — Update an existing Tap customer. Returns the updated customer object including id, first_name, last_name, email, and phone. Required: first_name. - **list_all_tap_payments_payout** — List Tap payouts within a specified date period, optionally filtered by merchant IDs and payout IDs. Returns payout records each including id, status, amount, currency, merchant_id, date, wallet details (bank name, swift, beneficiary iban), and settlements_available. Required: period. Maximum 50 payouts per call. - **get_single_tap_payments_payout_by_id** — Retrieve a specific Tap payout by payout ID. Returns the payout record including id, status, amount, currency, merchant_id, date, and wallet details (bank name, swift, and beneficiary iban). Required: payouts. - **tap_payments_payout_download** — Download a specific Tap payout's data by payout ID. Returns the payout record including id, status, amount, currency, merchant_id, date, and wallet details (bank name, swift, and beneficiary iban). Required: payouts. - **create_a_tap_payments_payout_download** — Create a payout download report in Tap for one or more merchants, optionally filtered by specific payout IDs. Returns an opaque text/plain file download containing the requested payout data; the response is a file stream rather than a structured JSON payload. - **list_all_tap_payments_card** — List all saved cards for a Tap customer. Returns a collection of card objects, each including id, object, brand, exp_month, exp_year, last_four, first_six, name, funding, fingerprint, customer, scheme, address, and issuer. Required: customer_id. - **get_single_tap_payments_card_by_id** — Retrieve a specific saved card for a Tap customer by card id. Returns: id, object, brand, scheme, last4, last_four, first_six, exp_month, exp_year, name, funding, fingerprint, customer, address, address_line1, address_country, address_city, phone_number, address_zip, issuer. Required: customer_id, id. - **delete_a_tap_payments_card_by_id** — Delete a saved card for a Tap customer by card id. Returns the deleted card object including id, object, brand, exp_month, exp_year, last_four, name, funding, and fingerprint. Required: customer_id, id. - **create_a_tap_payments_card** — Verify and register a card in Tap using the card verification flow. Returns the resulting card object including id, object, brand, exp_month, exp_year, last_four, first_six, name, funding, fingerprint, customer, scheme, address, and issuer. Required: currency, customer. - **create_a_tap_payments_token** — Create a single-use payment token in Tap from raw card data, a saved card, or a network (scheme) token, usable as a source in Charges, Authorize, or Card API calls. Returns: id, object, client_ip, card. Tokens are single-use and valid for only a few minutes after creation. - **create_a_tap_payments_connect** — Create a Tap connect URL for a lead, initiating an onboarding flow that authenticates the lead and converts it to an account when all validation rules are met. Returns: scope, data, lead, board, redirect, post, webhook, interface. Required: scope, lead, redirect, post. - **tap_payments_connect_create_account** — Convert a Tap lead into a retailer account by submitting the lead ID. Returns: scope, data, lead, board, redirect, post, webhook, interface. Required: lead_id. - **create_a_tap_payments_connect_account** — Convert a lead to a retailer (connect account) in Tap by submitting a lead ID. The source documents a 200 OK response on success but does not enumerate the response body fields. Required: lead_id. - **create_a_tap_payments_lead** — Create a new lead in Tap. Returns the lead object including country, brand, entity, wallet, marketplace, and post. Required: country. - **update_a_tap_payments_lead_by_id** — Update a Tap lead for a retailer. Returns the updated lead object including country, brand, entity, wallet, marketplace, and post. Required: lead_id, country, brand, entity, wallet, marketplace. - **create_a_tap_payments_charge** — Create a charge in Tap against a payment source (token or source ID). Returns the created charge object including id, status, amount, currency, customer, card, transaction, reference, and payment_agreement. Required: amount, currency, source. - **list_all_tap_payments_charges** — List charges in Tap, optionally filtered by period, status, currency, customer, or other criteria. Returns a collection of charge records, each including id, status, amount, currency, customer, source, and payment_agreement. - **update_a_tap_payments_charge_by_id** — Update a Tap charge by id. Allows updating the description and metadata fields. Returns the updated charge object including id, status, amount, currency, description, metadata, customer, and card. Required: id. - **tap_payments_charges_download** — Download Tap charge records in bulk for a given period, merchant set, or filter criteria. Returns charge records including id, status, amount, currency, customer, source, and payment_agreement. - **create_a_tap_payments_refund** — Create a refund in Tap against an existing charge (full or partial). Returns the refund object including id, status, amount, currency, charge_id, reference, response, and transaction details. Required: charge_id, amount, currency. - **tap_payments_refunds_download** — Download refunds from Tap with optional filtering by merchant reference and metadata. Returns the refund object including id, status, amount, currency, charge_id, reference, gateway, and transaction details. - **create_a_tap_payments_business** — Create a new business in Tap. Returns the created business object including business_id, brand, entity, and user. Required: name, type, entity, brands. - **list_all_tap_payments_businesses** — List all businesses in Tap. Returns a collection of business records, each including business_id, brand, entity, and user details. - **list_all_tap_payments_destinations** — List all Tap destinations available for splitting payments with sub-merchants. Returns: id, amount, currency, charge_id, reason, post, metadata, reference. Max 50 per page. - **get_single_tap_payments_destination_by_id** — Get a single Tap destination by id. Returns: id, amount, currency, charge_id, reason, post, metadata, reference. Required: id. - **create_a_tap_payments_merchant** — Create a new merchant in Tap. Returns the created merchant object including display_name, business_id, business_entity_id, brand_id, branch_id, wallet_id, charge_currenices, bank_account, and settlement_by. - **list_all_tap_payments_merchants** — List merchants in Tap, optionally filtered by business and date period. Returns a collection of merchant objects including display_name, business_id, business_entity_id, brand_id, branch_id, wallet_id, charge_currenices, bank_account, and settlement_by. - **create_a_tap_payments_invoice** — Create a new invoice in Tap. Returns the created invoice object including id, draft, due, expiry, mode, description, customer, and order. Required: due, expiry, customer, order. - **list_all_tap_payments_invoices** — List invoices in Tap, optionally filtering by period, reference, or track status. Returns invoice records including id, draft, due, expiry, mode, customer, and order. - **update_a_tap_payments_invoice_by_id** — Update an existing invoice in Tap by id. Returns the updated invoice object including id, draft, due, expiry, mode, customer, and order. Required: id, due, expiry, customer, order. - **tap_payments_disputes_download** — Download dispute data from Tap for a specified date range and list of merchants. Returns a text/plain file (spreadsheet) containing dispute records for the requested period. Required: period. - **create_a_tap_payments_file** — Upload a file to the Tap server for use in merchant onboarding and document verification (e.g., identity documents, business logos, commercial registration). Returns the created file object including id, filename, purpose, size, title, type, url, and links. Required: file, purpose, title, file_link_create, expires_at. - **create_a_tap_payments_customer** — Create a new customer in Tap. Returns the created customer object including id, first_name, last_name, and email. - **list_all_tap_payments_customers** — List customers in Tap. Returns a paginated collection of customer records, each including id, first_name, last_name, email, and phone. - **get_single_tap_payments_customer_by_id** — Get a single Tap customer by id. Returns the customer object including id, first_name, last_name, email, and phone. Required: id. - **update_a_tap_payments_customer_by_id** — Update a Tap customer by id. Returns the updated customer object including id, first_name, last_name, email, and phone. Required: id. - **list_all_tap_payments_payouts** — List Tap payouts filtered by date period, merchants, or specific payout IDs. Returns a list envelope with object, live_mode, count, has_more, and a payouts array where each item contains id, status, date, amount, currency, merchant_id, wallet, and settlements_available. - **tap_payments_payouts_download** — Download Tap payouts filtered by payout ID or merchant. Returns a list envelope with object, live_mode, count, has_more, and a payouts array where each item contains id, status, date, amount, currency, merchant_id, wallet, and settlements_available. - **list_all_tap_payments_cards** — List all saved cards for a Tap customer. Returns card objects including id, object, brand, exp_month, exp_year, name, funding, fingerprint, last4, scheme, and issuer. Required: customer_id. - **get_single_tap_payments_card_by_id** — Retrieve a single saved card from a Tap customer's account by id. Returns the card object including id, object, brand, exp_month, exp_year, name, funding, fingerprint, last4, scheme, and issuer. Required: customer_id, id. - **delete_a_tap_payments_card_by_id** — Delete a saved card from a Tap customer's account by id. Returns the deleted card object including id, object, brand, exp_month, exp_year, name, last4, and funding. Required: customer_id, id. - **create_a_tap_payments_card** — Verify a card in Tap via 3D Secure, optionally saving it to a customer account. Returns the verified card object including id, object, brand, exp_month, exp_year, name, funding, fingerprint, last4, scheme, and issuer. - **create_a_tap_payments_token** — Create a single-use token in Tap that can be used in place of a payment source in the Charges or Authorize API. Supports card, encrypted card, saved card, Apple Pay, Samsung Pay, and scheme token types. Returns: id, saved_card, client_ip. Required inputs vary by token type: use type + token_data for Apple Pay, Samsung Pay, or scheme tokens; card for plain or encrypted card tokens; saved_card for… - **create_a_tap_payments_lead** — Create a new lead in Tap. Returns the created lead object including id, country, segment, brand, entity, wallet, marketplace, and post webhook URL. - **get_single_tap_payments_lead_by_id** — Get a single Tap lead by id. Returns the lead object including id, country, brand, entity, wallet, marketplace, and post webhook details. Required: id. - **update_a_tap_payments_lead_by_id** — Update a Tap lead by id. Returns the updated lead object including id, country, brand, entity, wallet, marketplace, and post webhook details. Required: id. ## How it works 1. **Link your customer's Tap Payments account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Tap Payments.** The Proxy API is a 1-to-1 mapping of the Tap Payments API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Offer localized MENA checkout to your merchants** — SaaS platforms serving GCC-based businesses can embed Tap Payments to instantly unlock local payment methods like mada, KNET, Benefit, and regional BNPLs (Tabby, Tamara) without building country-specific integrations themselves. - **Provision sub-merchant accounts inside your product** — Marketplaces and vertical SaaS platforms can onboard their end-users as Tap sub-merchants natively, capturing KYC documents and creating Connect accounts without sending users to an external portal. - **Power in-app payment analytics and reconciliation** — E-commerce and booking platforms can sync charges, refunds, disputes, and payouts into their own dashboards using Tap's async bulk download APIs, so merchants never need to leave the SaaS UI to reconcile revenue. - **Enable holds and pre-authorizations for appointment-based products** — Clinic, salon, hospitality, and rental SaaS platforms can reduce no-shows and chargebacks by placing card holds via Tap's authorize APIs, then capturing or releasing them based on booking outcomes. - **Automate B2B invoicing for regional merchants** — Accounting, CRM, and wholesale marketplace platforms can issue localized digital invoices to their users' customers and track lifecycle status (Draft → Due → Paid) directly inside their product. ## What you can build - **Embedded merchant onboarding with KYC** — Create leads, upload compliance documents, and convert verified leads into functioning Tap Connect sub-merchant accounts without leaving your product. - **White-labeled tokenized checkout** — Tokenize raw card and Apple Pay payloads via Tap's token API and finalize transactions through the charge API to keep your checkout PCI-safe and fully branded. - **Pre-authorization holds for bookings and rentals** — Place, update, and later capture or release card authorizations to secure appointments, reservations, or equipment rentals. - **Merchant revenue dashboard** — Sync charges, refunds, payouts, and disputes via Tap's async download APIs to render native sales, settlement, and chargeback dashboards inside your SaaS. - **Split payments for marketplaces** — Map vendors as merchants and destinations to route funds between the underlying supplier and your platform fee on every transaction. - **Automated invoice generation and tracking** — Create Tap invoices programmatically, update them as terms change, and list their status to surface payable links and paid receipts inside your product. ## FAQs ### How does authentication work when my users connect their Tap Payments account? Truto handles credential collection and secure storage for Tap Payments API keys on behalf of your end-users. Your product calls Truto's tools using a stable connection identifier, and Truto injects the correct auth headers when calling Tap — you never store or rotate merchant API keys yourself. ### Which Tap Payments operations are supported through Truto? The integration covers charges, authorizations, refunds, customers, cards, tokens, invoices, payouts, disputes, merchants, destinations, businesses, leads, files, and Connect account creation — including both transactional endpoints and the async bulk download endpoints for charges, refunds, payouts, and disputes. ### How do the asynchronous download APIs work for bulk historical data? Tap's download endpoints (e.g. for charges, payouts, refunds, disputes) are asynchronous — you trigger a download job via the create download tool, then poll the corresponding retrieval tool to fetch the results once ready. This is the recommended pattern for backfilling historical transaction data into your own database. ### Can I embed full merchant onboarding without sending users to Tap's portal? Yes. You can create a lead, attach KYC/KYB documents via the file upload tool, update the lead as verification progresses, and then create a Connect account — all through API calls, keeping your users inside your product throughout onboarding. ### Does the integration support marketplace-style split payments? Yes. You can create merchants, list and retrieve destinations, and reference them when creating charges so funds are routed between the underlying vendor and your platform fee within a single transaction flow. ### How do I keep transaction and payout data fresh in my product? For real-time updates, call the list and get tools for charges, payouts, and customers on demand or on a schedule that fits your product. For larger historical syncs, use the async download tools to pull bulk exports without hitting per-request pagination limits.