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.

account_id

string

The ID of the source account being debited.

entity_id

string

The ID of the entity that initiated the transfer.

counterparty_id

string

The ID of the recipient counterparty.

payment_detail_id

string

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

type

string

Always outflow for transfers initiated via the API.

currency

string

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

amount

number

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

applicable_fee

number

Fee charged for this transfer in the smallest currency unit.

status

string

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

status_reason

string

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

narration

string

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

unique_reference

string

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

meta

object

Arbitrary key-value metadata attached at creation.

created

number

Unix timestamp in milliseconds when the transfer was created.

updated

number

Unix timestamp in milliseconds when the transfer was last updated.

Example transfer object

{
  "id": "01K7H0QM421E9CB5M24W5AK3Q3",
  "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
  "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
  "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "payment_detail_id": "pd_01KM37FAABC123DEF456GHI789",
  "type": "outflow",
  "currency": "GBP",
  "amount": 10000,
  "applicable_fee": 50,
  "status": "pending",
  "status_reason": "awaiting_processing",
  "narration": "Invoice payment INV-2025-001",
  "unique_reference": "PAY-2025-001",
  "meta": {},
  "created": 1760434049154,
  "updated": 1760434050159
}

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.

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 /bank-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

account_id

string

required

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

payment_detail_id

string

required

The ID of the payment detail record. Returned by POST /counterparties/{counterparty_id}/payment-details.

amount

number

required

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

narration

string

required

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

unique_reference

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.

meta

object

Arbitrary key-value metadata. Values must be strings.

Request

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

Response

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

{
  "id": "01K7H0QM421E9CB5M24W5AK3Q3",
  "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
  "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
  "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "payment_detail_id": "pd_01KM37FAABC123DEF456GHI789",
  "type": "outflow",
  "currency": "GBP",
  "amount": 10000,
  "applicable_fee": 50,
  "status": "pending",
  "status_reason": "awaiting_processing",
  "narration": "Invoice payment INV-2025-001",
  "unique_reference": "PAY-2025-001",
  "meta": {},
  "created": 1760434049154,
  "updated": 1760434050159
}

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 /momo-transfers Initiates a payout to a mobile money wallet. Supports M-Pesa, MTN, Airtel, Orange, Wave, and Tigo.

Request parameters

account_id

string

required

The ID of the source account to debit.

payment_detail_id

string

required

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

amount

number

required

Amount in the smallest currency unit.

narration

string

required

Transfer description. Maximum 100 characters.

unique_reference

string

required

Idempotency key. Maximum 64 characters.

meta

object

Arbitrary key-value metadata. Values must be strings.

Request

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

Response

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

{
  "id": "01K7H2PNABC123DEF456GHI789",
  "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
  "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
  "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "payment_detail_id": "pd_01KM37FABCD456EFG789HIJ012",
  "type": "outflow",
  "currency": "KES",
  "amount": 150000,
  "applicable_fee": 0,
  "status": "pending",
  "status_reason": "awaiting_processing",
  "narration": "Freelancer payout April 2025",
  "unique_reference": "MOMO-2025-001",
  "meta": {},
  "created": 1760434049154,
  "updated": 1760434050159
}

Create a stablecoin transfer

POST /stablecoin-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

account_id

string

required

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

payment_detail_id

string

required

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

amount

number

required

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

narration

string

required

Transfer description. Maximum 100 characters.

unique_reference

string

required

Idempotency key. Maximum 64 characters.

meta

object

Arbitrary key-value metadata. Values must be strings.

Request

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

Response

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

{
  "id": "01K7H3QABC456DEF789GHI012",
  "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
  "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
  "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "payment_detail_id": "pd_01KM37FABCD789EFG012HIJ345",
  "type": "outflow",
  "currency": "USC",
  "amount": 100000000,
  "applicable_fee": 0,
  "status": "pending",
  "status_reason": "awaiting_processing",
  "narration": "Token distribution batch 3",
  "unique_reference": "STABLE-2025-001",
  "meta": {},
  "created": 1760434049154,
  "updated": 1760434050159
}

Get a transfer

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

Path parameters

transfer_id

string

required

The transfer ID.

Query parameters

entity_id

string

Required when authenticating with an API key.

Request

curl "https://api.nuvion.dev/transfers/01K7H0QM421E9CB5M24W5AK3Q3" \
  -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

entity_id

string

Filter by entity ID. Required when authenticating with an API key.

account_id

string

Filter by source account.

status

string

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

limit

integer

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

cursor

string

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

Request

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

Response

{
  "data": [
    {
      "id": "01K7H0QM421E9CB5M24W5AK3Q3",
      "account_id": "01K747KD7QW8KQS2GRD8MQBT55",
      "entity_id": "01K3HJAK85YJP13WJ41P3CWAVM",
      "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
      "payment_detail_id": "pd_01KM37FAABC123DEF456GHI789",
      "type": "outflow",
      "currency": "GBP",
      "amount": 10000,
      "applicable_fee": 50,
      "status": "successful",
      "status_reason": "processing_complete",
      "narration": "Invoice payment INV-2025-001",
      "unique_reference": "PAY-2025-001",
      "meta": {},
      "created": 1760434049154,
      "updated": 1760434050159
    }
  ],
  "meta": {
    "pagination": {
      "has_next": false,
      "has_previous": false,
      "next_cursor": null,
      "previous_cursor": null,
      "total_count": 1
    }
  }
}

API Reference

​The Transfer object

​Transfer statuses

​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

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