API Endpoints

For a high-level overview on how to integrate these API endpoints see Integration Guide.

Lookup Payment

Lookup Payment

GET https://yodl.me/api/v1/tx/:chainId/:txHash

This endpoint looks up the given transaction in our database and returns an array of payments in an easy to read JSON format. The yodlFee value is a decimal value in terms of the token amount.

If price feeds are provided, conversion will be in the form of chainlink:XXXYYY where XXX is the invoice currency, and YYY is the token currency. The price feeds will be in the order they were used to convert from invoice currency to the token currency. The price feed name will be in the format $baseCurrency$quoteCurrency and their rates will all be in terms of the quote currency (usually USD).

Path Parameters

Headers

{
  "chainId": 1,
  "txHash": "0x00000000000000000000000000000000000000000000000000000000000000",
  "payments": [
    {
      // order ids, invoice number or other
      "memo": "test",
      "receiver": "0x0000000000000000000000000000000000000000",
      "tokenSymbol": "USDC", // symbol of the token being received
      "tokenAmount": { // amount of the token being received
        "formatted": "1.00",
        "value": "1000000"
      },
      "tokenAmountNet": { // amount the receiver gets (amount - fees)
        "formatted": "0.9975",
        "value": "997500"
      },
      "totalFees": {
        "formatted": "0.0025",
        "value": "2500"
      },
      "fees": [
        {
          // fee charged by YODL
          "type": "YodlFee",
          "formatted": "0.002",
          "value": "2000"
        },
        {
          // extra fee charged by third-party
          "type": "ExtraFee",
          "formatted": "0.0005",
          "value": "500"
        }
      ],
      // what was charged/invoice to the payer
      "invoiceAmount": "1",
      "invoiceCurrency": "USD",
      "conversion": "",
      "priceFeeds": [],
      // whether a sufficient number of blocks have passed for the tx to be considered final
      // see Finality section
      "final": true
    }
  ]
}

Lookup & Verify Payment

Lookup and verify a payment against given parameters

POST https://yodl.me/api/v1/verify

This endpoint behaves similarly to the Lookup endpoint with the notable addition of performing server-side payment verification checks. Instead of passing through transaction details in the URL, a JSON payload must be sent.

This endpoint will verify that a malicious user has not interferred and manipulated the payment.

Headers

Request Body

{
  "chainId": 1,
  "txHash": "0x00000000000000000000000000000000000000000000000000000000000000",
  "payments": [
    {
      // order ids, invoice number or other
      "memo": "",
      "receiver": "0x0000000000000000000000000000000000000000",
      "tokenSymbol": "USDC", // symbol of the token being received
      "tokenAmount": { // amount of the token being received
        "formatted": "0.737055",
        "value": "737055"
      },
      "tokenAmountNet": { // amount the receiver gets (amount - fees)
        "formatted": "0.737055",
        "value": "737055"
      },
      "totalFees": {
        "formatted": "0",
        "value": "0"
      },
      "fees": [],
      // what was charged/invoice to the payer
      "invoiceAmount": "1",
      "invoiceCurrency": "CAD",	
      "conversion": "chainlink:CADUSD",
      "priceFeeds": [
        {
          "name": "CADUSD",
          "contract": "0xf6DA27749484843c4F02f5Ad1378ceE723dD61d4",
          "rate": "0.7370555"
        }
      ],
      // whether a sufficient number of blocks have passed for the tx to be considered final
      // see Finality section
      "final": true
      "verified": true,
      "verificationErrors": []
    }
  ]
}

Notes

It is technically possible that a (blockchain) transaction can contain mulitple YODL payments. Therefore the API endpoints return an array of payments.

Finality

There are multiple definitions out there for finality, some more strict than others. In order to be practical, we will look at the likelihood of a reorg after a certain number of transactions have passed.

Currently, the confirmations we use are as follows:

Types

These are likely to change and are provided as a snapshot to the current state of types.

export enum OnCompleteActionType {
  NOTHING = "NOTHING",
  REDIRECT = "REDIRECT",
  CLOSE_WINDOW = "CLOSE_WINDOW",
}

export type OnCompleteAction =
  | { type: OnCompleteActionType.NOTHING }
  | {
      type: OnCompleteActionType.REDIRECT;
      payload: {
        url: string;
      };
    }
  | {
      type: OnCompleteActionType.CLOSE_WINDOW;
      payload: {
        delayMilliseconds: number;
      };
    };

export type CoinConfig = {
  chainId: number;
  defaultAddress?: string;
  tokens: {
    symbol: string;
    address?: string;
  }[];
};

export type LinkConfig = {
  coins: CoinConfig[];
  onCompleteAction?: OnCompleteAction;
};

export type PriceFeed = {
  name: string;
  contract: string;
  rate: string;
};

export type LookupTxDetails = {
  chainId: number;
  txHash: string;
  memo: string;
  receiver: string;
  tokenSymbol: string;
  tokenAmountGross: string;
  tokenAmountNet: string;
  tokenAmountGrossNative: string;
  tokenAmountNetNative: string;
  yodlFee: string;
  invoiceAmount: string;
  invoiceCurrency: string;
  conversion: string;
  priceFeeds: PriceFeed[];
};

export type AccountsResponse = {
	address: string;
	config: LinkConfig;
	handle: string;
};

export type LookupResponse = LookupTxDetails[];

export type VerifyDetails = LookupDetails & {
	verified: boolean;
	verificationErrors: string[]
};

export type VerifyResponse = VerifyDetails[];

Last updated