Skip to main content
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.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.

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.

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 for that path. Execute the transfer. Metal checks transaction admission, then executes the MIP20 call. Receive policy 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. 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

Account authority is a separate choice from the payment procedure. Use Create and manage a smart account 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 to test lost responses, duplicate events, and restoration before relying on the application’s payment records.