Increase a purchase card amount

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}/increase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 5999,
  "reason": "Shipping was added at checkout."
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount: 5999, reason: 'Shipping was added at checkout.'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}/increase', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"amount\": 5999,\n  \"reason\": \"Shipping was added at checkout.\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}/increase")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "platformCustomerId": "user-a1b2c3",
  "status": "PENDING_APPROVAL",
  "type": "EXECUTE_QUOTE",
  "expiresAt": "2025-10-03T15:05:00Z",
  "createdAt": "2025-10-03T15:00:00Z",
  "updatedAt": "2025-10-03T15:02:00Z",
  "quote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "exchangeRate": 123,
    "feesIncluded": 10,
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "platformFeesIncluded": 5,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "purposeOfPayment": "GIFT",
    "documentIds": [
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
    ],
    "scaChallenge": {
      "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
      "expiresAt": "2025-10-03T12:05:00Z",
      "factor": "SMS_OTP",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAssertionOptions": {},
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    },
    "minimumReceivingAmount": 1000,
    "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "destinationChainAddress": {
      "destinationType": "CHAIN_ADDRESS",
      "network": "BASE",
      "currency": "USDC",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationLightningInvoice": {
      "destinationType": "LIGHTNING_INVOICE",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  },
  "previousQuote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "exchangeRate": 123,
    "feesIncluded": 10,
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "platformFeesIncluded": 5,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "purposeOfPayment": "GIFT",
    "documentIds": [
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
    ],
    "scaChallenge": {
      "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
      "expiresAt": "2025-10-03T12:05:00Z",
      "factor": "SMS_OTP",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAssertionOptions": {},
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    },
    "minimumReceivingAmount": 1000,
    "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "destinationChainAddress": {
      "destinationType": "CHAIN_ADDRESS",
      "network": "BASE",
      "currency": "USDC",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationLightningInvoice": {
      "destinationType": "LIGHTNING_INVOICE",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  },
  "priceTolerance": {
    "basisPoints": 100,
    "minimumAmount": 100,
    "currency": "USD"
  },
  "purchaseCard": {
    "amount": 4999,
    "spendLimit": 5749,
    "currency": "USD",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "increaseCardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
    "previousAmount": 4999,
    "previousSpendLimit": 5749,
    "description": "Running shoes from example-store.com",
    "recurring": false,
    "expiresAt": "2026-10-26T15:30:00Z"
  },
  "claimablePayout": {
    "id": "ClaimablePayout:019542f5-b3e7-1d02-0000-000000000077",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
    "platformCustomerId": "user-a1b2c3",
    "status": "PENDING_APPROVAL",
    "sourceAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "amount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "recipient": {
      "name": "Maria",
      "phoneNumber": "+639171234567",
      "email": "maria@example.com",
      "country": "PH"
    },
    "expiresAt": "2025-10-10T15:00:00Z",
    "createdAt": "2025-10-03T15:00:00Z",
    "updatedAt": "2025-10-03T15:02:00Z",
    "note": "Happy birthday, Mom",
    "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
    "externalAccountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "paymentRail": "ACH",
    "failureReason": "INSUFFICIENT_FUNDS"
  },
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
    "status": "CREATED",
    "type": "INCOMING",
    "direction": "CREDIT",
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "currency": "EUR",
      "railDetails": {
        "paymentRail": "ONCHAIN",
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      },
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "pendingReason": "COUNTERPARTY_DECLARATION_REQUIRED",
    "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
    "settledAt": "2025-08-15T14:30:00Z",
    "createdAt": "2025-08-15T14:25:18Z",
    "updatedAt": "2025-08-15T14:30:00Z",
    "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "description": "Payment for invoice #1234",
    "sentAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "exchangeRate": 1.08,
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "refund": {
      "reference": "UMA-Q12345-REFUND",
      "initiatedAt": "2025-08-15T14:30:00Z",
      "status": "COMPLETED",
      "settledAt": "2025-08-15T14:35:00Z",
      "reason": "TRANSACTION_FAILED"
    },
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "currency": "USD",
      "railDetails": {
        "paymentRail": "ONCHAIN",
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      },
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "fees": 10,
    "reconciliationInstructions": {
      "reference": "UMA-Q12345-REF",
      "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
    },
    "failureReason": "LNURLP_FAILED"
  },
  "rejectionReason": "Transaction amount exceeds customer's current risk limit.",
  "failureReason": "QUOTE_EXPIRED"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Agent Operations

Increase a purchase card amount

Increase an open, unused single-use purchase card belonging to this agent. Recurring cards cannot be increased. Requires ISSUE_CARDS and MANAGE_CARDS and platform enablement. The new amount must be greater than the current amount and within the platform’s purchase-card maximum. The new issuer limit includes the platform’s tax and shipping allowance. Returns an ISSUE_PURCHASE_CARD action whose purchaseCard.increaseCardId is the card being increased. It waits for the customer’s approval through the ordinary action approval endpoint when the agent’s current policy requires approval for the new limit (the funding account’s execution mode, else the default execution mode, or the approval threshold), or when the original card required approval. Otherwise it is applied at once. Approval rechecks the card, limits and platform gate. The full new issuer limit is checked against the agent’s current spending limits. Increases do not reserve or count spending; authorization counts the actual spend. Replaying the same key returns the same action; a key used with different parameters is a conflict.

POST

agents

cards

{cardId}

increase

Increase a purchase card amount

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}/increase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "amount": 5999,
  "reason": "Shipping was added at checkout."
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({amount: 5999, reason: 'Shipping was added at checkout.'})
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}/increase', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"amount\": 5999,\n  \"reason\": \"Shipping was added at checkout.\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}/increase")
  .post(body)
  .addHeader("Idempotency-Key", "<idempotency-key>")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "platformCustomerId": "user-a1b2c3",
  "status": "PENDING_APPROVAL",
  "type": "EXECUTE_QUOTE",
  "expiresAt": "2025-10-03T15:05:00Z",
  "createdAt": "2025-10-03T15:00:00Z",
  "updatedAt": "2025-10-03T15:02:00Z",
  "quote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "exchangeRate": 123,
    "feesIncluded": 10,
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "platformFeesIncluded": 5,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "purposeOfPayment": "GIFT",
    "documentIds": [
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
    ],
    "scaChallenge": {
      "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
      "expiresAt": "2025-10-03T12:05:00Z",
      "factor": "SMS_OTP",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAssertionOptions": {},
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    },
    "minimumReceivingAmount": 1000,
    "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "destinationChainAddress": {
      "destinationType": "CHAIN_ADDRESS",
      "network": "BASE",
      "currency": "USDC",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationLightningInvoice": {
      "destinationType": "LIGHTNING_INVOICE",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  },
  "previousQuote": {
    "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "status": "PENDING",
    "createdAt": "2025-10-03T12:00:00Z",
    "expiresAt": "2025-10-03T12:05:00Z",
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "paymentRail": "ACH"
    },
    "sendingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "receivingCurrency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    },
    "totalSendingAmount": 123010,
    "totalReceivingAmount": 1000,
    "exchangeRate": 123,
    "feesIncluded": 10,
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000005",
    "platformFeesIncluded": 5,
    "paymentInstructions": [
      {
        "accountOrWalletInfo": {
          "accountType": "USD_ACCOUNT",
          "paymentRails": [
            "ACH",
            "WIRE"
          ],
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "reference": "UMA-Q12345-REF"
        },
        "instructionsNotes": "Include reference UMA-Q12345-REF in memo"
      },
      {
        "accountOrWalletInfo": {
          "accountType": "SPARK_WALLET",
          "assetType": "BTC",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
          "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
        }
      }
    ],
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "rateDetails": {
      "counterpartyMultiplier": 1.08,
      "counterpartyFixedFee": 10,
      "gridApiMultiplier": 0.925,
      "gridApiFixedFee": 10,
      "gridApiVariableFeeRate": 0.003,
      "gridApiVariableFeeAmount": 30
    },
    "purposeOfPayment": "GIFT",
    "documentIds": [
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000001",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000002",
      "PaymentDocument:019542f5-b3e7-1d02-0000-000000000003"
    ],
    "scaChallenge": {
      "id": "ScaChallenge:019542f5-b3e7-1d02-0000-000000000007",
      "expiresAt": "2025-10-03T12:05:00Z",
      "factor": "SMS_OTP",
      "availableFactors": [
        "SMS_OTP"
      ],
      "purpose": "PAYOUT",
      "passkeyAssertionOptions": {},
      "passkeyAllowedOrigins": [
        "https://app.example.com"
      ]
    },
    "minimumReceivingAmount": 1000,
    "destinationSparkAddress": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu",
    "destinationChainAddress": {
      "destinationType": "CHAIN_ADDRESS",
      "network": "BASE",
      "currency": "USDC",
      "address": "0x1234567890abcdef1234567890abcdef12345678"
    },
    "destinationLightningInvoice": {
      "destinationType": "LIGHTNING_INVOICE",
      "invoice": "lnbc15u1p3xnhl2pp5jptserfk3zk4qy42tlucycrfwxhydvlemu9pqr93tuzlv9cc7g3sdqsvfhkcap3xyhx7un8cqzpgxqzjcsp5f8c52y2stc300gl6s4xswtjpc37hrnnr3c9wvtgjfuvqmpm35evq9qyyssqy4lgd8tj637qcjp05rdpxxykjenthxftej7a2zzmwrmrl70fyj9hvj0rewhzj7jfyuwkwcg9g2jpwtk3wkjtwnkdks84hsnu8xps5vsq4gj5hs"
    }
  },
  "priceTolerance": {
    "basisPoints": 100,
    "minimumAmount": 100,
    "currency": "USD"
  },
  "purchaseCard": {
    "amount": 4999,
    "spendLimit": 5749,
    "currency": "USD",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "increaseCardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
    "previousAmount": 4999,
    "previousSpendLimit": 5749,
    "description": "Running shoes from example-store.com",
    "recurring": false,
    "expiresAt": "2026-10-26T15:30:00Z"
  },
  "claimablePayout": {
    "id": "ClaimablePayout:019542f5-b3e7-1d02-0000-000000000077",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
    "platformCustomerId": "user-a1b2c3",
    "status": "PENDING_APPROVAL",
    "sourceAccountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    "amount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "recipient": {
      "name": "Maria",
      "phoneNumber": "+639171234567",
      "email": "maria@example.com",
      "country": "PH"
    },
    "expiresAt": "2025-10-10T15:00:00Z",
    "createdAt": "2025-10-03T15:00:00Z",
    "updatedAt": "2025-10-03T15:02:00Z",
    "note": "Happy birthday, Mom",
    "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
    "externalAccountId": "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000030",
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "paymentRail": "ACH",
    "failureReason": "INSUFFICIENT_FUNDS"
  },
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000004",
    "status": "CREATED",
    "type": "INCOMING",
    "direction": "CREDIT",
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "currency": "EUR",
      "railDetails": {
        "paymentRail": "ONCHAIN",
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      },
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCustomerId": "18d3e5f7b4a9c2",
    "pendingReason": "COUNTERPARTY_DECLARATION_REQUIRED",
    "ruleBasedAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000011",
    "settledAt": "2025-08-15T14:30:00Z",
    "createdAt": "2025-08-15T14:25:18Z",
    "updatedAt": "2025-08-15T14:30:00Z",
    "receiptDeliveryConfirmedAt": "2025-08-15T14:31:00Z",
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "description": "Payment for invoice #1234",
    "sentAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "exchangeRate": 1.08,
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "refund": {
      "reference": "UMA-Q12345-REFUND",
      "initiatedAt": "2025-08-15T14:30:00Z",
      "status": "COMPLETED",
      "settledAt": "2025-08-15T14:35:00Z",
      "reason": "TRANSACTION_FAILED"
    },
    "counterpartyInformation": {
      "FULL_NAME": "John Sender",
      "BIRTH_DATE": "1985-06-15",
      "NATIONALITY": "DE"
    },
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
      "currency": "USD",
      "railDetails": {
        "paymentRail": "ONCHAIN",
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      },
      "onChainTransaction": {
        "transactionHash": "h82pJGF9p7kpzb6eU326EFZf2cDnimbTFVeJtx1qtBmUNJAEqN76R7PwPfHt3oWb8R6cKvhgyxQdDn53jFrK6wFx",
        "network": "SOLANA"
      }
    },
    "receivedAmount": {
      "amount": 12550,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "fees": 10,
    "reconciliationInstructions": {
      "reference": "UMA-Q12345-REF",
      "transactionHash": "0x9f2c6b6f4b6c8f2a8d9e0b1c2d3e4f5061728394a5b6c7d8e9f00112233445566"
    },
    "failureReason": "LNURLP_FAILED"
  },
  "rejectionReason": "Transaction amount exceeds customer's current risk limit.",
  "failureReason": "QUOTE_EXPIRED"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Headers

Idempotency-Key

string

required

Unique key for this increase, reused on retries.

Maximum string length: 255

Path Parameters

cardId

string

required

The unused single-use purchase card to increase.

Body

application/json

Increase an unused single-use purchase card's amount before checkout.

amount

integer<int64>

required

New purchase amount in USD cents, strictly above the current amount.

Required range: x >= 1

Example:

5999

reason

string

required

Why the purchase needs a higher amount, as reported by the app. The increase action returns it as purchaseCard.description, which is shown to the customer when they approve the increase.

Required string length: 1 - 255

Example:

"Shipping was added at checkout."

Response

The increase action, applied or awaiting approval.

An action submitted by an agent that may require platform approval before execution. All agent-initiated operations (quote execution, transfers) are represented as AgentActions, giving the platform a consistent object to approve, reject, and audit regardless of the underlying operation type.

string

required

System-generated unique identifier for this action.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

agentId

string

required

The agent that submitted this action.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

customerId

string

required

The customer on whose behalf the action was submitted.

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000010"

platformCustomerId

string

required

Platform-specific ID of the customer.

Example:

"user-a1b2c3"

status

enum<string>

required

Status of an agent action.

Status	Description
`PENDING_APPROVAL`	Submitted by the agent, awaiting platform approval before execution
`APPROVED`	Approved by the platform; execution is in progress or completed
`REJECTED`	Rejected by the platform; the underlying transaction was not executed
`FAILED`	Not executed, or execution failed; see `failureReason`

Available options:

PENDING_APPROVAL,

APPROVED,

REJECTED,

FAILED

type

enum<string>

required

The type of action the agent is requesting.

Type	Description
`EXECUTE_QUOTE`	Execute a quote
`ISSUE_PURCHASE_CARD`	Issue a purchase card: single-use, or recurring when `purchaseCard.recurring` is `true`. When `purchaseCard.increaseCardId` is set, raise the amount of that existing single-use card instead of issuing one. See `purchaseCard`
`CLAIMABLE_PAYOUT`	Send a claimable payout to a person by phone number or email. See `claimablePayout`

Available options:

EXECUTE_QUOTE,

ISSUE_PURCHASE_CARD,

CLAIMABLE_PAYOUT

expiresAt

string<date-time>

required

When the action expires. For an EXECUTE_QUOTE action with priceTolerance, this is the end of the platform's approval window, independent of the quote's own expiry: approval executes a live quote and quotes the send again once it has expired, and a pending action that reaches this time fails with APPROVAL_EXPIRED. For any other EXECUTE_QUOTE action, this is the quote's own expiry; a pending action that reaches it fails with QUOTE_EXPIRED, and approval never creates a replacement quote. For ISSUE_PURCHASE_CARD, this is the end of the approval window, after which a pending action fails with APPROVAL_EXPIRED.

Example:

"2025-10-03T15:05:00Z"

createdAt

string<date-time>

required

When the action was submitted by the agent.

Example:

"2025-10-03T15:00:00Z"

updatedAt

string<date-time>

required

When the action was last updated.

Example:

"2025-10-03T15:02:00Z"

quote

Agent Quote · object

The quote being executed. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user. Present for EXECUTE_QUOTE.

Show child attributes

previousQuote

Agent Quote · object

The quote the customer was shown before an approval found that the price had moved past priceTolerance. Present only while the action is PENDING_APPROVAL after such an approval; quote is then the new quote to show the customer, and approving it again repeats the check against it.

Show child attributes

priceTolerance

object

Present on a PENDING_APPROVAL EXECUTE_QUOTE action that Grid quotes again when it is approved after its quote expired: how far the price may move against the customer before they are asked again. Fixed when the action is created. Absent when approval can only execute quote as it is.

Show child attributes

purchaseCard

object

The purchase card the agent asked for, so an approval decision can show its amount, limit, description and funding account. Present for ISSUE_PURCHASE_CARD.

Show child attributes

claimablePayout

object

The claimable payout the agent asked to send, so an approval decision can show its amount and recipient. Present for CLAIMABLE_PAYOUT. Approving the action makes the payout AWAITING_CLAIM; rejecting it, or letting it expire, ends the payout and releases its hold.

Show child attributes

cardId

string

The purchase card the action issued, or for an increase the card whose amount it raised. Present for an ISSUE_PURCHASE_CARD action once it is APPROVED and the card is issued or increased; read it with GET /agents/me/cards/{cardId}.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000011"

transaction

Incoming Transaction · object

The resulting transaction, populated once the action has been approved and execution has begun. Absent while the action is PENDING_APPROVAL or REJECTED.

Incoming Transaction
Outgoing Transaction
Card Transaction

Show child attributes

rejectionReason

string

Human-readable reason provided by the platform when rejecting the action. Only present when status is REJECTED.

Example:

"Transaction amount exceeds customer's current risk limit."

failureReason

enum<string>

Machine-readable reason the action failed. Only present when status is FAILED; rejectionReason is used only for REJECTED actions.

Available options:

QUOTE_EXPIRED,

POLICY_DENIED,

AGENT_INACTIVE,

EXECUTION_FAILED,

PRICE_MOVED,

ADDRESS_REFUSED,

APPROVAL_EXPIRED

Using the API

API documentation

Increase a purchase card amount

Authorizations

Headers

Path Parameters

Body

Response