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

NameTypeDescription

:chainId*

String

:txHash*

String

Headers

NameTypeDescription

Authorization*

String

API Key

{
  "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

NameTypeDescription

Authorization*

String

API Key

Content-Type*

String

application/json

Request Body

NameTypeDescription

chainId*

number

id of the chain on which the transaction took place

txHash*

string

transaction hash

invoiceAmount*

number/string

amount of the invoice with decimals eg. 1.23

invoiceCurrency*

string

uppercase currency for the invoice eg. USD

address*

string

receiver address or yodl.me handle

{
  "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:

Chain NameChain IdConfirmationsDuration

Mainnet

1

3

~36 seconds

Optimism

10

48

~96 seconds

Gnosis

100

1

~5 seconds

Polygon

137

50

~100 seconds

Arbitrum One

42161

1600

~8 minutes

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[];
PreviousSmart ContractsNextWebhooks

Last updated