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 the 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 "{}" 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

toAddressstringOptional

Filter by destination wallet address of the recipient's crypto settlement

Example: 0x742CE26dE564353cCE46aa2c7D8e3DB5f56f9E21

namestringOptional

Filter by recipient name

Example: Jane Smith

pixKeystringOptional

Filter by the PIX key on the recipient's fiat settlement

Example: [e-mail]

taxIdstringOptional

Filter by the tax ID on the recipient's KYC information

Example: 11144477735

chainIdsone ofOptional

Filter by one or more destination chain IDs of the recipient's crypto settlement. Accepts a single chain ID, a comma-separated list (e.g. 1,8453,42161), or a repeated array query parameter.

stringOptionalExample: 1,8453,42161

or

string[]OptionalExample: ["1","8453","42161"]

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": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Jane Smith",
      "isActive": true,
      "projectId": "project-uuid",
      "organizationId": "organization-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": "[e-mail]",
          "keyType": null
        }
      },
      "kycInformation": {
        "taxId": "11144477735",
        "taxIdCountry": "BRA",
        "name": "Jane Smith",
        "email": "[e-mail]"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "223e4567-e89b-12d3-a456-426614174001",
      "name": "John Doe",
      "isActive": true,
      "projectId": "project-uuid",
      "organizationId": "organization-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 GET or endpoints with no request body, use the string "{}" (canonical empty object) for the signature.

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:

• A name alone is not sufficient to create a recipient. You must also provide settlement details: either cryptoSettlementDetails, OR both fiatSettlementDetails and kycInformation. Requests with only a name are rejected with a 400 validation error.

• 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

messagestringOptionalExample: Recipient created successfully

recipientIdstringOptional

Generated recipient ID

Example: 123e4567-e89b-12d3-a456-426614174000

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": "123e4567-e89b-12d3-a456-426614174000"
}

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 GET or endpoints with no request body, use the string "{}" (canonical empty object) for the signature.

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

messagestringOptionalExample: Recipient settlement details updated successfully

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: 211

{
  "recipientId": "123e4567-e89b-12d3-a456-426614174000",
  "cryptoSettlementDetails": {
    "toChain": "8453",
    "toToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "toAddress": "0x742d35Cc6634C0532925a3b844Bc45426438f000"
  }
}

Update crypto settlement detailsUpdate fiat settlement details

{
  "message": "Recipient settlement details updated successfully",
  "previousDetails": {
    "crypto": {
      "toChain": "137",
      "toToken": "0x2791Bca1f2de6b74d8cD3A0e5a1b1C5C7b8a8f3F",
      "toAddress": "0x8ba1f109551bD32515d9Ba1F84b2E2dA9D2C9f0E",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "fiat": {
      "toCurrency": "BRL",
      "bankAccount": "1234567890",
      "bankBranch": "001",
      "bankAccountType": "checking",
      "iban": "BR9700360305000010009795493P1",
      "pixKey": "[e-mail]",
      "cbuCvu": "0000003100010000000001,0000003100010000000002",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

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 GET or endpoints with no request body, use the string "{}" (canonical empty object) for the signature.

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

• 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

successbooleanOptionalExample: true

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: 54

{
  "recipientId": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "success": true,
  "data": {
    "recipientId": "123e4567-e89b-12d3-a456-426614174000",
    "recipientName": "Example Recipient",
    "deactivatedAt": "2024-03-19T12:34:56.789Z"
  }
}