Recipients

Operations for managing recipient accounts

Fetch recipients

get

Retrieve a paginated list of recipients for the authenticated project. Only returns active recipients.

Authentication

All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of an empty string (no request body for GET requests), using your Client Secret as the key.

Required Headers

Header	Description
x-client-id	Your project's client ID
x-signature	HMAC-SHA256 signature (hash of empty string for GET requests)

--

Response Details:

• Returns only active recipients (deactivated recipients are excluded)

• Recipients are scoped to the authenticated project

• Includes full settlement details (crypto and/or fiat)

• Includes KYC information when available

• Results are ordered alphabetically by recipient name

• Smart wallet information included when recipient was created with generated smart wallet

Authorizations

ClientId & Signature & Timestamp

x-client-idstringRequired

Your project client ID from orda dashboard

x-signaturestringRequired

HMAC-SHA256 signature of canonical request body using your client secret

x-timestampstringRequired

Unix timestamp in milliseconds for replay protection (recommended)

Query parameters

pageinteger · min: 1Optional

Page number for pagination

Default: 1Example: 1

limitinteger · min: 1 · max: 100Optional

Number of recipients per page

Default: 50Example: 20

Header parameters

x-client-idstringRequired

Your project client ID from orda dashboard

Default: prj_abc123def456ghi789Example: prj_abc123def456ghi789

x-signaturestringRequired

HMAC-SHA256 signature of canonical request body using your client secret

Default: a1b2c3d4e5f6789abc123def456ghi789abc123def456Example: a1b2c3d4e5f6789abc123def456ghi789abc123def456

x-timestampstringOptional

Unix timestamp in milliseconds for replay protection (recommended)

Default: 1704067200000Example: 1704067200000

Responses

200

Recipients retrieved successfully

application/json

401

Unauthorized - Invalid credentials

application/json

500

Internal Server Error

application/json

get

/recipients

HTTPcURLJavaScriptPython

GET /v1/recipients HTTP/1.1
Host: api.orda.network
x-client-id: prj_abc123def456ghi789
x-signature: a1b2c3d4e5f6789abc123def456ghi789abc123def456
x-timestamp: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "data": [
    {
      "id": "recipient-uuid-1",
      "name": "Jane Smith",
      "isActive": true,
      "projectId": "project-uuid",
      "businessId": "business-uuid",
      "smartWalletAddress": "0x8ba1f109551bD32515d9Ba1F84b2E2dA9D2C9f0E",
      "walletType": "ALCHEMY_SMART_WALLET",
      "cryptoSettlement": {
        "id": "settlement-uuid",
        "toChain": "137",
        "toToken": "0x2791Bca1f2de6b74d8cD3A0e5a1b1C5C7b8a8f3F",
        "toAddress": "0x8ba1f109551bD32515d9Ba1F84b2E2dA9D2C9f0E",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      },
      "fiatSettlement": {
        "id": "fiat-settlement-uuid",
        "toCurrency": "BRL",
        "method": "PIX",
        "pixDetails": {
          "pixKey": "[email protected]",
          "keyType": "email"
        }
      },
      "kycInformation": {
        "taxId": "123.456.789-00",
        "taxIdCountry": "BR",
        "name": "Jane Smith",
        "email": "[email protected]"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "recipient-uuid-2",
      "name": "John Doe",
      "isActive": true,
      "projectId": "project-uuid",
      "businessId": "business-uuid",
      "smartWalletAddress": null,
      "walletType": "USER_PROVIDED",
      "cryptoSettlement": {
        "id": "settlement-uuid-2",
        "toChain": "1",
        "toToken": "0xA0b86a33E6156ccA41e90b95D50532d6a3b8B7fC",
        "toAddress": "0x742CE26dE564353cCE46aa2c7D8e3DB5f56f9E21",
        "createdAt": "2024-01-14T09:20:00Z",
        "updatedAt": "2024-01-14T09:20:00Z"
      },
      "fiatSettlement": null,
      "kycInformation": null,
      "createdAt": "2024-01-14T09:20:00Z",
      "updatedAt": "2024-01-14T09:20:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalCount": 45,
    "totalPages": 3
  }
}

Create a recipient

post

Create a new recipient for payments. Recipients can have crypto settlement details, fiat settlement details with KYC information, or both.

Authentication

All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For the endpoints where there is no request body, use an empty string.

Required Headers

Header	Description
x-client-id	Your project's client ID
x-signature	HMAC-SHA256 signature derived from your client secret
Content-Type	application/json for this request

--

Important Notes:

• The cryptoSettlementDetails object contains blockchain settlement information

• The kycInformation object is required for fiatSettlementDetails

• Both kycInformation and fiatSettlementDetails are optional for crypto-only transactions

• You need a project client ID to create recipients

Authorizations

ClientId & Signature & Timestamp

x-client-idstringRequired

Your project client ID from orda dashboard

x-signaturestringRequired

HMAC-SHA256 signature of canonical request body using your client secret

x-timestampstringRequired

Unix timestamp in milliseconds for replay protection (recommended)

Header parameters

x-client-idstringRequired

Your project client ID from orda dashboard

Default: prj_abc123def456ghi789Example: prj_abc123def456ghi789

x-signaturestringRequired

HMAC-SHA256 signature of canonical request body using your client secret

Default: a1b2c3d4e5f6789abc123def456ghi789abc123def456Example: a1b2c3d4e5f6789abc123def456ghi789abc123def456

x-timestampstringOptional

Unix timestamp in milliseconds for replay protection (recommended)

Default: 1704067200000Example: 1704067200000

Body

application/json

namestringRequired

Name of the recipient

Example: Leeroy Jenkins

Responses

201

Recipient created successfully

application/json

400

Bad Request - Invalid parameters

application/json

401

Unauthorized - Invalid client ID

application/json

404

Not Found - Project not found

application/json

409

Conflict - Recipient with same name already exists

application/json

422

Unprocessable Entity - Invalid data format

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

post

/create-recipient

HTTPcURLJavaScriptPython

POST /v1/create-recipient HTTP/1.1
Host: api.orda.network
x-client-id: prj_abc123def456ghi789
x-signature: a1b2c3d4e5f6789abc123def456ghi789abc123def456
x-timestamp: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 181

{
  "name": "DeFi Protocol",
  "cryptoSettlementDetails": {
    "toChain": "8453",
    "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "toAddress": "0x742d35Cc6634C0532925a3b844Bc45426438f000"
  }
}

Crypto-only recipientFiat settlement recipient

{
  "message": "Recipient created successfully",
  "recipientId": "generated-recipient-id"
}

Update recipient details

put

Update an existing recipient's settlement details.

Authentication

All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For the endpoints where there is no request body, use an empty string.

Required Headers

Header	Description
x-client-id	Your project's client ID
x-signature	HMAC-SHA256 signature derived from your client secret
Content-Type	application/json for this request

---

Important Notes:

• The recipient ID will remain the same despite settlement details changing

• The response includes previously stored settlement details for audit trail

• You need the project's client ID to update recipients

Authorizations

ClientId & Signature & Timestamp

x-client-idstringRequired

Your project client ID from orda dashboard

x-signaturestringRequired

HMAC-SHA256 signature of canonical request body using your client secret

x-timestampstringRequired

Unix timestamp in milliseconds for replay protection (recommended)

Header parameters

x-client-idstringRequired

Your project client ID from orda dashboard

Default: prj_abc123def456ghi789Example: prj_abc123def456ghi789

x-signaturestringRequired

HMAC-SHA256 signature of canonical request body using your client secret

Default: a1b2c3d4e5f6789abc123def456ghi789abc123def456Example: a1b2c3d4e5f6789abc123def456ghi789abc123def456

x-timestampstringOptional

Unix timestamp in milliseconds for replay protection (recommended)

Default: 1704067200000Example: 1704067200000

Body

application/json

recipientIdstringRequired

ID of the recipient to update

Responses

200

Recipient updated successfully

application/json

400

Bad Request - Invalid parameters

application/json

401

Unauthorized - Invalid client ID

application/json

404

Not Found - Recipient not found

application/json

422

Unprocessable Entity - Invalid data format

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

put

/update-recipient

HTTPcURLJavaScriptPython

PUT /v1/update-recipient HTTP/1.1
Host: api.orda.network
x-client-id: prj_abc123def456ghi789
x-signature: a1b2c3d4e5f6789abc123def456ghi789abc123def456
x-timestamp: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 190

{
  "recipientId": "recipient-12345",
  "cryptoSettlementDetails": {
    "toChain": "8453",
    "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "toAddress": "0x742d35Cc6634C0532925a3b844Bc45426438f000"
  }
}

Update crypto settlement detailsUpdate fiat settlement details

{
  "message": "Recipient details updated successfully",
  "previousDetails": {}
}

Deactivate a recipient

put

Deactivate a recipient to prevent it from processing further transactions. Existing transactions will not be affected.

Authentication

All API requests to orda require HMAC signatures using your project's client ID and client secret. The signature is a HMAC-SHA256 hash of the request body, using your Client Secret as the key. For the endpoints where there is no request body, use an empty string.

Required Headers

Header	Description
x-client-id	Your project's client ID
x-signature	HMAC-SHA256 signature derived from your client secret
Content-Type	application/json for this request

---

Important Notes:

• Only the business can deactivate their recipients

• Deactivation can be undone by the business at any time using the /reactivate-recipient endpoint

• New transactions using the deactivated recipient's ID will be rejected

Authorizations

ClientId & Signature & Timestamp

x-client-idstringRequired

Your project client ID from orda dashboard

x-signaturestringRequired

HMAC-SHA256 signature of canonical request body using your client secret

x-timestampstringRequired

Unix timestamp in milliseconds for replay protection (recommended)

Header parameters

x-client-idstringRequired

Your project client ID from orda dashboard

Default: prj_abc123def456ghi789Example: prj_abc123def456ghi789

x-signaturestringRequired

HMAC-SHA256 signature of canonical request body using your client secret

Default: a1b2c3d4e5f6789abc123def456ghi789abc123def456Example: a1b2c3d4e5f6789abc123def456ghi789abc123def456

x-timestampstringOptional

Unix timestamp in milliseconds for replay protection (recommended)

Default: 1704067200000Example: 1704067200000

Body

application/json

recipientIdstringRequired

ID of the recipient to deactivate

Responses

200

Recipient deactivated successfully

application/json

400

Bad Request - Missing recipient ID

application/json

401

Unauthorized - Invalid API key

application/json

404

Not Found - Recipient not found

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

put

/deactivate-recipient

HTTPcURLJavaScriptPython

PUT /v1/deactivate-recipient HTTP/1.1
Host: api.orda.network
x-client-id: prj_abc123def456ghi789
x-signature: a1b2c3d4e5f6789abc123def456ghi789abc123def456
x-timestamp: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 33

{
  "recipientId": "recipient-12345"
}

{
  "message": "Recipient deactivated successfully",
  "recipientName": "Example Recipient",
  "deactivatedAt": "2024-03-19T12:34:56.789Z"
}