APIs

The ultimate guide to integrate DePay APIs.

APIs to access blockchain data like payment tracking, tokens, decentralized exchange information, 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.


Authentication

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

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

API Test Key

ONLY USE THIS KEY FOR TESTING PURPOSES. DO NOT USE THIS KEY FOR ANY LIVE SYSTEMS: 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 payment changes status from pending to either success or error.

Even though we recommend to setup callbacks you can also repeat the same request to retrieve the latest information for a given payment. 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

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 expect payment amount (as decimal number).

e.g. 102.2

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

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 "error".

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

uuid

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

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

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": "4d4cd30f-d393-40f0-b909-85578a722ad7"
}

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": "4d4cd30f-d393-40f0-b909-85578a722ad7",
  "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 error.

Payment callback

Once a payment changes state from pending to either success or error 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/forward 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": "4d4cd30f-d393-40f0-b909-85578a722ad7",
  "callback": "https://webhook.site/4d4cd30f-d393-40f0-b909-85578a722ad7",
  "confirmed_at": "2021-11-25T12:54:52.332Z",
  "created_at": "2021-11-25T11:17:13.833Z",
  "updated_at": "2021-11-25T12:54:52.334Z"
}

Forward 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/forward once you're done preparing your system for forwarding the user back to you.

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

Forwards users to configured forward_to (which you can set upon payment creation) to continue flow after payment has been confirmed.

Required parameters

blockchain

The name of the blockchain.

e.g. ethereum

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

Example request body

{
  "blockchain": "ethereum",
  "transaction": "0xd4a9424440f6010af1bec311dda4e23d4f0016f4cc215da84a41650150ecb8b7",
  "sender": "0x29b0d4cb9cffeb360067199cf026dfd4854a8ab0",
  "nonce": 1
}

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

Support

Need additional help
?

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

Ask the community
Open an issue
Start a conversation