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

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

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

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

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

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

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

Update recipient details

put

Update an existing recipient's settlement details.

Authentication

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

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

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

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

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

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

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

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

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

PreviousFiat To Crypto NextModels

Last updated 7 days ago

Good morning

Fetch recipients

Authentication

Create a recipient

Authentication

Update recipient details

Authentication

Deactivate a recipient

Authentication