Transfers - Nuvion

A transfer is a debit instruction from an entity’s account to a counterparty’s payment details. All transfers are asynchronous: the response reflects the initial queued state, and status updates are delivered via webhooks.

The Transfer object

string

Unique transfer identifier.

string

The ID of the source account being debited.

string

The ID of the entity that initiated the transfer.

string

The ID of the recipient counterparty.

string

The ID of the payment detail record used to route this transfer.

string

Always outflow for transfers initiated via the API.

string

ISO 4217 currency code (e.g. USD, GBP, EUR). Use USC for USDC and UST for USDT.

number

Transfer amount in the smallest currency unit. 10000 = $100.00 USD or £100.00 GBP.

number

Fee charged for this transfer in the smallest currency unit.

string

Transfer status. One of pending, processing, successful, failed, or reversed.

string

Human-readable description of the current status. For failures, indicates the cause, e.g. insufficient_funds, invalid_account_details, compliance_hold.

string

The payment type used for this transfer. One of bank-transfer, momo-transfer, stablecoin-transfer, or book-transfer.

string

Transfer description passed to the recipient’s bank statement where supported.

string

The idempotency key provided at creation. Used to identify and deduplicate transfers.

object

Arbitrary key-value metadata attached at creation.

number

Unix timestamp in milliseconds when the transfer was created.

number

Unix timestamp in milliseconds when the transfer was last updated.

Example transfer object

{
    "status": "success",
    "message": "Transfer created successfully",
    "data": {
        "id": "01HXYZ0060ABCDEFGHJKMNPQRS",
        "amount": 10000,
        "currency": "GBP",
        "unique_reference": "PAY-2025-001",
        "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
        "account_id": "01HXYZ0064ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
        "status": "pending",
        "status_reason": "awaiting_processing",
        "narration": "Invoice payment INV-2025-001",
        "type": "outflow",
        "payment_type": "bank-transfer",
        "applicable_fee": 50,
        "meta": {},
        "created": 1787415765559,
        "updated": 1787415765559
    }
}

Transfer statuses

Status	Description
`pending`	Transfer created and queued for processing.
`processing`	Being executed by the payment network.
`successful`	Delivered to the recipient.
`failed`	Could not be completed. Check `status_reason` for the cause.
`reversed`	Completed transfer was subsequently reversed.

Payment Types

Type	Description
`bank-transfer`	Initiates a payout to a counterparty via a bank transfer rail (FPS, SEPA, ACH, Wire, SWIFT, and others)
`momo-transfer`	Initiates a payout to a mobile money wallet. Supports M-Pesa, MTN, Airtel, Orange, Wave, and Tigo
`stablecoin-transfer`	Send USDC or USDT to an external wallet address
`book-transfer`	Book a transfer

Subscribe to outflows.created, outflows.completed, outflows.failed, and outflows.cancelled webhooks to track transfers in real time. See Event types.

Create a bank transfer

POST /transfers Initiates a payout to a counterparty via a bank transfer rail (FPS, SEPA, ACH, Wire, SWIFT, and others). The payment method and routing scheme are derived from the payment detail record.

Request parameters

string

required

The ID of the source account to debit. The account must have sufficient available balance.

string

required

The ID of the payment detail record. Returned by POST /payment-details.

string

required

The ID of the recipient counterparty. Returned by POST /counterparties.

string

required

ISO 4217 currency code for the transfer. e.g. GBP, USD, NGN.

number

required

Amount to send in the smallest currency unit. 10000 = $100.00 USD or £100.00 GBP.

string

required

The payment type of the transfer. It can be bank-transfer, momo-transfer, stablecoin-transfer, and book-transfer.

string

required

Transfer description. Passed to the recipient’s bank statement where the rail supports it. Maximum 100 characters.

string

required

Idempotency key. If a transfer with this reference already exists for the account, the original transfer is returned rather than creating a duplicate. Maximum 64 characters.

string

The ID of an FX quote from POST /fx-quotes. Required when the source account currency differs from the transfer currency.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

object

Arbitrary key-value metadata. Values must be strings.

Request

curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01HXYZ0065ABCDEFGHJKMNPQRS",
    "payment_detail_id": "01HXYZ0066ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0067ABCDEFGHJKMNPQRS",
    "amount": 10000,
    "currency": "GBP",
    "narration": "Invoice payment INV-2025-001",
    "payment_type": "bank-transfer",
    "unique_reference": "PAY-2025-001"
  }'

curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01HXYZ0064ABCDEFGHJKMNPQRS",
    "payment_detail_id": "01HXYZ0061ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "amount": 50000,
    "currency": "USD",
    "narration": "Contractor payment May 2025",
    "payment_type": "bank-transfer",
    "unique_reference": "PAY-2025-002"
  }'

Response

Returns the created transfer object with status: "pending".

{
    "status": "success",
    "message": "Transfer created successfully",
    "data": {
        "id": "01HXYZ0060ABCDEFGHJKMNPQRS",
        "amount": 50000,
        "currency": "USD",
        "unique_reference": "PAY-2025-002",
        "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
        "account_id": "01HXYZ0064ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
        "status": "pending",
        "status_reason": "awaiting_processing",
        "narration": "Contractor payment May 2025",
        "type": "outflow",
        "payment_type": "bank-transfer",
        "applicable_fee": 50,
        "meta": {},
        "created": 1787415765559,
        "updated": 1787415765559
    }
}

Errors

Code	Description
`422`	Validation error: a required field is missing or invalid.
`422`	Insufficient funds in the source account.
`404`	The `account_id` or `payment_detail_id` was not found.
`409`	A transfer with this `unique_reference` already exists. Returns the original transfer.

Create a mobile money transfer

POST /transfers Initiates a payout to a mobile money wallet. Supports M-Pesa, MTN, Airtel, Orange, Wave, and Tigo.

Request parameters

string

required

The ID of the source account to debit.

string

required

The ID of the payment detail record with payment_method: "momo-transfer".

string

required

The ID of the recipient counterparty.

number

required

Amount in the smallest currency unit.

string

required

ISO 4217 currency code for the transfer.

string

required

The payment type of the transfer. It can be bank-transfer, momo-transfer, stablecoin-transfer, and book-transfer.

string

required

Transfer description. Maximum 100 characters.

string

required

Idempotency key. Maximum 64 characters.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

object

Arbitrary key-value metadata. Values must be strings.

Request

curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01HXYZ0065ABCDEFGHJKMNPQRS",
    "payment_detail_id": "01HXYZ0068ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0069ABCDEFGHJKMNPQRS",
    "amount": 150000,
    "currency": "TZS",
    "narration": "Freelancer payout April 2025",
    "payment_type": "momo-transfer",
    "unique_reference": "MOMO-2025-001"
  }'

Response

Returns the created transfer object with status: "pending".

{
    "status": "success",
    "message": "Transfer created successfully",
    "data": {
        "id": "01HXYZ0070ABCDEFGHJKMNPQRS",
        "amount": 150000,
        "currency": "TZS",
        "unique_reference": "MOMO-2025-001",
        "counterparty_id": "01HXYZ0069ABCDEFGHJKMNPQRS",
        "account_id": "01HXYZ0071ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "status": "pending",
        "status_reason": "awaiting_processing",
        "narration": "Freelancer payout April 2025",
        "type": "outflow",
        "payment_type": "momo-transfer",
        "applicable_fee": 1,
        "meta": {},
        "created": 1787424785925,
        "updated": 1787424788386
    }
}

Create a stablecoin transfer

POST /transfers Initiates a stablecoin send to an on-chain wallet address. Supports USDC (USC) and USDT (UST) on Ethereum, Solana, Base, and Polygon.

Request parameters

string

required

The ID of the source account to debit. Must hold a stablecoin balance (USC or UST).

string

required

The ID of the payment detail record with payment_method: "stablecoin-transfer".

string

required

The ID of the recipient counterparty.

number

required

Amount in the smallest stablecoin unit. 100000000 = 100.00 USDC.

string

required

ISO 4217 currency code for the transfer.

string

required

Transfer description. Maximum 100 characters.

string

required

The payment type of the transfer. It can be bank-transfer, momo-transfer, stablecoin-transfer, and book-transfer.

string

required

Idempotency key. Maximum 64 characters.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

object

Arbitrary key-value metadata. Values must be strings.

Request

curl -X POST https://api.nuvion.dev/transfers \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01HXYZ0065ABCDEFGHJKMNPQRS",
    "payment_detail_id": "01HXYZ0068ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0072ABCDEFGHJKMNPQRS",
    "amount": 100000000,
    "currency": "USC",
    "narration": "Token distribution batch 3",
    "payment_type": "stablecoin-transfer",
    "unique_reference": "STABLE-2025-001"
  }'

Response

Returns the created transfer object with status: "pending".

{
    "status": "success",
    "message": "Transfer created successfully",
    "data": {
        "id": "01HXYZ0073ABCDEFGHJKMNPQRS",
        "amount": 100000000,
        "currency": "USC",
        "unique_reference": "STABLE-2025-001",
        "counterparty_id": "01HXYZ0072ABCDEFGHJKMNPQRS",
        "account_id": "01HXYZ0065ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ1234ABCDEFGHJKMNPQRS",
        "status": "pending",
        "status_reason": "Transaction created successfully",
        "narration": "Token distribution batch 3",
        "type": "outflow",
        "payment_type": "stablecoin-transfer",
        "applicable_fee": 1,
        "meta": {},
        "created": 1787427193358,
        "updated": 1787427195256
    }
}

Get a transfer

GET /transfers/{transfer_id} Retrieves a single transfer by ID.

Path parameters

string

required

The transfer ID.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl "https://api.nuvion.dev/transfers/01HXYZ0079ABCDEFGHJKMNPQRS" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

Returns the Transfer object.

List transfers

GET /transfers Returns a paginated list of transfers for an entity or account.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

Filter by source account.

string

Filter by status. One of pending, processing, successful, failed, or reversed.

integer

Number of results to return. Between 1 and 100. Defaults to 20.

string

Pagination cursor from a previous response. Omit for the first page.

Request

curl "https://api.nuvion.dev/transfers?entity_id=01HXYZ0077ABCDEFGHJKMNPQRS&status=successful&limit=20" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

{
    "status": "success",
    "message": "Transfers retrieved successfully",
    "data": {
        "data": [
            {
                "id": "01HXYZ0074ABCDEFGHJKMNPQRS",
                "amount": 7563879,
                "currency": "GBP",
                "unique_reference": "a0c75339-c41c-490e-9ee7-f92e202a3a3b",
                "counterparty_id": "01HXYZ0075ABCDEFGHJKMNPQRS",
                "account_id": "01HXYZ0076ABCDEFGHJKMNPQRS",
                "entity_id": "01HXYZ0077ABCDEFGHJKMNPQRS",
                "status": "successful",
                "status_reason": "processing_complete",
                "narration": "Test Funding",
                "type": "outflow",
                "payment_type": "book-transfer",
                "applicable_fee": 0,
                "meta": {
                    "fx_quote_id": "01HXYZ0078ABCDEFGHJKMNPQRS",
                    "provider_reference": null
                },
                "created": 1787070779824,
                "updated": 1787070781112
            }
        ],
        "meta": {
            "pagination": {
                "order": "desc",
                "has_next": true,
                "limit": 1,
                "has_previous": false,
                "next_cursor": "01HXYZ0074ABCDEFGHJKMNPQRS",
                "previous_cursor": null
            },
            "filters_applied": {
                "entity_id": "01HXYZ0077ABCDEFGHJKMNPQRS",
                "status": "successful",
                "sort": {
                    "field": "created",
                    "order": "desc"
                }
            }
        }
    }
}

​The Transfer object

​Transfer statuses

​Payment Types

​Create a bank transfer

​Request parameters

​Request

​Response

​Errors

​Create a mobile money transfer

​Request parameters

​Request

​Response

​Create a stablecoin transfer

​Request parameters

​Request

​Response

​Get a transfer

​Path parameters

​Query parameters

​Request

​Response

​List transfers

​Query parameters

​Request

​Response

The Transfer object

Transfer statuses

Payment Types

Create a bank transfer

Request parameters

Request

Response

Errors

Create a mobile money transfer

Request parameters

Request

Response

Create a stablecoin transfer

Request parameters

Request

Response

Get a transfer

Path parameters

Query parameters

Request

Response

List transfers

Query parameters

Request

Response