Transactions

Use this API to create and get transactions for a customer and a quote. Requires the creation of a quote beforehand per transaction.

Create a transaction

Creates a transaction using a given quoteID. QuoteID must be valid and not expired.

POSThttps://app.fernhq.com/api/v0/transactions

Body

application/json

quoteId*string

Identifier of the quote to initiate the transaction

Example: "c88ebfc2-3356-48b5-b2bb-6fca7b618c96"

correlationIdnullable string

Optional: You can add your own correlationId to match the transaction to your own internal records.

Example: "03b7030f-6da1-4e76-3352-3debd82112c8"

Response

200400403404500

Transaction created successfully

Body

application/json

transactionId*string

Unique identifier of the transaction

Example: "1d8beb26-b4d1-47ee-8e5d-0d3905f200c7"

correlationIdstring

Optional: You can add your own correlationId to match the transaction to your own internal records.

Example: "03b7030f-6da1-4e76-3352-3debd82112c8"

status*Transaction State

Current status of the transaction

Example: "PROCESSING"

AWAITING_TRANSFERPROCESSINGCOMPLETEDFAILEDCANCELLED

fees*Transaction Fees

Detailed breakdown of all fees associated with the transaction

exchangeRate*number

The rate at which the source currency is multiplied to determine the equivalent amount in the destination currency

Example: 1.2

transferInstructions*Transfer Instructions

Transfer instructions for either onramp or offramp transactions

Transfer InstructionsOnramp Transfer Instructions

source*object

destination*object

sendingAmount*number

The amount to convert and send, expressed in decimals and denominated in the source currency

Example: 100

receivingAmount*number

The amount that will be received after conversion and fees

Example: 98.5

minGuaranteedReceivingAmount*number

The minimum amount guaranteed to be received, accounting for potential price fluctuations

Example: 98

errorDetails*array of object

Details of the error if the transaction has failed

Request

JavaScriptCurlPython

const response = await fetch('https://app.fernhq.com/api/v0/transactions', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
      "quoteId": "c88ebfc2-3356-48b5-b2bb-6fca7b618c96"
    }),
});
const data = await response.json();

Response

200400403404500

{
  "transactionId": "1d8beb26-b4d1-47ee-8e5d-0d3905f200c7",
  "correlationId": "03b7030f-6da1-4e76-3352-3debd82112c8",
  "status": "PROCESSING",
  "fees": {
    "fernFee": {
      "type": "fern",
      "currency": "USD",
      "amount": 5.45,
      "usdAmount": 5.45
    },
    "developerFee": {
      "type": "fern",
      "currency": "USD",
      "amount": 5.45,
      "usdAmount": 5.45
    }
  },
  "exchangeRate": 1.2,
  "transferInstructions": {
    "type": "offramp",
    "paymentMethod": "ethereum",
    "transferWalletAddress": "0x123abc123abc123abc123abc123abc123abc123a"
  },
  "source": {
    "bankAccountId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
    "paymentMethod": "ach",
    "currency": "USD"
  },
  "destination": {
    "bankAccountId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
    "walletAddress": "0xbf50fb9c99233f95bce213044507e58485cf9eba",
    "paymentMethod": "ach",
    "currency": "USDC",
    "wireMessage": "text",
    "achReference": "text"
  },
  "sendingAmount": 100,
  "receivingAmount": 98.5,
  "minGuaranteedReceivingAmount": 98,
  "errorDetails": [
    {
      "message": "Insufficient funds",
      "code": "INSUFFICIENT_FUNDS",
      "metadata": {
        "errorType": "Funds Error"
      },
      "timestamp": "2021-08-10T14:48:00Z",
      "action": "Add more funds"
    }
  ]
}

Get transaction details

GEThttps://app.fernhq.com/api/v0/transactions/{transactionId}

Path parameters

transactionId*string

Unique identifier of the transaction

Example: "1d8beb26-b4d1-47ee-8e5d-0d3905f200c7"

Response

200400500

Transaction retrieved successfully

Body

application/json

transactionId*string

Unique identifier of the transaction

Example: "1d8beb26-b4d1-47ee-8e5d-0d3905f200c7"

correlationIdstring

Optional: You can add your own correlationId to match the transaction to your own internal records.

Example: "03b7030f-6da1-4e76-3352-3debd82112c8"

status*Transaction State

Current status of the transaction

Example: "PROCESSING"

AWAITING_TRANSFERPROCESSINGCOMPLETEDFAILEDCANCELLED

fees*Transaction Fees

Detailed breakdown of all fees associated with the transaction

exchangeRate*number

The rate at which the source currency is multiplied to determine the equivalent amount in the destination currency

Example: 1.2

transferInstructions*Transfer Instructions

Transfer instructions for either onramp or offramp transactions

Transfer InstructionsOnramp Transfer Instructions

source*object

destination*object

sendingAmount*number

The amount to convert and send, expressed in decimals and denominated in the source currency

Example: 100

receivingAmount*number

The amount that will be received after conversion and fees

Example: 98.5

minGuaranteedReceivingAmount*number

The minimum amount guaranteed to be received, accounting for potential price fluctuations

Example: 98

errorDetails*array of object

Details of the error if the transaction has failed

Request

JavaScriptCurlPython

const response = await fetch('https://app.fernhq.com/api/v0/transactions/{transactionId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400500

{
  "transactionId": "1d8beb26-b4d1-47ee-8e5d-0d3905f200c7",
  "correlationId": "03b7030f-6da1-4e76-3352-3debd82112c8",
  "status": "PROCESSING",
  "fees": {
    "fernFee": {
      "type": "fern",
      "currency": "USD",
      "amount": 5.45,
      "usdAmount": 5.45
    },
    "developerFee": {
      "type": "fern",
      "currency": "USD",
      "amount": 5.45,
      "usdAmount": 5.45
    }
  },
  "exchangeRate": 1.2,
  "transferInstructions": {
    "type": "offramp",
    "paymentMethod": "ethereum",
    "transferWalletAddress": "0x123abc123abc123abc123abc123abc123abc123a"
  },
  "source": {
    "bankAccountId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
    "paymentMethod": "ach",
    "currency": "USD"
  },
  "destination": {
    "bankAccountId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
    "walletAddress": "0xbf50fb9c99233f95bce213044507e58485cf9eba",
    "paymentMethod": "ach",
    "currency": "USDC",
    "wireMessage": "text",
    "achReference": "text"
  },
  "sendingAmount": 100,
  "receivingAmount": 98.5,
  "minGuaranteedReceivingAmount": 98,
  "errorDetails": [
    {
      "message": "Insufficient funds",
      "code": "INSUFFICIENT_FUNDS",
      "metadata": {
        "errorType": "Funds Error"
      },
      "timestamp": "2021-08-10T14:48:00Z",
      "action": "Add more funds"
    }
  ]
}

List transactions

GEThttps://app.fernhq.com/api/v0/transactions

Query parameters

Response

200403

Transactions retrieved successfully

Body

application/json

transactionsarray of Create Transaction Response Schema

Retrieved transactions

nextPageTokenstring

Page token to use to fetch next page

Example: "xyz"

Request

JavaScriptCurlPython

const response = await fetch('https://app.fernhq.com/api/v0/transactions?customerId=072a8b7b-38c7-429a-a6cf-35dae7f2fb77', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200403

{
  "transactions": [
    {
      "transactionId": "1d8beb26-b4d1-47ee-8e5d-0d3905f200c7",
      "correlationId": "03b7030f-6da1-4e76-3352-3debd82112c8",
      "status": "PROCESSING",
      "fees": {
        "fernFee": {
          "type": "fern",
          "currency": "USD",
          "amount": 5.45,
          "usdAmount": 5.45
        },
        "developerFee": {
          "type": "fern",
          "currency": "USD",
          "amount": 5.45,
          "usdAmount": 5.45
        }
      },
      "exchangeRate": 1.2,
      "transferInstructions": {
        "type": "offramp",
        "paymentMethod": "ethereum",
        "transferWalletAddress": "0x123abc123abc123abc123abc123abc123abc123a"
      },
      "source": {
        "bankAccountId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
        "paymentMethod": "ach",
        "currency": "USD"
      },
      "destination": {
        "bankAccountId": "072a8b7b-38c7-429a-a6cf-35dae7f2fb77",
        "walletAddress": "0xbf50fb9c99233f95bce213044507e58485cf9eba",
        "paymentMethod": "ach",
        "currency": "USDC",
        "wireMessage": "text",
        "achReference": "text"
      },
      "sendingAmount": 100,
      "receivingAmount": 98.5,
      "minGuaranteedReceivingAmount": 98,
      "errorDetails": [
        {
          "message": "Insufficient funds",
          "code": "INSUFFICIENT_FUNDS",
          "metadata": {
            "errorType": "Funds Error"
          },
          "timestamp": "2021-08-10T14:48:00Z",
          "action": "Add more funds"
        }
      ]
    }
  ],
  "nextPageToken": "xyz"
}