Deposit Flow

With deposit flow, you can let your users deposit money into their accounts, keep track of user balances, and charge them for your services later.

Note that repaya is not at any time in control or has any possession of your or your customer's funds. You are fully responsible and in control of your users' funds handling and custody.

The algorithm of user deposits generally consists of two steps

1. Payment processing

At this step, you set up a payment request integration with repaya to let your customer make a payment to their balance.

2. Getting user balance

After you have successfully received payment, you can request user balances from repaya. From now on, repaya is only tracking the number of funds deposited, so you will need to set up some further billing processes to deduct from the user balance when the user performs a purchase or pays for a service in your app.

Payment Form

Set up a Payment Request form and fill in the necessary details:

Title (for example, "Deposit to App")
Coins that you accept for payment
Your receiving blockchain address
Your return URL. This is the address on your website to redirect customers after they complete the payment.

Backend Integration

To build the deposit flow on your site, you will need to make three things happen from your server:

Create a payment session and redirect users by the URL you get from repaya API
Check payment status
Request user balance and display it to the user

1. Create a payment session

Perform a request to repaya's Rest API to create a payment session. Set the id of the customer field to the corresponding user ID in your own database to be able to match them after the payment is complete. Use the checkoutUrl field from the response to redirect your user.

Create payment session

post

/session

Create a payment session to initiate the checkout flow

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

formLinkIdstringRequiredExample: jAY7k

clientIdstringOptionalExample: key_1432

Responses

200

Payment session created

application/json

post

/session

POST /api/public/1/session HTTP/1.1
Host: repaya.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 194

{
  "formLinkId": "jAY7k",
  "customer": {
    "id": "user_123141",
    "data": "text"
  },
  "product": {
    "id": "product_123141",
    "name": "Awesome product",
    "data": "text"
  },
  "price": {
    "USD_MULTI_1": "15.0"
  },
  "clientId": "key_1432"
}

200

Payment session created

{
  "checkoutUrl": "https://repaya.io/checkout/id_124124",
  "id": "id_124124",
  "formLinkId": "jAY7k",
  "receiver": "0x0000000000000000000000000000000000000000",
  "customer": {
    "id": "user_123141"
  },
  "product": {
    "id": "product_123141",
    "name": "Awesome product"
  },
  "price": {
    "USD_MULTI_1": "15.0"
  },
  "clientId": "key_1432"
}

2. Verify payment

When the payment is completed, the customer will be redirected to your website on the return URL you provided during the payment form setup. Verify the payment status at this step by requesting it via the API. The sessionId for the request will be provided to you in the query parameter of the return URL.

Save the resulting payment in your DB if you want to enumerate all the customer payments later or use them another way.

Get customer's payment in the given session

get

/payment

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

sessionIdstringRequired

Payment session ID

Example: id_124124

Responses

200

A payment associated with a given session, null if missing

application/json

get

/payment

GET /api/public/1/payment?sessionId=id_124124 HTTP/1.1
Host: repaya.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

A payment associated with a given session, null if missing

{
  "id": "pid_3251",
  "customer": {
    "id": "user_123141",
    "data": "text"
  },
  "product": {
    "id": "product_123141",
    "name": "Awesome product",
    "data": "text"
  },
  "sender": "0x0000000000000000000000000000000000000000",
  "receiver": "0x0000000000000000000000000000000000000000",
  "amount": "15.0",
  "paidAmount": "5.0",
  "status": "pending",
  "coin": {
    "code": "USD_MULTI_1",
    "name": "USD Stablecoins"
  }
}

3. Request user balances

After the payment, you can finally request the user balance from repaya.

Get customer balances

get

/balance

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

formLinkIdstringRequired

Payment form ID

Example: jAY7k

customerIdstringOptional

Filter by customer, pass an empty string to get the total balance

Example: user_123141

productIdstringOptional

Filter by product, pass an empty string to get the total balance

Example: product_123141

coinstringOptional

Filter by coin

Example: USD_MULTI_1

Responses

200

List of customer balances

application/json

get

/balance

GET /api/public/1/balance?formLinkId=jAY7k HTTP/1.1
Host: repaya.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of customer balances

[
  {
    "customerId": "user_123141",
    "productId": "product_123141",
    "balance": "123.08",
    "coin": {
      "code": "USD_MULTI_1",
      "name": "USD Stablecoins"
    }
  }
]

To let your users purchase products in your app or pay for services, you need to establish some billing process and keep track of the number of funds you deducted from user balances. Then the final user balance will be the sum of balances from repaya and the ones from your backend or database.

1. Payment processing

2. Getting user balance

Payment Form

Backend Integration

1. Create a payment session

Create payment session

2. Verify payment

Get customer's payment in the given session

3. Request user balances

Get customer balances

See also