Submit Transaction Payload

The Submit Transaction Payload endpoint is the primary API for sending payment transactions to Rivet for optimization. Rivet's model trains on your sales data and payment gateway reporting data to build a unique optimized payload for your use case.

Endpoint

POST https://ASSIGNED_RIVET_API_HOSTNAME/v1/transaction_payloads

Request Example

You can submit a transaction payload either by calling the HTTP API directly or by using Rivet's Node.js package. 

curl \
    https://ASSIGNED_RIVET_API_HOSTNAME/v1/transaction_payloads \
    --request POST \
    --header 'Authorization: Token 53084bad-c316-448c-bccf-9c323efd1916' \
    --header 'Content-Type: application/json' \
    --data-raw '{
  "action": "OPTIMIZE_SALE",
  "payload": {
    "com_ind": "ecomm",
    "account_token": "tok_XXXXXXXXXXXX",
    "mid": "449330391",
    "amount": 12289,
    "expiration": "1228",
    "account_zip": "97123",
    "cvv": "tok_XXXXXXXXXXXX",
    "currency": "USD",
    "capture": "Y",
    "name": "George Jetson",
    "company_name": "Jetson Family",
    "address1": "123 Skypad Apartments",
    "address2": "Apt 7",
    "city": "Orbit City",
    "region": "CA",
    "country": "US",
    "phone": "5555551234",
    "email": "george.jetson@spacely.com"
  },
  "payload_metadata": {
    "item_purchased": "Sprocket Widget A",
    "invoice_id": "INV-2026-040601",
    "shipping_method": "UPS_GROUND_DOMESTIC"
  }
}'
const rivet = require('rivet');

const requestPayload = {
  "action": "OPTIMIZE_SALE",
  "payload": {
    "com_ind": "ecomm",
    "account_token": "tok_XXXXXXXXXXXX",
    "mid": "449330391",
    "amount": 12289,
    "expiration": "1228",
    "account_zip": "97123",
    "cvv": "tok_XXXXXXXXXXXX",
    "currency": "USD",
    "capture": "Y",
    "name": "George Jetson",
    "company_name": "Jetson Family",
    "address1": "123 Skypad Apartments",
    "address2": "Apt 7",
    "city": "Orbit City",
    "region": "CA",
    "country": "US",
    "phone": "5555551234",
    "email": "george.jetson@spacely.com"
  },
  "payload_metadata": {
    "item_purchased": "Sprocket Widget A",
    "invoice_id": "INV-2026-040601",
    "shipping_method": "UPS_GROUND_DOMESTIC"
  }
};

const optimizedResult = await rivet.optimize(requestPayload);

Request Parameters

The request body must include an action field and a payload object containing the payment details to optimize.

Parameter Type Required Description
action string Yes The action to perform
payload object Yes The payment data object containing all transaction details.
payload_metadata object No Additional metadata about the payment. This data helps train the model and optimize the payment for your use case.

Response

The API response includes the optimized payload and a metadata object that indicates which optimizations were applied.

API Response 
{
  "_metadata": {
    "success_flag": true,
    "error_message": null,
    "error_code": 200,
    "error_key": null,
    "processing_time_ms": 45,
    "optimization_applied_flag": true,
    "optimization_applied": {
      "line_items_data_enrichment": true,
      "shipping_data_enrichment": true,
      "tax_data_enrichment": true
    }
  },
  "data": {
    "optimized_payload": {...}
  }
}

Error Responses

When an error occurs, the API returns an appropriate HTTP status code along with an error message in the response body.

Error Response Example 
{
  "_metadata": {
    "success_flag": false,
    "error_message": "The action must be OPTIMIZE_SALE.",
    "error_code": 400,
    "error_key": "invalid_action",
    "processing_time_ms": 9
  },
  "data": {}
}

HTTP Status Codes

Status Code Description
200 Request processed successfully
400 Bad request - Invalid parameters or missing required fields
401 Unauthorized - Invalid or missing API token
405 Method not allowed - This endpoint only supports POST requests
500 Internal server error - Unexpected error occurred
Top