Payment Details

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, 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

required

The entity initiating the payout.

string

required

The ID of the recipient counterparty

string

ISO alpha-2 destination country code. Required for bank transfers.

string

Payment scheme. Required when the currency supports multiple rails. For USD, specify ach or wire. For GBP, fps or chaps.

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": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "sort_code": "040004",
    "account_number": "12345678"
  }'

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": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "routing_number": "026009593",
    "account_number": "987654321012",
    "account_type": "checking",
    "bank_name": "Bank of America"
  }'

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": "01KBCFY3VB1XT0MC8VMZXME6RS",
    "counterparty_id": "01KQESEEKSRKEKMACFX5H",
    "scheme": "mpesa",
    "phone_number": "+254712345678"
  }'

Response

{
  "id": "01KM37FAABC123DEF456GHI789",
  "payment_method": "bank-transfer",
  "currency": "GBP",
  "country": "GB",
  "scheme": "fps",
  "account_holder_name": "Jane Smith",
  "sort_code": "040004",
  "account_number": "12345678",
  "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
  "entity_id": "01KBCFY3VB1XT0MC8VMZXME6RS"
}

Retrieve Payment Details

To retrieve a payment detail, use the GET /payment-details/{id} endpoint with the payment detail ID returned from the POST /payment-details request.

curl -X GET https://api.nuvion.dev/payment-details/"01KM37FAABC123DEF456GHI789" \
  -H "Authorization: Bearer $NUVION_API_KEY"

{
    "status": "success",
    "message": "Payment detail retrieved successfully",
    "data": {
        "id": "01KM37FAABC123DEF456GHI789",
        "payment_method": "stablecoin-transfer",
        "currency": "USC",
        "account_holder_name": "Jane Smith",
        "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
        "entity_id": "01KCKRJJH6A3SJMAXBB737K5NP",
        "scheme": "stablecoin",
        "wallet_address": "0x9829203632188bAAe5C0BFDd362Fd6FDdD943B61",
        "country": "US",
        "blockchain_network": "ETH_MAINNET"
    }
}

Update Payment Details

To update a payment detail, use the PATCH /payment-details/{id} endpoint with the payment detail ID returned from the POST /payment-details request.

curl -X PATCH https://api.nuvion.dev/payment-details/01KM37FAABC123DEF456GHI789 \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty_id": "01KM37EZ0AYCVDXJ3WDHXPPSZ9",
    "bank_address": {
      "line1": "885 Teaneck Road",
      "city": "Teaneck",
      "state": "NJ",
      "country": "US",
      "postal_code": "07666"
    }
}'

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

​Add payment details

​Request parameters

​Request

​Response

​Retrieve Payment Details

​Update Payment Details

Add payment details

Request parameters

Request

Response

Retrieve Payment Details

Update Payment Details