APIs

The ultimate guide to integrate DePay APIs.

APIs to access blockchain data like payment tracking, tokens, accounts, prices etc.


Introduction

You will be able to test and explore DePay APIs with our API test key. For an integration into your production systems we need to ask you to issue an API key dedicated to your integration.

JSON API

Make sure to set the Content-Type header to application/json at all times:

Content-Type: application/json


Authentication

In order to authenticate towards our APIs you need an API key.

API Key Limitations

Every API Key is limited to max. 10 requests/second , 10 requests in parallel and 14'400 requests/day.

API Test Key

For testing purposes, DePay provides a public API key which is not recommended for any systems in production, as it's shared with the public and heavily rate-limited. We also rotate the public api key on a recurring basis.

ONLY USE THIS KEY FOR TESTING PURPOSES M5dZeHFfIp3J7h9H9fs4i4wmkUo1HjAF3EmMy32c

Set x-api-key header

In order to authenticate towards DePay's apis, you need to pass your API Key via the x-api-key header:

x-api-key: M5dZeHFfIp3J7h9H9fs4i4wmkUo1HjAF3EmMy32c


Payments

POST

https://api.depay.fi/v2/payments

Allows to track payments on decentralized blockchain networks.

Returns 201 if payment was created from scratch.
Returns 200 if payment already existed before.

This method implements idempotency. It will not create multiple trackers but will continue to provide the information for the given payment if the request is executed repeatedly.

We recommend to setup a callback to have the payment tracker call your systems once payments change status from pending to either success or failed.

Even though we recommend to setup callbacks you can also retrieve the payment status via GET https://api.depay.fi/v2/payments/{uuid}. Just make sure you don't run into API call limitations that way and use reasonable pauses between requests (we recommend 1 minute polling).

Required parameters

blockchain

The name of the blockchain.

e.g. ethereum , bsc

transaction

The transaction id expected to perform the payment.

e.g. 0xb6f777051f6701696e410fca7acbd3d14c06a53e

sender

The address of the sender.

e.g. 0x1db3439a222c519ab44bb1144fc28167b4fa6ee6

nonce

The sender nonce of the expected payment transaction.

e.g. 5

receiver

The receiver address of the expected payment.

e.g. 0xab5801a7d398351b8be11c439e05c5b3259aec9b

token

Address of the token expected as received payment (will be downcased internally).

e.g. 0xdac17f958d2ee523a2206206994597c13d831ec7

amount

Human readable expected payment amount (as string, to prevent rounding issues).

e.g. "102.20"

confirmations

The amount of confirmations required before considering a payment succesful.

e.g. 13

after_block

The block after which to expect the payment to happen. The current block right before the payment was submitted. Required to scan for replaced payment transactions.

e.g. 13542983

uuid

Secret uuid referencing the payment identifcator in your system. Do not expose this to the public! UUID needs to be unguessable!

e.g. 74417770-e6ac-4ae8-b027-0657600d7bad

Optional parameters

callback

Secret callback url. Needs to be hidden from the public. UUID needs to be unguessable. Will be called once the payment status completes either with success or failed.

e.g. https://example.com/payments/74417770-e6ac-4ae8-b027-0657600d7bad

payload

Allows to store additional, limited, payload information alongside the payment.

e.g. {"somekey": "somevalue"}

forward_to

URL used to forward users to once payment tracking is completed.

e.g. https://example.com/continue/after/74417770-e6ac-4ae8-b027-0657600d7bad

fee_amount

Human readable expected payment fee amount (if fee has been configured) as string, to prevent rounding issues.

e.g. "1.0220"

fee_receiver

The receiver address of the fee (if fee has been configured).

e.g. 0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02

Example request body

{
  "blockchain": "ethereum",
  "transaction": "0xd4a9424440f6010af1bec311dda4e23d4f0016f4cc215da84a41650150ecb8b7",
  "sender": "0x29b0d4cb9cffeb360067199cf026dfd4854a8ab0",
  "nonce": 1,
  "receiver": "0x29b0d4cb9cffeb360067199cf026dfd4854a8ab0",
  "token": "0xa0bed124a09ac2bd941b10349d8d224fe3c955eb",
  "amount": "822.5",
  "confirmations": 13,
  "after_block": 13609144,
  "callback": "https://webhook.site/4d4cd30f-d393-40f0-b909-85578a722ad7",
  "forward_to": "https://example.com/continue/after/74417770-e6ac-4ae8-b027-0657600d7bad",
  "payload": { "somekey": "somevalue" },
  "uuid": "74417770-e6ac-4ae8-b027-0657600d7bad"
}

Example response body

{
  "status": "pending",
  "blockchain": "ethereum",
  "transaction": "0xd4a9424440f6010af1bec311dda4e23d4f0016f4cc215da84a41650150ecb8b7",
  "sender": "0x29b0d4cb9cffeb360067199cf026dfd4854a8ab0",
  "nonce": 1,
  "receiver": "0x29b0d4cb9cffeb360067199cf026dfd4854a8ab0",
  "token": "0xa0bed124a09ac2bd941b10349d8d224fe3c955eb",
  "confirmations": 13,
  "after_block": 13609144,
  "amount": "822.5",
  "payload": {
      "somekey": "somevalue"
  },
  "uuid": "74417770-e6ac-4ae8-b027-0657600d7bad",
  "callback": "https://webhook.site/4d4cd30f-d393-40f0-b909-85578a722ad7",
  "forward_to": "https://example.com/continue/after/74417770-e6ac-4ae8-b027-0657600d7bad",
  "confirmed_at": null,
  "created_at": "2021-11-25T11:17:13.833Z",
  "updated_at": "2021-11-25T11:17:13.833Z"
}

Status can either be pending , success or failed.

In case a payment failed it will also provide a failed_reason which can be one of the following: FAILED , MISMATCH , TRANSACTION_MISMATCH , TOKEN_MISMATCH , SENDER_MISMATCH , RECEIVER_MISMATCH , NONCE_MISMATCH , AMOUNT_MISMATCH , TRACKING_TIMED_OUT (After 24h of unsuccessful tracking).

Payment callback

Once a payment changes state from pending to either success or failed your system will retrieve a callback if callback was provided upon payment creation.

The callback request uses the POST http method.

Make sure your system responds with a success status code upon receiving our callback.

Respond with 200 if your system is ready immediatelly upon response to handle the redirected user to perform next steps in your system.

Respond with 202 if your system accepts the callback, but is performing background jobs that need to be finished before the user is supposed to be redirected to the next step in your system.
In this case you need to make sure to call POST /payments/release once you're done with background processing the payment and once your systems are ready to handle the redirected user to perform next steps.

Other codes but 200 or 202 will be considered a failed callback and will be retried up to 25 times over approx. 21 days.

Make sure you evaluate the status of the payment callback in order to decide what to do in your systems next.

Payment callbacks will retry failures with your system with an exponential backoff using the formula (retry_count ** 4) + 15 + (rand(30) * (retry_count + 1)) (i.e. 15, 16, 31, 96, 271, ... seconds + a random amount of time).

It will perform 25 retries over approx. 21 days. After that you will need to retrieve the data for the payment from your systems with another payment request.

Example callback body

{
  "status": "success",
  "blockchain": "ethereum",
  "transaction": "0xd4a9424440f6010af1bec311dda4e23d4f0016f4cc215da84a41650150ecb8b7",
  "sender": "0x29b0d4cb9cffeb360067199cf026dfd4854a8ab0",
  "nonce": 1,
  "receiver": "0x29b0d4cb9cffeb360067199cf026dfd4854a8ab0",
  "token": "0xa0bed124a09ac2bd941b10349d8d224fe3c955eb",
  "confirmations": 13,
  "after_block": 13609144,
  "amount": "822.5",
  "payload": {
    "somekey": "somevalue"
  },
  "uuid": "74417770-e6ac-4ae8-b027-0657600d7bad",
  "callback": "https://webhook.site/74417770-e6ac-4ae8-b027-0657600d7bad",
  "confirmed_at": "2021-11-25T12:54:52.332Z",
  "created_at": "2021-11-25T11:17:13.833Z",
  "updated_at": "2021-11-25T12:54:52.334Z"
}

Release users

In case you need to perform background processing upon payment confirmation callback and have responded with 202 upon our callback, you need to make sure that you call POST /payments/release once you're done preparing your system for forwarding the user back to you. You can request to release the user back to you by calling:

POST https://api.depay.fi/v2/payments/release

Forwards users to configured forward_to (which you can set upon payment creation) to continue flow after payment has been confirmed. If forward_to is not set, the payment widget will turn into "completed state" and allows the user to close the payment widget.

Required parameters

blockchain

The name of the blockchain.

e.g. ethereum , bsc

transaction

The transaction id expected to perform the payment.

e.g. 0xb6f777051f6701696e410fca7acbd3d14c06a53e

sender

The address of the sender.

e.g. 0x1db3439a222c519ab44bb1144fc28167b4fa6ee6

nonce

The sender nonce of the expected payment transaction.

e.g. 5

uuid

Secret uuid referencing the payment identifcator in your system. Do not expose this to the public! UUID needs to be unguessable!

e.g. 74417770-e6ac-4ae8-b027-0657600d7bad

Example request body

{
  "blockchain": "ethereum",
  "transaction": "0xd4a9424440f6010af1bec311dda4e23d4f0016f4cc215da84a41650150ecb8b7",
  "sender": "0x29b0d4cb9cffeb360067199cf026dfd4854a8ab0",
  "nonce": 1,
  "uuid": "74417770-e6ac-4ae8-b027-0657600d7bad"
}

Make sure to re-attempt the POST /payments/release request in case the request fails or returns anything but a 200.

Ensure user release/flow 100%

In certain scenarios in which websockets fail to deliver messages to your users, so that they can be released due to succefuly payment, DePay offers an additional way to control user flow/release. In order to increase resilience implement an additional endpoint into you systems the payment widget can poll information from to decide when to release the user and forward him/her to the next step in your payment flow/process.

This requires you to configure your payment widget with track and track.poll

For example:

DePayWidgets.Payment({
  ...,
  track: {
    endpoint: '/payments/track'
    poll: {
      endpoint: '/payments/release'
    }
  }
})

Both endpoints will be called from the payment widget with a POST request containing the following body:

{
  "blockchain": "ethereum",
  "transaction": "0x4311a9820195c2a5af99c45c72c88848ed403a4020863c913feed81d15855ae4",
  "sender": "0x769794c94e9f113e357023dab73e81dbd6db201c",
  "nonce": 103,
  "after_block": 13230369,
  "to_token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}

While the track.endpoint /payments/track expects you to call the payments api to initiate the tracker, the track.poll.endpoint /payments/release expects you to tell the widget when to release the user to the next step in your payment processing flow.

The payment widget will call /payments/release every 5 seconds and your endpoint needs to either respond with status 404 if the user is not to be released, or with a 200 if user is to be released. Once the user has been released the payment widget displays that the payment confirmation has been stored succefully and it allows the user to close the widget.

If you need to forward the user to the next step in your payment processing flow your poll.endpoint needs to respond with the following body upon release:

{
  "forward_to": "/next_step/123"
}

Show Payment

Fetches payment for give uuid:

GET https://api.depay.fi/v2/payments/45b55d24-60d0-45ba-9800-c61835494dc8-3

Example response body

{
  "status": "success",
  "blockchain": "bsc",
  "transaction": "0x2c8db4f5a4b0cd18f0e5e9e060060753a1928e6b39cac3e24a686bba2700863d",
  "sender": "0xe5f9c386c96912210d03a66b72a908b9b3706511",
  "nonce": 15,
  "receiver": "0xe5f9c386c96912210d03a66b72a908b9b3706511",
  "token": "0x55d398326f99059ff775485246999027b3197955",
  "confirmations": 2,
  "after_block": 14466705,
  "amount": "1.00",
  "payload": null,
  "uuid": "45b55d24-60d0-45ba-9800-c61835494dc8-3",
  "callback": "https://webhook.site/45b55d24-60d0-45ba-9800-c61835494dc8",
  "release": null,
  "forward_to": null,
  "confirmed_at": "2022-01-25T14:01:04.774Z",
  "created_at": "2022-01-25T14:01:00.909Z",
  "updated_at": "2022-01-25T14:01:04.775Z"
}

Status can either be pending , success or failed.

In case a payment failed it will also provide a failed_reason which can be one of the following: FAILED , MISMATCH , TRANSACTION_MISMATCH , TOKEN_MISMATCH , SENDER_MISMATCH , RECEIVER_MISMATCH , NONCE_MISMATCH , AMOUNT_MISMATCH , TRACKING_TIMED_OUT (After 24h of unsuccessful tracking).


Assets

GET https://api.depay.fi/v2/accounts/{blockchain}/{account}/assets

Provides a list of assets for the given account on the given network.

Required parameters

blockchain

The name of the blockchain.

e.g. ethereum , bsc

account

The account id (address).

e.g. 0x1db3439a222c519ab44bb1144fc28167b4fa6ee6

Example response body

[
  { 
    "name": "Ether",
    "symbol": "ETH",
    "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "balance": "117419780000000000",
    "decimals":18,
    "type":"NATIVE"
  },
  {
    "name": "Tether USD",
    "symbol": "USDT",
    "address": "0x55d398326f99059ff775485246999027b3197955",
    "balance": "810446200000000000",
    "decimals": 18,
    "type":"20"
  }
]


Token Prices

GET https://api.depay.fi/v2/prices/{blockchain}/{token_address}

Provides live price in usd for give token address on given blockchain.

Required parameters

blockchain

The name of the blockchain.

e.g. ethereum , bsc

token_address

The address of the token. Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE for the native currency of the given blockchain e.g. ETH/Ether on ethereum, or Binance Coin/BNB on bsc etc.

e.g. 0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb

Example request

GET https://api.depay.fi/v2/prices/ethereum/0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb

Example response body

0.578212912312

Support

Need additional help
?

Feel free to reach out in order to get additional help:

Ask the community
Open an issue
Start a conversation