Pooled Pay-ins

Pooled pay-ins let customers send funds through shared receiving instructions. Swipelux uses payment references and transfer tracking to attribute each incoming payment to the right customer or wallet.

Pooled Pay-in Workflow

Integration Flow

1. Create and verify the customer.
2. Request the pooled rail when needed.
3. Create or choose a Swipelux custodial wallet for the destination balance.
4. Create a pay-in quote with that custodial wallet as to.
5. Execute the pay-in.
6. Track the transfer by ID or webhook.

Rail setup and quote execution use related but different values. Customer rail requests use qualified rail names such as fedwire_pooled or sepa_pooled. Pay-in quotes use the executable base rail such as fedwire, ach, sepa, swift, card, or apple_pay.

Before creating a bank-transfer, PIX, SPEI, PSE, or Transfers 3.0 pay-in quote, make sure the matching customer rail is ready_to_use. If it is missing or still under review, POST /v1/payin/quote returns 409 rail_not_ready with requiredRails, requestRailEndpoint, and nextAction.

Fiat bank-transfer pay-ins require the to wallet to be a Swipelux-created custodial wallet. Imported external wallets are valid for supported external wallet and on-chain recipient flows, but they are not general destinations for ACH, Fedwire, SEPA, SWIFT, PIX, SPEI, or PSE pay-in quotes.

When the final destination is an external wallet, use this sequence:

1. Create or use a custodial wallet for the customer.
2. Create and execute the fiat pay-in to that custodial wallet.
3. After settlement, move funds onward through the supported transfer or payout flow for the external destination.

For a USD Fedwire pay-in, request the pooled rail for the customer, wait until it is ready, then quote with from.rail: "fedwire":

{
  "to": "wal_abc123",
  "from": {
    "amount": "100",
    "currency": "USD",
    "rail": "fedwire"
  }
}

For a EUR SEPA pay-in, request sepa_pooled, then quote with from.rail: "sepa" and currency: "EUR".

Quotes expire. Execute POST /v1/payin with the quote id while it is valid; after expiry, request a new quote before showing instructions to the customer.

Store the id returned by POST /v1/payin and use it to reconcile transfer.* and payin.* webhook payloads. Core API webhooks use Swipelux object IDs for correlation; see Correlate Webhooks To API Requests.

Some SEPA pay-ins can include a Swipelux review marker while funds are being released from cold storage. If GET /v1/transfers/{id} returns attentionRequired: true with attentionReason set to sepa_release_pending or sepa_release_failed, keep using the normal transfer state and webhook events for your integration flow; the marker does not require a merchant-side API action.

Endpoint Sequence

POST /v1/customers/{customerId}/rails
GET /v1/customers/{customerId}/rails/{rail}
POST /v1/customers/{customerId}/wallets
POST /v1/payin/quote
POST /v1/payin
GET /v1/transfers/{id}

API Reference