Payment Details

A payment detail stores the routing information for a single payment rail on a counterparty, such as a bank account, mobile money wallet, or stablecoin address. Create one before initiating a transfer on that rail.

The Payment Detail object

string

Unique payment detail identifier.

string

The payment rail. One of bank-transfer, momo-transfer, stablecoin-transfer, or book-transfer.

string

ISO 4217 currency code.

string

Full name of the payment recipient, as it appears on the receiving account.

string

The ID of the counterparty this payment detail belongs to.

string

The ID of the entity this payment detail is registered under.

string

ISO 3166-1 alpha-2 destination country code. Present for bank transfer rails; not required for mobile money.

string

The payment scheme used to route this payment detail. Values are rail-specific (e.g. fps for UK bank transfers, mpesa for Kenyan mobile money). See Send a Payout for the full list of schemes per rail.

object

Key-value metadata attached to the payment detail.

Additional fields are present depending on payment_method and scheme:

string

UK bank sort code. Present for fps.

string

Destination account number. Format varies by rail (e.g. a CLABE for mx_spei, an account number for fps/ach).

string

US bank routing number. Present for ach and wire.

string

US bank account type. One of checking or savings. Present for ach, wire, and rtp.

string

Canadian bank institution number. Present for eft.

string

Canadian bank transit number, identifying the recipient’s branch. Present for eft.

string

SWIFT/BIC code for the recipient’s bank. Present for swift and other international rails.

string

Name of the recipient’s bank.

object

Recipient bank’s postal address. Present for rails that require it (e.g. ach, wire, swift).

Show bank_address fields

string

Street address.

string

City.

string

State or province.

string

Postal code.

string

ISO 3166-1 alpha-2 country code.

string

Recipient’s mobile money wallet number, in E.164 format. Present for payment_method: "momo-transfer".

string

Destination blockchain wallet address. Present for payment_method: "stablecoin-transfer".

string

Blockchain network for wallet_address. One of ETH_MAINNET, SOLANA_MAINNET, BASE_MAINNET, or POLYGON_MAINNET. Present for payment_method: "stablecoin-transfer".

See Send a Payout for the complete set of required fields per rail, across all supported corridors.

Example

{
  "id": "01HXYZ0061ABCDEFGHJKMNPQRS",
  "payment_method": "bank-transfer",
  "currency": "GBP",
  "account_holder_name": "Jane Smith",
  "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
  "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
  "scheme": "fps",
  "account_number": "12345678",
  "country": "GB",
  "sort_code": "040004",
  "bank_name": "Barclays",
  "meta": {}
}

Add payment details

POST /payment-details Attach bank account, mobile money, stablecoin, or book transfer routing information to a counterparty. The returned payment detail ID is used when initiating transfers.

Request parameters

string

required

The payment rail. One of bank-transfer, momo-transfer, stablecoin-transfer, or book-transfer.

string

required

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

string

required

Full name of the payment recipient, as it appears on the receiving account.

string

The ID of the entity this payment detail is registered under. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

string

required

The ID of the recipient counterparty.

string

ISO 3166-1 alpha-2 destination country code. Required for all bank transfer rails and for mobile money.

string

Payment scheme. Required when the currency supports multiple rails. For USD, specify ach, wire, or rtp. See Send a Payout for the full list of schemes per rail.

object

Recipient bank’s postal address. Required for some rails (e.g. ach, wire, swift). See Send a Payout for the exact rails.

Show bank_address fields

string

Street address.

string

City.

string

State or province.

string

Postal code.

string

ISO 3166-1 alpha-2 country code.

object

Optional key-value metadata.

Request

curl -X POST https://api.nuvion.dev/payment-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "bank-transfer",
    "currency": "GBP",
    "country": "GB",
    "account_holder_name": "Jane Smith",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "sort_code": "040004",
    "account_number": "12345678",
    "bank_name": "Barclays"
  }'

curl -X POST https://api.nuvion.dev/payment-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "bank-transfer",
    "currency": "USD",
    "country": "US",
    "scheme": "ach",
    "account_holder_name": "Danielle Brooks",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "routing_number": "026009593",
    "account_number": "987654321012",
    "account_type": "checking",
    "bank_name": "Bank of America",
    "bank_address": {
      "line1": "100 Federal Street",
      "city": "Boston",
      "state": "MA",
      "postal_code": "02110",
      "country": "US"
    }
  }'

curl -X POST https://api.nuvion.dev/payment-details \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "momo-transfer",
    "currency": "KES",
    "account_holder_name": "John Smith",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "scheme": "mpesa",
    "phone_number": "+254712345678"
  }'

Response

Returns the created payment detail object.

Response

{
  "status": "success",
  "message": "Payment detail created successfully",
  "data": {
    "id": "01HXYZ0061ABCDEFGHJKMNPQRS",
    "payment_method": "bank-transfer",
    "currency": "GBP",
    "account_holder_name": "Jane Smith",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "scheme": "fps",
    "account_number": "12345678",
    "country": "GB",
    "sort_code": "040004",
    "bank_name": "Barclays"
  }
}

Retrieve payment details

GET /payment-details/{id} Retrieve a single payment detail by ID.

Path parameters

string

required

The ID of the payment detail to retrieve.

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 -X GET https://api.nuvion.dev/payment-details/01HXYZ0061ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

Returns the payment detail object.

Response

{
  "status": "success",
  "message": "Payment detail retrieved successfully",
  "data": {
    "id": "01HXYZ0061ABCDEFGHJKMNPQRS",
    "payment_method": "bank-transfer",
    "currency": "GBP",
    "account_holder_name": "Jane Smith",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "scheme": "fps",
    "account_number": "12345678",
    "country": "GB",
    "sort_code": "040004",
    "bank_name": "Barclays"
  }
}

Update payment details

PATCH /payment-details/{id} Updates an existing payment detail. Accepts the same fields as POST /payment-details; pass only the fields you want to change.

Path parameters

string

required

The ID of the payment detail to update.

Request parameters

string

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

Request

curl -X PATCH https://api.nuvion.dev/payment-details/01HXYZ0061ABCDEFGHJKMNPQRS \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_holder_name": "Jane E. Smith"
  }'

Response

Returns the updated payment detail object.

Response

{
  "status": "success",
  "message": "Payment detail updated successfully",
  "data": {
    "id": "01HXYZ0061ABCDEFGHJKMNPQRS",
    "payment_method": "bank-transfer",
    "currency": "GBP",
    "account_holder_name": "Jane E. Smith",
    "counterparty_id": "01HXYZ0062ABCDEFGHJKMNPQRS",
    "entity_id": "01HXYZ0063ABCDEFGHJKMNPQRS",
    "scheme": "fps",
    "account_number": "12345678",
    "country": "GB",
    "sort_code": "040004",
    "bank_name": "Barclays"
  }
}

See Send a Payout for the complete list of rail-specific required fields across all supported corridors.

​The Payment Detail object

​Add payment details

​Request parameters

​Request

​Response

​Retrieve payment details

​Path parameters

​Query parameters

​Request

​Response

​Update payment details

​Path parameters

​Request parameters

​Request

​Response

The Payment Detail object

Add payment details

Request parameters

Request

Response

Retrieve payment details

Path parameters

Query parameters

Request

Response

Update payment details

Path parameters

Request parameters

Request

Response