Nium Platforms — Complete Documentation

This guide demonstrates how clients and platforms leverage Nium's pre-built forms to manage beneficiary/recipient payouts and tax information at scale. Using Nium, a platform operates a centralized system and uses Nium-hosted forms to onboard beneficiaries/recipients for payments and tax compliance.

Each client entity represents a single customer (a customer) with a unique customerHashId. Beneficiaries/recipients complete Nium's pre-built Payment and Tax forms and become beneficiaries under the client to receive payouts. The client handles tax filing on behalf of its beneficiaries/recipients.

A tax-filing entity (identified by filerHashId) must be registered for each client before beneficiary/recipient tax information can be collected.

Filer Section

After client onboarding and customer creation, a filer record is required so the client can file taxes for beneficiaries/recipients.

Create a Filer

Endpoint: POST https://gateway.nium.com/api/v1/client/{clientHashId}/filers

Required Parameters:

Field	Type	Description
`customerHashId`	string (UUID)	Unique identifier for the customer provided by Nium
`name`	string	Filer's name
`address`	object	Filer's address details
`address.type`	enum	Either `mailing` or `residence`
`address.line1`	string	Street address line 1
`address.line2`	string	Street address line 2 (optional)
`address.city`	string	City name
`address.state`	string	State/province (2-letter ISO)
`address.countryCode`	string	Country (2-letter ISO)
`address.postalCode`	string	Postal/ZIP code
`taxResidentCountryCode`	string	Country where the filer is tax resident
`tin`	object	Taxpayer Identification Number details
`tin.number`	string	TIN value
`tin.type`	enum	`ssn`, `ein`, `itin`, or `atin`
`contact`	object	Primary contact information
`contact.name`	string	Contact's full name
`contact.departmentTitle`	string	Contact's department/title
`contact.phoneNumber`	object	Phone number object
`contact.phoneNumber.number`	string	Phone number (without country code)
`contact.phoneNumber.countryCode`	string	Country code (2-letter ISO)
`paymentSettlementEntity`	enum	`PAYMENT_SETTLEMENT_ENTITY` or `ELECTRONIC_PAYMENT_FACILITATOR_OR_OTHER_THIRD_PARTY` (optional)
`paymentCardThirdPartyNetwork`	enum	`PAYMENT_CARD_TRANSACTIONS` or `THIRD_PARTY_NETWORK_TRANSACTIONS` (optional)
`pseName`	string	Payment Settlement Entity name (optional)
`pseTelephoneNumber`	object	PSE phone number (optional)
`giin`	string	Global Intermediary Identification Number (optional)
`ch3Status`	enum	FATCA Chapter 3 status (optional)
`ch4Status`	enum	FATCA Chapter 4 status (optional)

Example Request:

curl --request POST "https://gateway.nium.com/api/v1/client/{clientHashId}/filers" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: YOUR_SECRET_TOKEN" \
  --data '{
    "taxResidentCountryCode": "us",
    "name": "Acme Corp",
    "address": {
      "type": "residence",
      "line1": "123 Main St",
      "line2": "Suite 100",
      "city": "San Francisco",
      "state": "CA",
      "countryCode": "us",
      "postalCode": "94560"
    },
    "customerHashId": "07b1f5a4-3934-418e-bdd3-069d49ff0932",
    "tin": {
      "number": "123456780",
      "type": "ein"
    },
    "contact": {
      "phoneNumber": {
        "number": "4809427111",
        "countryCode": "us"
      },
      "name": "Jeff Grail",
      "departmentTitle": "Tax Department"
    }
  }'

Example Response:

{
  "taxResidentCountryCode": "us",
  "name": "Acme Corp",
  "address": {
    "type": "residence",
    "line1": "*****",
    "line2": "*****",
    "city": "San Francisco",
    "state": "*****",
    "countryCode": "us",
    "postalCode": "*****"
  },
  "customerHashId": "07b1f5a4-3934-418e-bdd3-069d49ff0932",
  "clientHashId": "6ee6b2d6-2613-41f0-a961-a9791862b3e4",
  "tin": {
    "number": "*****6780",
    "type": "ein"
  },
  "contact": {
    "phoneNumber": {
      "number": "******7111",
      "countryCode": "us"
    },
    "name": "Jeff Grail",
    "departmentTitle": "Tax Department"
  },
  "paymentSettlementEntity": "ELECTRONIC_PAYMENT_FACILITATOR_OR_OTHER_THIRD_PARTY",
  "paymentCardThirdPartyNetwork": "THIRD_PARTY_NETWORK_TRANSACTIONS",
  "pseName": "Acme Corp",
  "pseTelephoneNumber": {
    "number": "******7111",
    "countryCode": "us"
  },
  "filerHashId": "4a7aeb8c-46f5-496f-9470-28d95f21d95b",
  "status": "active"
}

Fetch Filer

Endpoint: GET https://gateway.nium.com/api/v1/client/{clientHashId}/filers/{filerHashId}

Example Request:

curl --request GET "https://gateway.nium.com/api/v1/client/{clientHashId}/filers/{filerHashId}" \
  --header "X-Api-Key: YOUR_SECRET_TOKEN"

Example Response:

{
  "taxResidentCountryCode": "us",
  "name": "Example Platform Client LLC",
  "address": {
    "type": "residence",
    "line1": "*****",
    "line2": "*****",
    "city": "Newark",
    "state": "*****",
    "countryCode": "us",
    "postalCode": "*****"
  },
  "customerHashId": "336b44a0-afad-496f-b2c8-67af9a78ec40",
  "tin": {
    "number": "*****6780",
    "type": "ein"
  },
  "contact": {
    "phoneNumber": {
      "number": "******7890",
      "countryCode": "us"
    },
    "name": "Jeff Grail",
    "departmentTitle": "Tax Department"
  },
  "paymentSettlementEntity": "ELECTRONIC_PAYMENT_FACILITATOR_OR_OTHER_THIRD_PARTY",
  "paymentCardThirdPartyNetwork": "THIRD_PARTY_NETWORK_TRANSACTIONS",
  "pseName": "Example Platform Client LLC",
  "pseTelephoneNumber": {
    "number": "xxxxxx7890",
    "countryCode": "us"
  },
  "filerHashId": "3ac6548d-fc13-4d7e-abc1-bcdd32e1d694",
  "status": "active"
}

Required Forms

Beneficiaries/recipients must complete forms in a specific order because subsequent forms depend on earlier submissions:

Payment Form: Collects payment details first to create a beneficiary for the beneficiary/recipient in Nium
Tax Form: Collects tax information and links it to the beneficiary's previously created beneficiary record

The Payment form must be completed first. Until a beneficiary record exists, tax information cannot be collected.

Note: Identity verification for clients is completed at the customer level and is not part of the beneficiary/recipient-facing experience.

Payment and Tax Forms

Endpoint: POST https://gateway.nium.com/api/v1/client/{clientHashId}/prebuilt-forms-init

Request Parameters

Field	Type	Condition	Description
`modules`	array-string	Required	Modules to initiate. Supported values: `identity`, `tax`, `payment`
`referenceId`	string	Required	Unique identifier for the user in your system
`userDetails`	object	Required	Details of the onboarding user
`userDetails.name`	string	Required	Full name
`userDetails.email`	string	Required	Email address
`userDetails.mobile`	string	Optional	Mobile number
`userDetails.address`	object	Optional	Address details
`userDetails.address.type`	enum	Optional	`mailing` or `residence`
`userDetails.address.line1`	string	Optional	Street address line 1
`userDetails.address.line2`	string	Optional	Street address line 2
`userDetails.address.city`	string	Optional	City
`userDetails.address.state`	string	Optional	State/province (2-letter ISO)
`userDetails.address.countryCode`	string	Optional	Country (2-letter ISO)
`userDetails.address.postalCode`	string	Optional	Postal/ZIP code
`userDetails.entityType`	enum	Required	`individual` or `business`
`customerHashId`	string (UUID)	Conditional	Required if customer acts as remitter
`clientSecret`	string (UUID)	Required	Client secret used to authenticate the request. Keep this secure
`redirectUris`	object	Required	Redirect URLs for handling outcomes
`redirectUris.success`	string	Required	Redirect URL after successful completion
`redirectUris.cancel`	string	Required	Redirect URL if user cancels
`redirectUris.refresh`	string	Required	Redirect URL if session expires

Form Requirements

Payment Form

Prerequisites:

Client must be onboarded in Nium with customerHashId
Required beneficiary/recipient details: referenceId, name, email, entityType

What it does:

Collects the beneficiary/recipient's bank account or payment card information
Creates the beneficiary/recipient as a beneficiary in Nium
Creates a payment account for the beneficiary/recipient

When to use:

Adding new payment method for beneficiary/recipient
Updating existing payment information
Required before Tax form can be used

Tax Form

Prerequisites:

Client must be onboarded with customerHashId
Tax-filing entity must exist for client (filerHashId)
Beneficiary/recipient must already exist as beneficiary (Payment form completed)
Required beneficiary/recipient details: referenceId, name, email, entityType

What it does:

Collects tax information from the beneficiary/recipient (for example, W-9 for US persons or W-8 for non-US persons)
Links tax information to beneficiary/recipient's existing beneficiary record
Records client as tax filer for beneficiary/recipient

When to use:

Collecting tax information from newly onboarded beneficiary/recipient
Updating expired or incorrect tax details
Annual tax form renewals

Note: Tax form cannot be used until Payment form completed. If no beneficiary exists, tax flow fails.

Request Examples

Payment Form

This example starts a Nium-hosted Payment form session to collect beneficiary/recipient payment details and create a beneficiary.

Request:

curl --request POST "https://gateway.nium.com/api/v1/client/{clientHashId}/prebuilt-forms-init" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: YOUR_CLIENT_API_KEY" \
  --data '{
    "clientSecret": YOUR_CLIENT_SECRET,
    "modules": ["payment"],
    "referenceId": "c1deabfd2787cac3ab2c17c21c9e7462843ab493ed7e99b39dd241b3b6db4c8e",
    "userDetails": {
        "name": "John Smith",
        "email": "john.smith@acme.com",
        "entityType": "individual",
        "mobile": "+14155551234"
    },
    "customerHashId": "4b0d6416-96cf-4806-876f-c7d89ca7c52a",
    "redirectUris": {
        "success": "http://localhost:3002/platform/success",
        "cancel": "http://localhost:3002/platform/cancel",
        "refresh": "http://localhost:3002/platform/refresh"
    }
  }'

Response:

{
    "status": "SUCCESS",
    "sessionId": "25f82bda-d630-4b27-91e0-e99eaa9754f4",
    "redirectUrl": "https://onboard.sandbox.nium.com?code=25f82bda-d630-4b27-91e0-e99eaa9754f4",
    "expiresInSeconds": 30,
    "error": null
}

Tax Form

This example starts a Nium-hosted Tax form session for beneficiary/recipient who completed Payment form.

Request:

curl --request POST "https://gateway.nium.com/api/v1/client/{clientHashId}/prebuilt-forms-init" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: YOUR_CLIENT_API_KEY" \
  --data '{
    "clientSecret": YOUR_CLIENT_SECRET,
    "modules": ["tax"],
    "referenceId": "c1deabfd2787cac3ab2c17c21c9e7462843ab493ed7e99b39dd241b3b6db4c8e",
    "userDetails": {
        "name": "John Smith",
        "email": "john.smith@acme.com",
        "entityType": "individual",
        "mobile": "+14155551234"
    },
    "customerHashId": "4b0d6416-96cf-4806-876f-c7d89ca7c52a",
    "redirectUris": {
        "success": "http://localhost:3002/platform/success",
        "cancel": "http://localhost:3002/platform/cancel",
        "refresh": "http://localhost:3002/platform/refresh"
    }
  }'

Response:

{
    "status": "SUCCESS",
    "sessionId": "3060f802-535c-444b-853d-6fabf540e833",
    "redirectUrl": "https://onboard-qa.nium.com?code=3060f802-535c-444b-853d-6fabf540e833",
    "expiresInSeconds": 30,
    "error": null
}

Response Fields:

Field	Description
`sessionId`	One-time session code used to launch the hosted form (expires after 30 seconds)
`expiresIn`	Time in seconds before session expires

After successful response, redirect beneficiary/recipient to: https://hosted-forms.nium.com/{module}?code={sessionId}

Error Response:

{
  "status": "ERROR",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Error Codes

Code	Description	Next Steps
`CLIENT_NOT_FOUND`	The `clientHashId` does not match active Nium client	Confirm correct `clientHashId`. Contact Nium Support if issue persists
`INVALID_CREDENTIALS`	The `clientSecret` doesn't match provided `clientHashId`	Verify correct `clientSecret` is configured
`CLIENT_INACTIVE`	Client account is disabled and cannot create sessions	Contact Nium Support to review or restore account
`MODULE_NOT_ALLOWED`	One or more requested forms not enabled for client	Confirm which forms enabled with Nium Support
`INVALID_SCOPE`	One or more `scope` field values unsupported	Use only: `"identity"`, `"payment"` or `"tax"`
`CUSTOMER_NOT_FOUND`	The `customerHashId` doesn't exist or not accessible	Verify correct `customerHashId` provided
`BENEFICIARY_REQUIRED`	Tax form requested before `beneficiary` created	Complete Payment form before Tax form
`SESSION_NOT_FOUND`	Session code invalid or expired	Create new session and restart flow
`SESSION_ALREADY_USED`	Session already completed and cannot be reused	Create new session to continue

User Flow

Payment Form Flow

Client selects beneficiary/recipient from internal system
Client backend starts Payment form session using /api/v1/init with scope: ["payment"] including beneficiary/recipient name & email
Beneficiary/recipient redirected to Nium-hosted Payment form
Beneficiary/recipient enters payment details (bank account or card)
Nium creates beneficiary record and payment account for beneficiary/recipient
Beneficiary/recipient redirected to client success page

Tax Form Flow

Client selects beneficiary/recipient from internal system
Client backend starts Tax form session using /api/v1/init with scope: ["tax"] including beneficiary/recipient name and email
- Backend confirms client set up to file taxes
- Backend confirms beneficiary/recipient exists as beneficiary (Payment form completed)
Beneficiary/recipient redirected to Nium-hosted Tax form
Beneficiary/recipient completes required tax form (W-9 or W-8)
Nium links tax information to beneficiary/recipient's existing beneficiary record
Beneficiary/recipient redirected to client success page

Retrieving Payment Account IDs

After a beneficiary/recipient completes the Payment form and creates a payment account, you can retrieve the paymentAccountId using the following API endpoints.

List All Beneficiaries

Retrieve all beneficiaries under a customer:

curl --location 'https://gateway.nium.com/api/v3/client/{clientHashId}/customer/{customerHashId}/beneficiaries' \
--header 'x-api-key: ********'

Response includes: List of all beneficiaries with their beneficiaryHashId

{
    "beneficiaries": [
        {
            "id": "4d3db693-68dc-49c7-a1a6-ebb3c06111dd",
            "customerHashId": "07b1f5a4-3934-418e-bdd3-069d49ff0932",
            "name": "Taylor Swift",
            "entityType": "individual",
            "email": {
                "value": "t*****@music.com",
                "verified": false
            },
            "contactNumber": {
                "number": "********0199",
                "verified": false
            },
            "paymentAccounts": [
                "eeba0fd0-f10f-4aca-9fa3-fbf8857a6080"
            ],
            "status": "active",
            "communicationPreference": "email"
        },
        {
            "id": "92b83716-3126-4a1c-b536-dfb781bcd048",
            "customerHashId": "07b1f5a4-3934-418e-bdd3-069d49ff0932",
            "name": "Nium",
            "entityType": "corporate",
            "email": {
                "value": "t*****@nium.com",
                "verified": false
            },
            "contactNumber": {
                "number": "*******7890",
                "verified": false
            },
            "paymentAccounts": [
                "47a2a6ab-db7d-4f3a-a99f-44cccc66f1fc"
            ],
            "status": "active",
            "communicationPreference": "email",
            "remitterBeneficiaryRelationship": "relationship",
            "businessRegistrationNumber": "*****6756",
            "businessType": "partnership",
            "name_local": "test"
        },
        {
            "id": "a3c9e204-1f5b-4d8e-92ac-7b4f8cc12e45",
            "customerHashId": "07b1f5a4-3934-418e-bdd3-069d49ff0932",
            "name": "John Doe",
            "entityType": "individual",
            "email": {
                "value": "j*****@example.com",
                "verified": true
            },
            "contactNumber": {
                "number": "********4567",
                "verified": true
            },
            "paymentAccounts": [
                "b6e2d811-9f3c-45a7-8123-2d55f9aa1c88",
                "d9a1b74e-8cf3-42e5-a0b2-551c9f3b84e7"
            ],
            "status": "active",
            "communicationPreference": "email"
        },
        {
            "id": "c7e91a3f-0b5d-49c2-b841-e3fa6c7b99d1",
            "customerHashId": "07b1f5a4-3934-418e-bdd3-069d49ff0932",
            "name": "Acme Corporation Ltd",
            "entityType": "corporate",
            "email": {
                "value": "f*****@acme.com",
                "verified": true
            },
            "contactNumber": {
                "number": "*******1234",
                "verified": false
            },
            "paymentAccounts": [
                "5f82c4a9-61e3-4d78-9a12-83fb4e5d6c91"
            ],
            "status": "active",
            "communicationPreference": "email",
            "remitterBeneficiaryRelationship": "supplier",
            "businessRegistrationNumber": "*****8821",
            "businessType": "corporation"
        },
        {
            "id": "e4b8d192-2a6c-4f19-bc5a-9e8f3d7b2c66",
            "customerHashId": "07b1f5a4-3934-418e-bdd3-069d49ff0932",
            "name": "Jane Smith",
            "entityType": "individual",
            "email": {
                "value": "j*****@gmail.com",
                "verified": false
            },
            "contactNumber": {
                "number": "********5511",
                "verified": false
            },
            "paymentAccounts": [
                "7c91e3a2-4b85-4d16-91f8-2a6c5f9e3b41"
            ],
            "status": "inactive",
            "communicationPreference": "email"
        }
    ],
    "pagination": {
        "totalRecords": 264,
        "totalPages": 27,
        "currentCursor": "4d3db693-68dc-49c7-a1a6-ebb3c06111dd",
        "nextCursor": "f2a8c519-7d3b-4b8e-a4c1-6e9f5d82a3b7"
    }
}

Get Specific Beneficiary

Retrieve details of a specific beneficiary:

curl --location 'https://gateway.nium.com/api/v3/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}' \
--header 'x-api-key: ********'

Response includes: Beneficiary details

{
    "id": "a3c9e204-1f5b-4d8e-92ac-7b4f8cc12e45",
    "customerHashId": "07b1f5a4-3934-418e-bdd3-069d49ff0932",
    "name": "John Doe",
    "entityType": "individual",
    "email": {
        "value": "j*****@example.com",
        "verified": true
    },
    "contactNumber": {
        "number": "********4567",
        "verified": true
    },
    "paymentAccounts": [
        "b6e2d811-9f3c-45a7-8123-2d55f9aa1c88",
        "d9a1b74e-8cf3-42e5-a0b2-551c9f3b84e7"
    ],
    "status": "active",
    "communicationPreference": "email",
    "remitterBeneficiaryRelationship": "self"
}

List Payment Accounts for a Beneficiary

Retrieve all payment accounts associated with a beneficiary:

curl --location 'https://gateway.nium.com/api/v3/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts' \
--header 'x-api-key: ********'

Response includes: List of payment accounts with paymentAccountHashId and account details

{
    "paymentAccounts": [
        {
            "id": "b6e2d811-9f3c-45a7-8123-2d55f9aa1c88",
            "beneficiaryHashId": "a3c9e204-1f5b-4d8e-92ac-7b4f8cc12e45",
            "owner": {
                "name": "John Doe",
                "address": {
                    "line1": "*****",
                    "line2": "*****",
                    "city": "San Francisco",
                    "state": "*****",
                    "countryCode": "us",
                    "postalCode": "*****"
                },
                "identification": {
                    "type": "passport",
                    "value": "*****"
                }
            },
            "autoSweep": {
                "default": false,
                "enable": false
            },
            "alias": "Chase checking",
            "payoutCountry": "us",
            "payoutCurrency": "usd",
            "paymentMethod": "local",
            "verificationStatus": {
                "status": "verified",
                "date": "2026-03-15",
                "method": "AccountVerificationService"
            },
            "status": "active",
            "bankName": "JPMorgan Chase Bank",
            "accountType": "checking",
            "accountNumber": "******1234",
            "routingCodes": [
                {
                    "type": "ach_code",
                    "value": "021000021"
                }
            ],
            "openDate": "2025-08-22",
            "default": true
        },
        {
            "id": "d9a1b74e-8cf3-42e5-a0b2-551c9f3b84e7",
            "beneficiaryHashId": "a3c9e204-1f5b-4d8e-92ac-7b4f8cc12e45",
            "owner": {
                "name": "John Doe",
                "address": {
                    "line1": "*****",
                    "line2": "*****",
                    "city": "San Francisco",
                    "state": "*****",
                    "countryCode": "us",
                    "postalCode": "*****"
                },
                "identification": {
                    "type": "passport",
                    "value": "*****"
                }
            },
            "autoSweep": {
                "default": false,
                "enable": false
            },
            "alias": "Barclays GBP",
            "payoutCountry": "gb",
            "payoutCurrency": "gbp",
            "paymentMethod": "swift",
            "verificationStatus": {
                "status": "pending",
                "date": "2026-04-10",
                "method": "AccountVerificationService"
            },
            "status": "active",
            "bankName": "Barclays Bank PLC",
            "accountType": "checking",
            "accountNumber": "******7891",
            "routingCodes": [
                {
                    "type": "swift",
                    "value": "BARCGB22"
                }
            ],
            "openDate": "2026-01-18",
            "default": false
        }
    ],
    "pagination": {
        "totalRecords": 2,
        "totalPages": 1,
        "currentCursor": "b6e2d811-9f3c-45a7-8123-2d55f9aa1c88"
    }
}

Get Specific Payment Account

Retrieve details of a specific payment account:

curl --location 'https://gateway.nium.com/api/v3/client/{clientHashId}/customer/{customerHashId}/beneficiaries/{beneficiaryHashId}/payment-accounts/{paymentAccountHashId}' \
--header 'x-api-key: ********'

Response includes: Payment account details with paymentAccountHashId

{
    "paymentAccounts": [
        {
            "id": "c4a91e73-5b82-4d19-af26-8f3b5c7d9e41",
            "beneficiaryHashId": "c7e91a3f-0b5d-49c2-b841-e3fa6c7b99d1",
            "owner": {
                "name": "Acme Corporation Ltd",
                "address": {
                    "line1": "*****",
                    "line2": "*****",
                    "city": "Berlin",
                    "state": "*****",
                    "countryCode": "de",
                    "postalCode": "*****"
                },
                "identification": {
                    "type": "business_registration",
                    "value": "*****"
                }
            },
            "autoSweep": {
                "default": false,
                "enable": false
            },
            "alias": "Deutsche Bank EUR",
            "payoutCountry": "de",
            "payoutCurrency": "eur",
            "paymentMethod": "local",
            "verificationStatus": {
                "status": "verified",
                "date": "2026-02-28",
                "method": "AccountVerificationService"
            },
            "status": "active",
            "bankName": "Deutsche Bank AG",
            "accountType": "current",
            "accountNumber": "DE******************5678",
            "routingCodes": [
                {
                    "type": "swift",
                    "value": "DEUTDEFF"
                }
            ],
            "openDate": "2024-11-03",
            "default": true
        }
    ],
    "pagination": {
        "totalRecords": 1,
        "totalPages": 1,
        "currentCursor": "c4a91e73-5b82-4d19-af26-8f3b5c7d9e41"
    }
}

Using Payment Account ID for Transfers

Once you have retrieved the paymentAccountHashId, use it to initiate a transfer to the beneficiary/recipient via the Transfer Money API:

Endpoint: POST https://gateway.nium.com/api/v1/client/{clientHashId}/customer/{customerHashId}/wallet/{walletHashId}/remittance

Request Body Example:

{
  "beneficiary": {
    "paymentAccountId": "{paymentAccountHashId}"
  },
  "amount": 5000,
  "currency": "USD",
  "description": "Payment to beneficiary"
}

Full API Reference: Transfer Money API Documentation

Security Best Practices

Keep Client Credentials Server-Side

Never expose clientSecret in frontend code. All requests to Nium must be from backend.

Incorrect Example:

// Client secret exposed in frontend code
fetch("https://gateway.nium.com/marketplace-service/api/v1/init", {
  body: JSON.stringify({
    clientSecret: "exposed-secret",
  }),
});

Correct Example:

// Frontend calls backend, backend calls Nium
fetch("/api/initiate-beneficiary-onboarding", {
  body: JSON.stringify({
    beneficiaryId: "123",
    form: "payment",
  }),
});

Handle Short-Lived Sessions Immediately

Session IDs expire after 30 seconds. Redirect the beneficiary/recipient to the hosted form as soon as a valid sessionId is returned.

If session expires before use, create new session and restart flow.

Store Credentials Securely

Never commit credentials to public code
Use secure secret credentials management (AWS Secrets Manager, HashiCorp Vault, etc.)

Use HTTPS in Production

All requests to Nium API must be made over HTTPS in production environments.

Key Terms

Customer (Client)

Represents client/platform in Nium
Identified by customerHashId
Initiates Payment and Tax form sessions for beneficiaries/recipients
Acts as tax filer for beneficiaries/recipients under client
Tax filing entity of client represented by filer resource

Beneficiary (Beneficiary/Recipient)

Represents beneficiary/recipient receiving payouts
Created when beneficiary/recipient completes Payment form
Identified by beneficiaryId generated by Nium
Receives payments from client
Is taxpayer for tax purposes

Session Lifecycle

Each Nium-hosted form session is short-lived and can be used only once. Depending on beneficiary/recipient interaction, they're redirected to different URLs provided when starting session.

Success

When beneficiary/recipient successfully completes form, redirected to success URL:

https://clients.example.com/payment/success?customerHashId=1fb5eaa1...

Use redirect URL to confirm completion. Extract customerHashId and continue internal workflow.

Cancelled

If beneficiary/recipient cancels form before completing, redirected to cancel URL:

https://clients.example.com/payment/cancel

Use redirect URL to display appropriate message or allow beneficiary/recipient to try again later.

Session Expiry

A form session expires after 30 seconds and can only be used once.

If beneficiary/recipient doesn't start form before expiry, redirected to refresh URL:

https://clients.example.com/payment/refresh

If session expires, create new one and redirect beneficiary/recipient to new session.

Testing

Nium provides sandbox environment allowing Payment and Tax form testing without creating live records or processing real data. Use sandbox to validate integration flow, redirects, and error handling before moving to production.

Sandbox Credentials

Contact Nium Support or point of contact for sandbox credentials:

You'll receive:

Test clientHashId
Test clientSecret
Test customerHashId representing client

Use these credentials only in non-production environments.

Test Beneficiaries/Recipients

When testing form flows, use non-production beneficiary/recipient details:

Examples:

Use placeholder names and emails (e.g., test.recipient+1@example.com, test.recipient+2@example.com)
Avoid real beneficiary/recipient data
Reuse same test beneficiary/recipient details to validate repeat flows

Sandbox Endpoint

Use following endpoint to initialize form sessions in sandbox:

https://sandbox.gateway.nium.com/marketplace-service/api/v1/init

Common Questions

Can we skip the Payment form and go directly to the Tax form?

No. The Payment form must be completed first to create the beneficiary/recipient's beneficiary record. The Tax form cannot be used until a beneficiary exists.

Is customerHashId always required?

Yes, customerHashId always required. It identifies client as customer under which beneficiaries/recipients onboarded and beneficiary created.

What happens if we start a Tax form before the beneficiary/recipient completes the Payment form?

Request fails with BENEFICIARY_REQUIRED error, indicating Payment form must be completed first.

Can the same beneficiary/recipient complete the Payment and Tax forms in separate sessions?

Yes. Once Payment form completed and beneficiary created, separate Tax form session can be started for same beneficiary/recipient.

How can we tell if a beneficiary/recipient has already completed the Payment form?

If beneficiary record exists for beneficiary/recipient, Payment form completed. Nium can provide guidance on checking during integration.

What's the difference between customerHashId and beneficiaryId?

customerHashId: Client (you provide this value)
beneficiaryId: Beneficiary/recipient - created by Nium when beneficiary/recipient completes Payment form

Can a beneficiary/recipient update an existing payment method?

Yes. If beneficiary/recipient already has payment method on file, Payment form enables review and update.

Filer Section​

Create a Filer​

Fetch Filer​

Required Forms​

Payment and Tax Forms​

Request Parameters​

Form Requirements​

Payment Form​

Tax Form​

Request Examples​

Payment Form​

Tax Form​

Error Codes​

User Flow​

Payment Form Flow​

Tax Form Flow​

Retrieving Payment Account IDs​

Using Payment Account ID for Transfers​

Security Best Practices​

Keep Client Credentials Server-Side​

Handle Short-Lived Sessions Immediately​

Store Credentials Securely​

Use HTTPS in Production​

Key Terms​

Customer (Client)​

Beneficiary (Beneficiary/Recipient)​

Session Lifecycle​

Success​

Cancelled​

Session Expiry​

Testing​

Sandbox Credentials​

Test Beneficiaries/Recipients​

Sandbox Endpoint​

Common Questions​

Filer Section

Create a Filer

Fetch Filer

Required Forms

Payment and Tax Forms

Request Parameters

Form Requirements

Payment Form

Tax Form

Request Examples

Payment Form

Tax Form

Error Codes

User Flow

Payment Form Flow

Tax Form Flow

Retrieving Payment Account IDs

Using Payment Account ID for Transfers

Security Best Practices

Keep Client Credentials Server-Side

Handle Short-Lived Sessions Immediately

Store Credentials Securely

Use HTTPS in Production

Key Terms

Customer (Client)

Beneficiary (Beneficiary/Recipient)

Session Lifecycle

Success

Cancelled

Session Expiry

Testing

Sandbox Credentials

Test Beneficiaries/Recipients

Sandbox Endpoint

Common Questions