Payment Intents

Overview

The Payment Intents allow you to create payment intents that define spending parameters and budgets for agentic payments. Intents specify the purpose, amount, time period, and spending limits for automated payment processing. Once created, payment intents go through an approval process before becoming active.

Create Payment Intent

Creates a new payment intent for a specific intent type. The AllocatableType ID determines what kind of payment intent you're creating (e.g., Travel, IT, Meals, etc.). This intent defines the spending parameters for agentic payment processing.

Path Parameters

Request Body

The request body must contain the following required fields and can include optional fields for additional configuration.

Example Request

Using cURL:

curl -X POST https://sandbox.custodia-tech.com/md/api/AllocatableTypes/550e8400-e29b-41d4-a716-446655440000/createActivity \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "start": "2024-01-15",
    "end": "2024-01-25",
    "ownerId": "user-id-123",
    "currency": "USD",
    "purpose": "Business trip to New York",
    "name": "NYC Business Trip"
  }'

Using JavaScript (fetch):

const allocatableTypeId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/AllocatableTypes/${allocatableTypeId}/createActivity`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1000,
    start: '2024-01-15',
    end: '2024-01-25',
    ownerId: 'user-id-123',
    currency: 'USD',
    purpose: 'Business trip to New York',
    name: 'NYC Business Trip'
  })
});

const paymentIntent = await response.json();

Creating a payment intent with spending limits:

const response = await fetch(`https://sandbox.custodia-tech.com/md/api/AllocatableTypes/${allocatableTypeId}/createActivity`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    start: '2024-02-01',
    end: '2024-02-28',
    ownerId: 'user-id-123',
    currency: 'USD',
    purpose: 'Monthly IT equipment budget',
    dailyLimit: 500,
    txLimit: 200,
    weekDaysLimit: '1111100', // Monday-Friday only
    hoursLimit: '000000000000111111110000', // 12:00 PM - 10:00 PM only
    txCountLimit: 50
  })
});

Response

{
  "id": "request-id-123",
  "associatedId": "allocation-id-456",
  "status": "pending",
  "amount": 1000,
  "currency": "USD",
  "ownerId": "user-id-123",
  "name": "NYC Business Trip",
  "purpose": "Business trip to New York",
  "start": "2024-01-15",
  "end": "2024-01-25",
  "created": "2024-01-10T10:00:00.000Z"
}

Get Payment Intents (Allocations)

Retrieves a list of payment intents (allocations) that are currently available. You can filter, sort, and paginate the results using query parameters.

Query Parameters

Use the filter query parameter to filter, sort, and paginate results. The filter should be a JSON object passed as a URL-encoded string.

Filter Options

The filter object supports the following properties:

Where Clause Examples

Common filter conditions for the where clause:

Example Requests

Get all active payment intents for a user:

const filter = {
  where: {
    ownerId: 'user-id-123',
    status: 'active'
  },
  utilization: true,
  order: 'activationDate DESC'
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const paymentIntents = await response.json();

Get active and new payment intents with utilization metrics:

const filter = {
  where: {
    ownerId: 'user-id-123',
    status: {inq: ['active', 'new']}
  },
  utilization: true,
  include: ['allocatedTo'],
  order: 'expirationDate ASC',
  limit: 50
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const paymentIntents = await response.json();

Search payment intents by title or purpose:

const filter = {
  where: {
    ownerId: 'user-id-123',
    or: [
      {title: {like: '%Business Trip%'}},
      {purpose: {like: '%Conference%'}}
    ]
  },
  utilization: true
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const paymentIntents = await response.json();

Response

[
  {
    "id": "allocation-id-123",
    "title": "NYC Business Trip",
    "purpose": "Business trip to New York",
    "status": "active",
    "ownerId": "user-id-123",
    "companyId": "company-id-123",
    "amount": 1000,
    "currency": "USD",
    "used": 250,
    "pending": 50,
    "amountLeft": 700,
    "activationDate": "2024-01-15T00:00:00.000Z",
    "expirationDate": "2024-01-25T00:00:00.000Z",
    "activityStart": "2024-01-15",
    "activityEnd": "2024-01-25",
    "boundToCardId": null,
    "allocatedToType": "Travel",
    "created": "2024-01-10T10:00:00.000Z",
    "modified": "2024-01-15T00:00:00.000Z"
  },
  {
    "id": "allocation-id-456",
    "title": "Monthly IT Budget",
    "purpose": "IT equipment and software",
    "status": "active",
    "ownerId": "user-id-123",
    "companyId": "company-id-123",
    "amount": 5000,
    "currency": "USD",
    "used": 1200,
    "pending": 300,
    "amountLeft": 3500,
    "activationDate": "2024-02-01T00:00:00.000Z",
    "expirationDate": "2024-02-28T23:59:59.000Z",
    "activityStart": "2024-02-01",
    "activityEnd": "2024-02-28",
    "boundToCardId": "card-id-789",
    "allocatedToType": "IT",
    "created": "2024-01-25T10:00:00.000Z",
    "modified": "2024-02-01T00:00:00.000Z"
  }
]

Get Payment Intent by ID

Retrieves detailed information about a specific payment intent (allocation) by its ID.

Path Parameters

Query Parameters

Example Request

Using cURL:

curl -X GET "https://sandbox.custodia-tech.com/md/api/Allocations/allocation-id-123?filter=%7B%22utilization%22%3Atrue%7D" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-appid: YOUR_CLIENT_ID"

Using JavaScript (fetch):

const allocationId = 'allocation-id-123';

const filter = {
  utilization: true,
  include: ['allocatedTo', 'budgetAllocations']
};

const filterParam = encodeURIComponent(JSON.stringify(filter));
const response = await fetch(`https://sandbox.custodia-tech.com/md/api/Allocations/${allocationId}?filter=${filterParam}`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'x-appid': clientId
  }
});

const paymentIntent = await response.json();

Response

{
  "id": "allocation-id-123",
  "title": "NYC Business Trip",
  "description": null,
  "purpose": "Business trip to New York",
  "status": "active",
  "ownerId": "user-id-123",
  "companyId": "company-id-123",
  "amount": 1000,
  "currency": "USD",
  "used": 250,
  "pending": 50,
  "amountLeft": 700,
  "activationDate": "2024-01-15T00:00:00.000Z",
  "expirationDate": "2024-01-25T00:00:00.000Z",
  "activityStart": "2024-01-15",
  "activityEnd": "2024-01-25",
  "boundToCardId": null,
  "allocatedToType": "Travel",
  "allocatedToId": "allocatable-type-id",
  "dailyLimit": null,
  "txLimit": null,
  "weekDaysLimit": "1111111",
  "hoursLimit": "111111111111111111111111",
  "txCountLimit": null,
  "merchants": [],
  "keywords": [],
  "created": "2024-01-10T10:00:00.000Z",
  "modified": "2024-01-15T00:00:00.000Z"
}

Payment Intent Fields

The following fields are available in payment intent (allocation) responses:

Error Responses

All endpoints may return the following error responses: