Create Your First Beneficiary

A beneficiary is created under a customer. The customer ID belongs in the URL, not in the JSON body. You need BENEFICIARIES_WRITE to create a beneficiary. Add BENEFICIARIES_READ if your integration reads the beneficiary back after creation.

Prepare the beneficiary payload

Use an active BIC known to Nuvera. Either iban or accountNumber must be present.

{
  "country": "<beneficiary-country-alpha-2>",
  "companyName": "Acme Supplier GmbH",
  "address": "Taunusanlage 12, Frankfurt",
  "zipCode": "60325",
  "currencyCode": "USD",
  "accountNumber": "1234567890",
  "bankBic": "<valid-bank-bic>"
}

Create the beneficiary under a customer

Generate the signed JWT with uri set to /api/v1/customers/{customerId}/beneficiaries after replacing {customerId} with the actual customer ID.

CUSTOMER_ID="<customer-id>"
BODY='{"country":"<beneficiary-country-alpha-2>","companyName":"Acme Supplier GmbH","address":"Taunusanlage 12, Frankfurt","zipCode":"60325","currencyCode":"USD","accountNumber":"1234567890","bankBic":"<valid-bank-bic>"}'
TOKEN="<signed-request-jwt>"

curl "https://rest-api.nuvera.global/api/v1/customers/$CUSTOMER_ID/beneficiaries" \
  -H "x-api-key: $NUVERA_API_KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  --data "$BODY"

Field notes

Field	Required?	Notes
`country`	Required	Beneficiary country as an ISO alpha-2 country code.
`companyName`	Required	Legal or business name of the beneficiary.
`address`	Required	Beneficiary address.
`zipCode`	Required	Postal code.
`currencyCode`	Required	Currently `USD`.
`bankBic`	Required	Active SWIFT/BIC known to Nuvera.
`iban`	Conditional	Required when `accountNumber` is not provided.
`accountNumber`	Conditional	Required when `iban` is not provided.
`wireRoutingNumber`	Optional	Add only when required for the payout rail.
`achRoutingNumber`	Optional	Add only when required for the payout rail.
`intermediaryBank`	Optional	Add only when required for the payout rail.

New beneficiaries enter review. Use GET /api/v1/customers/{customerId}/beneficiaries/{id} and the activity endpoint to track the record. For the complete schema, open the API Reference.

Getting Started

Partner API

Core Workflows

Operations

Create Your First Beneficiary

Field notes

​Field notes

Field notes