Body

Audience: Salesforce developers building Apex on top of the Accounting Seed Ramp integration. This article documents the package's global Apex API for retrieving a single Ramp card transaction.

RampTransactionAPI is a global class exposed by the managed package. It lets subscriber-org Apex fetch one Ramp transaction by id, using the org's already-configured Ramp connection. No token handling, credential lookup, or HTTP plumbing is required by the caller.

Why use this instead of calling Ramp directly? The method reuses the active Ramp_Credential__mdt and the package's cached OAuth token (with automatic refresh on 401). You get a typed Apex object back, deserialized from Ramp's response. No need to manage authentication or parse JSON yourself.

Method

global static RampTransactionAPI.RampTransaction getTransaction(String transactionId)

	Detail
Parameter	`transactionId`: the Ramp transaction id (UUID).
Returns	A `RampTransaction` object mirroring the Ramp `GET /developer/v1/transactions/{id}` response. Never null on success.
Underlying call	`GET /developer/v1/transactions/{transactionId}` on the org's Ramp connection.
Throws	`RampTransactionAPI.RampTransactionAPIException`. See Exceptions below.

Exceptions

Condition	Message
Blank / null `transactionId`	"transactionId is required."
HTTP 404	"Ramp transaction not found: {id}"
Any other non-2xx	"Ramp API error retrieving transaction {id} (HTTP {code}): {body}"
Response can't be parsed	"Failed to parse Ramp transaction response: {detail}"

Example

try {
    RampTransactionAPI.RampTransaction txn =
        RampTransactionAPI.getTransaction('1ab23c45-6789-40de-8f01-23456789abcd');

    System.debug(txn.merchant_name);   // e.g. "Amazon Web Services"
    System.debug(txn.amount);          // decimal dollars, e.g. 128.40
    System.debug(txn.sync_status);     // e.g. "SYNC_READY"

    if (txn.card_holder != null) {
        System.debug(txn.card_holder.first_name + ' ' + txn.card_holder.last_name);
    }

    // Anything not modeled below is available raw:
    System.debug(txn.rawJson);
} catch (RampTransactionAPI.RampTransactionAPIException e) {
    System.debug(LoggingLevel.ERROR, e.getMessage());
}

Pairs with the Ramp Id on Journal Entry Lines. Transaction sync stamps the Ramp transaction id on every Journal Entry Line in the Ramp_Id__c field. To go from an Accounting Seed line back to the live Ramp transaction, read Ramp_Id__c and pass it straight to getTransaction. No need to parse the External Id.

Response object reference

Field names mirror Ramp's JSON exactly, so the response deserializes directly. All members are global.

RampTransaction

Field	Type	Notes
`id`	String	Ramp transaction UUID.
`amount`	Decimal	Top-level amount in dollars (not minor units).
`currency_code`	String
`accounting_date`	String	ISO 8601.
`user_transaction_time`	String
`settlement_date`	String
`synced_at`	String
`merchant_name`	String
`merchant_descriptor`	String
`merchant_id`	String
`merchant_category_code`	String
`merchant_category_code_description`	String
`memo`	String
`state`	String	e.g. `CLEARED`.
`sync_status`	String	e.g. `SYNC_READY`.
`entity_id`	String	Ramp business entity UUID.
`card_id`	String
`card_present`	Boolean
`sk_category_id`	Integer
`sk_category_name`	String
`card_holder`	CardHolder	See below.
`accounting_field_selections`	List<AccountingFieldSelection>	Transaction-level coding.
`line_items`	List<LineItem>	Split line items.
`rawJson`	String	Full untouched response. Use for any field not modeled here.

CardHolder

Field	Type
`user_id`	String
`first_name`	String
`last_name`	String
`department_id` / `department_name`	String
`location_id` / `location_name`	String
`employee_id`	String

Cardholder email is not on this object. Ramp's transaction payload carries only card_holder.user_id; the email lives on the Users API (GET /developer/v1/users/{id}). The transaction sync resolves emails separately. This single-transaction API returns the cardholder block as Ramp provides it.

AccountingFieldSelection

Field	Type	Notes
`id`	String	UUID of the selected option.
`name`	String
`type`	String	e.g. `GL_ACCOUNT`, `MERCHANT`, variable types.
`external_id` / `external_code`	String
`category_info`	CategoryInfo	Parent field info (`id`, `name`, `type`, `external_id`).

LineItem

Field	Type	Notes
`amount`	CurrencyAmount	Merchant's original currency.
`converted_amount`	CurrencyAmount	Settlement currency.
`memo`	String
`accounting_field_selections`	List<AccountingFieldSelection>	Per-line coding.

CurrencyAmount

Field	Type	Notes
`amount`	Long	Minor units (e.g. cents). Divide by `minor_unit_conversion_rate`.
`currency_code`	String
`minor_unit_conversion_rate`	Integer	Divisor to convert to major units (defaults to 100 if unset/zero).

Usage notes & limits

It makes an HTTP callout. Each call performs one Ramp API callout and counts against the transaction's callout limits. As with any callout, you cannot invoke it after uncommitted DML in the same transaction.
Prerequisite: an active, connected credential. The org must have a single Active Ramp_Credential__mdt and a working Ramp connection (see Ramp Credential Setup & Accounting Connection). With no active credential the underlying auth call errors.
Top-level amount is dollars; line-item amounts are minor units. Use CurrencyAmount.minor_unit_conversion_rate when reading line items.
Unmodeled fields: if Ramp returns a field not listed above, read it from rawJson (parse with JSON.deserializeUntyped).

This is a permanent managed-package API contract. Global members can only change additively across package versions: fields and the method signature won't be removed or renamed. Build against it with that guarantee in mind.

Return to top

Title

Ramp Developer API

URL Name

Ramp-Developer-API