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
:chainId*
String
:txHash*
String
Headers
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
Authorization*
String
API Key
Content-Type*
String
application/json
Request Body
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:
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[];Last updated