Overview

The Penny API enables fiat-to-fiat transfers by allowing a sender to deposit funds into a Penny collection account and automatically triggering a payout to a registered recipient once the deposit is received and matched.

This flow is designed for B2B partners that require a compliant and auditable payment workflow where:

• A sender deposits fiat currency into Penny’s collection account
• Penny detects and matches the deposit
• Penny automatically pays out funds to the recipient’s registered bank account

This process does not require any cryptocurrency interaction. Funds are received, processed, and settled entirely through traditional banking rails.

Fiat-to-Fiat Transfer Flow

The fiat-to-fiat workflow consists of three required steps:

1. Register the recipient fiat account
2. Request a quote for the fiat corridor
3. Create a deposit order with metadata to enable automatic payout

Once the inbound deposit is received and matched, Penny automatically executes the payout to the registered recipient.

Step 1 — Register a Recipient Fiat Account

Before executing a fiat-to-fiat transfer, you must first register the recipient’s bank account using the Create Payment Method endpoint. This creates a unique fiatAccountId that represents the beneficiary.

The fiatAccountId is used as the canonical reference for payouts.

Why Registration Is Required

Registering the recipient account allows Penny to:

• Validate the payout rail and banking format
• Perform compliance and sanctions screening
• Standardize routing and payout execution
• Provide a consistent reference for future transactions

Required Information

When registering a recipient account, you typically provide:

• Recipient type (individual or business)

• Recipient identity information

• Bank account details (country specific)

  • Bank name
  • Account number / CLABE / CVU / IBAN
  • Routing or bank identifier
  • Account type (checking or savings)

• Recipient address information

• Optional metadata for internal reference

If your platform maintains its own beneficiary registry, it is recommended to store the returned fiatAccountId alongside your internal beneficiary record to avoid duplicate registrations.

Step 2 — Request a Fiat Corridor Quote

Once the recipient account is registered, the next step is to request a quote for the transfer corridor.

The quote establishes the pricing and execution terms for the transaction.

Why Quoting Is Required

Quotes define:

• The exchange rate
• Applicable fees
• The expected destination amount
• The validity window before the quote expires

Quotes may be:

• Indicative quotes (preview pricing)
• Firm quotes (short validity window with locked pricing)

The quote ID must be included when creating the deposit order.

Step 3 — Create a Deposit Order with Auto Offramp

After obtaining a valid quote, create a deposit order that generates instructions for the sender to deposit funds.

The deposit order links the inbound payment to the intended payout by including:

• quoteId
• destinationFiatAccountId
• autoOfframp.enabled = true

This allows Penny to automatically execute the payout once the inbound deposit is confirmed.

What the Deposit Order Provides

Creating the deposit order generates:

• Collection account details
• Unique deposit reference
• Deposit instructions for the sender

The sender must include the deposit reference when sending funds to ensure the payment can be correctly matched.

Deposit Matching and Automatic Payout

Once the deposit is received, Penny performs the following sequence:

1. Detect and match the inbound deposit
2. Confirm the funds have been received
3. Execute the FX conversion using the provided quoteId
4. Trigger the payout to the registered destinationFiatAccountId
5. Mark the transfer as completed

This deposit-to-payout sequence represents the canonical fiat-to-fiat settlement workflow.

Webhooks (Recommended)

To track the lifecycle of a fiat-to-fiat transfer, partners should subscribe to webhook events.

Recommended Webhook Events

Example Event: FIAT_DEPOSIT_RECEIVED

{
  "eventType": "FIAT_DEPOSIT_RECEIVED",
  "timestamp": "2026-01-15T19:02:11Z",
  "data": {
    "onrampId": "or_01HZX33B2A3G7Z0KXKQ9Y7D5V1",
    "sourceAmount": "50000.00",
    "sourceCurrency": "MXN",
    "senderName": "Empresa ABC SA de CV",
    "senderBankName": "BBVA México",
    "reference": "ALF-OR-01HZX33B2A3G7Z0KXKQ9Y7D5V1"
  }
}

Transfer Status Model

A fiat-to-fiat transfer moves through the following lifecycle states:

Common Failure Scenarios

Deposit Mismatch

Cause: Incorrect amount or missing reference.

Outcome: Deposit cannot be automatically matched.

Resolution: Manual investigation may be required.

Invalid or Inactive Fiat Account

Cause: Recipient account is invalid or not active.

Outcome: Payout cannot be executed.

Resolution: Register a valid fiatAccountId.

Quote Expired

Cause: Deposit arrives after the quote expiration window.

Outcome: FX execution cannot proceed.

Resolution: Request a new quote and recreate the deposit order.

Compliance Hold

Cause: Compliance review triggered due to corridor rules or transaction limits.

Outcome: Transfer processing is paused.

Resolution: Provide requested documentation or information to resume processing.

Summary

A fiat-to-fiat transfer using the Penny API requires three primary steps:

1. Register the recipient fiat account Create a fiatAccountId representing the beneficiary bank account.

2. Request a quote Lock the FX corridor terms and fees.

3. Create a deposit order with auto offramp enabled Generate deposit instructions and automatically execute the payout once funds are received.

This workflow enables partners to process compliant bank-to-bank transfers through the Penny API while maintaining full traceability and automated settlement.