> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metalntwx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Design a payment integration

> Place Metal transactions and payment verification within an existing payment system

> [!NOTE]
>
> **What you'll be able to do**
>
> * Map Metal's role within an existing PSP architecture.
> * Identify the application components to connect or extend.
> * Select the implementation guides for the integration.

For an invoice payment, the payment system records the customer's instruction
and identifies who owns the funds and who can authorize the transfer. Metal
executes the transfer and establishes consensus finality. The payment processor
verifies that result against the instruction before marking the invoice paid.

## Place the components

The diagram follows a direct MIP20 payment. The integrating organization owns the
application and chooses its signing arrangement. A customer wallet, an internal
signer, or a custody provider can supply the signature.

![The application authenticates and saves a payment instruction, obtains a signature and retains the transaction hash, then submits through RPC. Metal checks admission, executes the transfer and policy, and finalizes the block. The payment processor verifies the exact event against the saved instruction and checks finality before updating records.](https://mintlify.s3.us-west-1.amazonaws.com/nexus-ed339086/images/build/payment-integration.svg)

A direct MIP20 payment, read clockwise. The application matches the exact transfer to its saved instruction and checks block finality before recording the payment and updating the invoice or balance in one database transaction.

| Component | Application responsibility |
| - | - |
| Customer and payment system | Authenticate instructions, map customers to onchain identities, and decide the payment's business outcome |
| Signing system | Enforce who may authorize each transaction, protect keys, and support the required approvals and recovery |
| Transaction submitter | Select the network and gas token, coordinate transaction nonces for each signing account, save signed bytes where supported, and reconcile uncertain responses |
| Payment processor | Find relevant events, verify the expected outcome and finality, and apply each payment once |
| Operations | Monitor processing lag, retain recovery records, and test restart and restoration |

Metal does not infer an invoice, customer, or payment purpose from a transfer.
Keep personal information and the customer-to-address mapping in the
application. A token symbol is display information. Use the configured chain ID
and token contract address to identify an asset.

## Process an incoming payment

**Create the instruction.** Assign an immutable application ID to the payment
instruction and save its expected chain, token, sender, recipient, amount in
base units, and earliest acceptable block. Because ordinary transfers carry no
unique invoice ID, distinguish concurrent invoices using a separate receiving
address, a known transaction hash, or another unambiguous matching method.

**Authorize and submit.** The sender's application estimates the fee and obtains
the required signature. An internal signer can save the signed transaction and
its hash before broadcasting. A browser wallet may combine signing and broadcast,
which changes the information available after a lost response. Use
[Connect a browser wallet](https://docs.metalntwx.com/build/prepare/connect-a-browser-wallet.md) for that path.

**Execute the transfer.** Metal checks transaction admission, then executes the
MIP20 call. [Receive policy](https://docs.metalntwx.com/reference/compliance/receive-policy.md) can refuse a credit.
An ordinary transfer then reverts or, when configured, credits ReceivePolicy
quarantine. A refused capture from a MIP20 hold always credits quarantine. A
successful receipt records execution, so the payment processor must still match the exact
recipient transfer and verify the containing block's finality.

**Update the records.** Insert the verified event and update the invoice or
customer balance in one database transaction. A unique event key prevents replay
from applying the same payment again. If discovery stops during an outage,
resume from the last committed finalized-block cursor. Implement these steps in
[Best practices in processing payments](https://docs.metalntwx.com/build/payments/verify-and-reconcile-payments.md).

If funds enter quarantine, save the quarantine receipt and leave the invoice
unpaid. A transfer authorization or MIP20 hold can already be consumed, or a
shielded note spent. Preserve that state and reconcile recovery before authorizing
another payment. Deployment checks must establish that the documented policy behavior
is available on the selected network.

A recipient can receive an ordinary MIP20 transfer at an address. Add a send
policy contract to enforce spending approvals, or a routing contract to forward
funds, when the application needs those controls.

## Select a payment procedure

| Application task | Procedure and completion condition |
| - | - |
| Send from an application-controlled signer | [Direct payment](https://docs.metalntwx.com/build/payments/direct-payment.md), then verify the intended finalized transfer |
| Collect a sender's one-time transfer authorization | [Authorized payment](https://docs.metalntwx.com/build/payments/authorized-payment.md), checking the authorization nonce and replay protection |
| Set funds aside for later payment | [Payment from reserved funds](https://docs.metalntwx.com/build/payments/payment-from-reserved-funds.md), tracking captures and remaining MIP20 hold amounts |
| Require a private payment's recipient decision | [Shielded payment](https://docs.metalntwx.com/build/payments/shielded-payment.md), checking the resolution and its proof prerequisites |
| Route receipts through application rules | [Route incoming payments](https://docs.metalntwx.com/build/payments/route-incoming-payments.md), verifying all transfers needed for the destination outcome |
| Charge for individual API calls | [Offer Pay-per-Call Clearing](https://docs.metalntwx.com/agents/clearing.md), retaining accepted payment receipts and verifying batch finalization and required settlement |

Account authority is a separate choice from the payment procedure. Use
[Create and manage a smart account](https://docs.metalntwx.com/build/controls/create-and-manage-a-smart-account.md)
when one or several signers must authorize account calls. Choose custody and
administrator recovery before configuring that authority.

## Identify the next implementation work

For the selected payment, record the transaction signer, required approvals,
transaction submitter, signing account, and business completion condition.
List each public package, deployed contract, service, and proof artifact the
chosen procedure requires. An unavailable dependency remains an integration
blocker even when the contract interface is documented.

Implement one payment procedure and its durable processor. Use
[Monitor and recover your integration](https://docs.metalntwx.com/build/operations/monitor-and-recover-your-integration.md)
to test lost responses, duplicate events, and restoration before relying on the
application's payment records.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.