Payments

Instant payments, batch payments, payment intents, and payment history

These payments use the same two-step prepare → execute flow as the original V1 API: a PUT request returns EIP-712 typed data to sign, then a POST request submits the signature to broadcast the transaction.

All payment endpoints here require Authorization: Bearer <jwt> — see Authentication.

rise_id/payee/recipient/payee_riseid accept a V1 RiseID, V2 RiseID, RiseAccount address, or nanoid interchangeably — see Identifier formats.

Every amount field on this page (amount, total_amount, pay_intents[].amount) is an integer in micro-USD, V1’s original fixed-point unit — 1,000,000 = $1.00. A $100.00 payment is `"amount": 100000000`, not `100.00`. Sending a decimal dollar value like `100.00` is parsed as `100` micro-USD (**$0.0001**) — it won’t error, it’ll just silently pay the wrong amount.

Prepare an instant payment

PUT /v1/payments/pay

wallet · string · required

Wallet address of the payer.

rise_id · string · required

V1/V2 RiseID, RiseAccount address, or nanoid of the paying team.

payee · string · required

V1/V2 RiseID, RiseAccount address, or nanoid of the payee.

amount · number | string · required

Payment amount in micro-USD (1,000,000 = $1.00) — e.g. 100000000 for $100.00.

salt · number | string · required

Unique salt for this payment. Combined with rise_id/payee/amount to derive the on-chain payment id — reusing a salt for the same payer+payee+amount collides with the existing payment and fails with 409. Use a new, never-before-used salt (e.g. a counter or random value) per payment.

curl -X PUT "https://b2b-api.riseworks.io/v1/payments/pay" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0xYourWalletAddress",
    "rise_id": "te-abc123def456",
    "payee": "us-xyz789abc123",
    "amount": 100000000,
    "salt": 1
  }'

{
  "data": {
    "domain": {
      "name": "RiseAccountForwarder",
      "version": "1.0.0",
      "chainId": 42161,
      "verifyingContract": "0x..."
    },
    "types": {
      "RisePayNow": [
        { "name": "from", "type": "address" },
        { "name": "to", "type": "address" },
        { "name": "amount", "type": "uint256" },
        { "name": "salt", "type": "uint256" }
      ]
    },
    "message": {
      "from": "0x...",
      "to": "0x...",
      "amount": "100000000",
      "salt": "1"
    },
    "primaryType": "RisePayNow",
    "descriptor": {}
  }
}

domain, types, and message are the three arguments EIP-712 signing needs — see Creating the signature below. descriptor is always an empty object — a V1 response-shape placeholder with no V2 equivalent.

If this payee already received a very similar payment recently (same team, similar amount, within a lookback window), the response also includes a duplicates field — this doesn’t block the payment, it’s an early warning so you can confirm before signing:

{
  "duplicates": {
    "days_checked": 30,
    "payments": [
      {
        "to": "us-xyz789abc123",
        "amount_cents": 10000,
        "currency_symbol": "USD",
        "invoice_description": "",
        "payment_details": "",
        "external_id": "",
        "created_at": "2024-12-15T00:00:00.000Z"
      }
    ]
  }
}

duplicates is omitted entirely when none are found.

Execute an instant payment

POST /v1/payments/pay

Same body as the prepare step, plus the signed request and signature:

request · object · required

The typed-data request object returned by the prepare step.

signature · string · required

Signature over the typed data.

title · string

Optional payment title (max 60 chars).

description · string

Optional payment description (max 1000 chars).

external_id · string

Optional caller-supplied external reference id. Not length-checked at request time — values over 500 chars are silently truncated, not rejected. (/v1/payments/batch-pay/intents is stricter: it hard-validates a 1000-char max instead.)

{
  "data": {
    "to": "0x...",
    "from": "0x...",
    "contractAddress": null,
    "transactionIndex": 0,
    "gasUsed": { "type": "BigNumber", "hex": "0x..." },
    "blockHash": "0x...",
    "transactionHash": "0x...",
    "logs": [ ],
    "blockNumber": 123456,
    "confirmations": 1,
    "status": 1,
    "type": 2,
    "byzantium": true
  }
}

This is an ethers-v5-shaped transaction receipt, matching V1’s original response exactly.

Creating the signature

domain, types, and message from the prepare response feed directly into EIP-712 signing. This same pattern signs both instant and batch payments — just swap the endpoint.

Using the SDK (recommended)

client.v1Legacy.pay() runs prepare → sign → execute in a single call, using the client’s configured key (or a per-call privateKey override):

const { RiseApiClient } = require('riseworks-sdk');
const { ethers } = require('ethers');

const client = new RiseApiClient({
  environment: 'prod',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.PRIVATE_KEY,
  },
});

// `wallet` is the address that will sign the payment — the same wallet
// backing riseIdAuth.privateKey — not a RiseID.
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY);

const receipt = await client.v1Legacy.pay({
  wallet: wallet.address,
  rise_id: 'te-abc123def456',
  payee: 'us-xyz789abc123',
  amount: 100000000, // $100.00 in micro-USD
  salt: 1,
});

console.log('Transaction hash:', receipt.data.transactionHash);

For manual control over signing, use preparePay/executePay directly, mirroring the same three steps:

const prepared = await client.v1Legacy.preparePay({
  wallet: wallet.address,
  rise_id: 'te-abc123def456',
  payee: 'us-xyz789abc123',
  amount: 100000000,
  salt: 1,
});

const { domain, types, message } = prepared.data;
const { signature } = await client.signTypedData(domain, types, message);

const receipt = await client.v1Legacy.executePay({
  wallet: wallet.address,
  rise_id: 'te-abc123def456',
  payee: 'us-xyz789abc123',
  amount: 100000000,
  salt: 1,
  request: message,
  signature,
});

client.v1Legacy.batchPay() / prepareBatchPay() / executeBatchPay() follow the identical pattern for /v1/payments/batch-pay.

Manual HTTP (no SDK)

import { ethers } from 'ethers';

const baseUrl = 'https://b2b-api.riseworks.io';
const wallet = new ethers.Wallet(process.env.WALLET_PRIVATE_KEY);
const headers = {
  Authorization: `Bearer ${token}`, // from the authentication flow
  'Content-Type': 'application/json',
};

async function payInstant(riseId, payee, amount, salt) {
  // Step 1: Prepare — get EIP-712 typed data to sign
  const prepareResponse = await fetch(`${baseUrl}/v1/payments/pay`, {
    method: 'PUT',
    headers,
    body: JSON.stringify({
      wallet: wallet.address,
      rise_id: riseId,
      payee,
      amount,
      salt,
    }),
  });
  const { data } = await prepareResponse.json();
  const { domain, types, message } = data;

  // Step 2: Sign the typed data with your wallet
  const signature = await wallet.signTypedData(domain, types, message);

  // Step 3: Execute — submit the signature to broadcast the payment
  const executeResponse = await fetch(`${baseUrl}/v1/payments/pay`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      wallet: wallet.address,
      rise_id: riseId,
      payee,
      amount,
      salt,
      request: message,
      signature,
    }),
  });
  const { data: receipt } = await executeResponse.json();
  return receipt; // ethers-v5-shaped transaction receipt
}

const receipt = await payInstant('te-abc123def456', 'us-xyz789abc123', 100000000, 1);
console.log('Transaction hash:', receipt.transactionHash);

The same domain/types/message → wallet.signTypedData() → submit-as-request pattern applies to /v1/payments/batch-pay and /v1/payments/batch-pay/intents as well.

Prepare a batch payment

PUT /v1/payments/batch-pay

wallet · string · required

Wallet address of the payer.

rise_id · string · required

V1/V2 RiseID, RiseAccount address, or nanoid of the paying team.

total_amount · number | string · required

Micro-USD. Must equal the sum of all payments[].amount.

payments · array · required

Array of { recipient, amount, salt } — 1 to 1000 items. Each salt must be unique per recipient + amount (across this batch and any prior payment) — reused salts fail with 409.

curl -X PUT "https://b2b-api.riseworks.io/v1/payments/batch-pay" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0xYourWalletAddress",
    "rise_id": "te-abc123def456",
    "total_amount": 200000000,
    "payments": [
      { "recipient": "us-xyz789abc123", "amount": 100000000, "salt": 1 },
      { "recipient": "us-def456ghi789", "amount": 100000000, "salt": 2 }
    ]
  }'

{
  "data": {
    "domain": {
      "name": "RiseAccountForwarder",
      "version": "1.0.0",
      "chainId": 42161,
      "verifyingContract": "0x..."
    },
    "types": {
      "RisePayNowBatchRequest": [
        { "name": "from", "type": "address" },
        { "name": "payments", "type": "PaymentItem[]" }
      ]
    },
    "message": {
      "from": "0x...",
      "payments": [ ]
    },
    "primaryType": "RisePayNowBatchRequest"
  }
}

Sign with wallet.signTypedData(domain, types, message) — see Creating the signature above. Unlike instant-pay, there’s no descriptor field here — but duplicates can still appear, in the same shape documented above.

Execute a batch payment

POST /v1/payments/batch-pay

Same body as the prepare step, with each payment item optionally carrying title (≤60 chars), description (≤1000 chars), and external_id (silently truncated over 500 chars, not rejected), plus request and signature. Returns the same ethers-v5 receipt shape as the instant-payment execute step.

Create batch payment intents

POST /v1/payments/batch-pay/intents

Creates draft (unscheduled) payments — useful for scheduling future payroll without signing immediately.

company_id · number | string · required

Legacy numeric id, V1/V2 RiseID, RiseAccount address, or nanoid of the paying company/team.

pay_intents · array · required

Array of intents, 1 to 1000 items, each: { payee_riseid, amount, salt, timestamp, title?, description?, external_id? }. amount is micro-USD and must be greater than 0 (the only payment endpoint that rejects 0, where every other one only requires non-negative). title ≤60 chars, description ≤1000 chars, external_id ≤1000 chars.

curl -X POST "https://b2b-api.riseworks.io/v1/payments/batch-pay/intents" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "te-abc123def456",
    "pay_intents": [
      {
        "payee_riseid": "us-xyz789abc123",
        "amount": 100000000,
        "salt": 1,
        "timestamp": 1735689600
      }
    ]
  }'

{
  "data": [
    {
      "id": "pa-abc123def456",
      "payHash": "0x...",
      "amountUSD": "100.00",
      "paySchedule": "0x...",
      "approvedPayDate": "2025-01-01T00:00:00.000Z",
      "saltWeekOrSchedule": "1",
      "company": "te-abc123def456",
      "payee": "us-xyz789abc123",
      "status": "ready",
      "created_at": "2024-12-01T00:00:00.000Z",
      "updated_at": "2024-12-01T00:00:00.000Z",
      "uid": "us-xyz789abc123"
    }
  ]
}

Returns 409 Conflict if a payment group or payment with the same salt already exists — use a new salt to retry.

SDK:

const intents = await client.v1Legacy.createBatchPaymentIntents({
  company_id: 'te-abc123def456',
  pay_intents: [{ payee_riseid: 'us-xyz789abc123', amount: 100000000, salt: 1, timestamp: 1735689600 }],
});

List payments

GET /v1/payments

company_id · number | string · required

Legacy numeric id, V1/V2 RiseID, RiseAccount address, or nanoid of the paying company/team.

external_ids · string | string[]

Filter by one or more caller-supplied external ids.

payee_ids · string | string[]

Filter by one or more payees — V1/V2 RiseID, RiseAccount address, or nanoid.

page · number

1-indexed page number (default 1).

count · number

Page size, 1–1000 (default 100). Values above 1000 are silently capped, not rejected.

status · string

all, a V2 state name (intent/ready, scheduled, complete, removed), or a V1 status (draft, pending, ready, scheduled, submitted, complete, failed, attempted_and_failed, removed, rejected, cancelled).

draft, pending, submitted, failed, attempted_and_failed, rejected, and cancelled pass validation (they’re valid V1 statuses) but have no V2 equivalent — filtering by any of them returns 200 with "data": [] rather than an error. If a filtered call unexpectedly returns nothing, check that status is one of the ones with a real V2 mapping.

curl -X GET "https://b2b-api.riseworks.io/v1/payments?company_id=te-abc123def456&status=all&page=1&count=100" \
  -H "Authorization: Bearer <jwt>"

{
  "data": [
    {
      "amount_usd": "100.00",
      "approved_pay_date": "2025-01-01T00:00:00.000Z",
      "pay_hash": "0x...",
      "salt": "1",
      "status": "complete",
      "external_id": null,
      "transaction_hash": "0x...",
      "payee": {
        "id": "us-xyz789abc123",
        "avatar": null,
        "email": "[e-mail]",
        "name": "Jane Payee",
        "address": "0x..."
      }
    }
  ]
}

SDK:

const payments = await client.v1Legacy.listPayments({ company_id: 'te-abc123def456', status: 'all' });

Errors

Status	Cause
400	Missing/invalid parameters (see the errors object in the response).
401	Missing or expired JWT.
403	Caller lacks WRITE_TEAM_PAYROLL permission on the paying team, or the company isn’t enabled for B2B API access.
404	Payer account, payee, or team not found.
409	A payment group or payment with the same salt (for this payer + payee + amount) already exists — retry with a new, unused salt.
504	(execute endpoints only) Transaction wasn’t confirmed in time — check status via GET /v1/payments before retrying.

Still stuck? See Troubleshooting.