GuidesAPI ReferenceSDKsChangelog

Payin Integration

What Are Payins and Why They Matter

Payins enable your application to seamlessly accept fiat payments from your customers' bank accounts, which will be converted to cryptocurrency. Whether you're a developer or a business owner, this guide will help you integrate DollarPe's Payin system.

Prerequisites:

Warning: Initiate the payin before the quotation expiry time.

Integration at a Glance

The Payin integration flow for centralized exchanges involves the following key steps:

  1. Fetch Configurations - Retrieve the basic configuration to understand supported assets, networks, and limits.
  2. Validate user requirements – Ensure the customer has completed KYC verification, has at least one verified bank account added, and has at least one whitelisted wallet
  3. Fetch payin limits – Retrieve payin limits to check daily limits, available limits, and whether Enhanced Due Diligence (EDD) is required.
  4. Fetch exchange rates – Retrieve the latest cryptocurrency exchange rates
  5. Create a quotation – Generate a quote for the desired payin amount
  6. Send fiat payment – Transfer the fiat amount to the provided bank details
  7. Initiate the payin – Start the payin using the UTR from the fiat payment
  8. Monitor transaction status – Track the progress of the transaction
  9. Handle completion – Finalize the payin once the transaction is confirmed

Visual Integration Flow

Process Flow Diagram

Sequence Diagram: Detailed Process Flow

Step-by-Step Integration Guide

Step 1: Fetch Configurations

Before starting the integration, fetch the basic configuration to understand supported assets, networks, and limits:

GET /payin/configuration

{
"status": true,
"message": "Success",
"data": {
  "aud": {
    "supported_assets": [
      "usdt",
      "usdc"
    ],
    "supported_networks": {
      "usdt": [
        "polygon",
        "eth",
        "bsc",
        "sepolia",
        "solana",
        "tron",
        "arbitrum"
      ],
      "usdc": [
        "polygon",
        "eth",
        "bsc",
        "sepolia",
        "solana",
        "tron",
        "arbitrum"
      ]
    },
    "coin_limits": {
      "usdt": {
        "osko": {
          "min": 28,
          "max": 5563
        },
        "payId": {
          "min": 28,
          "max": 1113
        }
      },
      "usdc": {
        "osko": {
          "min": 28,
          "max": 5563
        },
        "payId": {
          "min": 28,
          "max": 1113
        }
      }
    },
    "required_risk_parameters": [
      "ip_address",
      "device_id"
    ]
  }
}
}

Key Fields:

  • supported_fiats: List of supported fiat currencies
  • supported_assets: List of supported cryptocurrencies
  • supported_networks: List of supported blockchain networks
  • coin_limits: Minimum and maximum limits for each supported cryptocurrency
  • required_risk_parameters: Require risk parameters that should be passed at quotation stage

If you are storing these configurations in your application to validate user inputs and display appropriate options, make sure to update this data periodically.

Step 2: Check Customer KYC, Bank Account, and Wallet status

Before initiating any payin, ensure the customer is KYC-verified, has a verified bank account, and has at least one whitelisted wallet.

GET /customer/{customer_id}
{
"status": true,
"message": "Success",
"data": {
  "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
  "customer_id": "550e8400-e29b-41d4-a716-446655440000",
  "account_number": "123456789012",
  "bsb": "123456789012",
  "pay_id": "johndoe@oksbi",
  "pay_id_type": "EMAIL",
  "bank_account_type": "PAYID",
  "bank_account_status": "VERIFIED",
  "failure_reason": "null"
}
}

GET /bank/list/{customer_id}
{
"status": true,
"message": "Success",
"data": {
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
      "customer_id": "550e8400-e29b-41d4-a716-446655440000",
      "account_number": "123456789012",
      "bsb": "123456789012",
      "pay_id": "johndoe@oksbi",
      "pay_id_type": "EMAIL",
      "bank_account_type": "PAYID",
      "bank_account_status": "VERIFIED",
      "failure_reason": "null"
    }
  ]
}
}

GET /wallet/list/{customer_id}
{
"status": true,
"message": "Success",
"data": {
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "4e6f1b20-a73c-11ec-b909-0242ac120002",
      "customer_id": "550e8400-e29b-41d4-a716-446655440000",
      "wallet_address": "0x1234567890123456789012345678901234567890",
      "wallet_status": "ACTIVE",
      "failure_reason": "null"
    }
  ]
}
}

Step 3: Check Payin Limit

Before creating a quotation, check the customer's available payin limit to ensure they are eligible to create a new order.

GET /payin/limit/{customer_id}

{
  "status": true,
  "message": "Success",
  "data": {
    "daily_limit": 10000,
    "available_limit": 10000,
    "payment_method_limits": {
        "per_transaction_limit": {
            "OSKO": 10000,
            "PAYID": 10000
        },
        "total_available_limit": {
            "OSKO": 10000,
            "PAYID": 10000
        }
    },
    "full_limit_reset_timestamp": "2024-03-13T10:00:00Z",
    "is_edd_required": false,
    "is_limit_increase_available": true
  }
}

Key Fields:

  • maximum_daily_limit: The maximum daily payin limit for the customer
  • available_daily_limit: The remaining payin limit for the day
  • is_edd_required: If true, the customer must complete Enhanced Due Diligence (EDD) before proceeding

How to use:

  • If available_daily_limit is sufficient for the intended transaction and is_edd_required is false, proceed to the next step.
  • If is_edd_required is true and the limit is not available, direct the user to complete EDD as part of the KYC process before proceeding. After EDD, recheck the limit.
  • If is_edd_required is false and the limit is not available (i.e., user has already completed EDD and limit is still exhausted), do not allow the user to create a new payin order and show an appropriate error message. No further action is possible until the limit resets.

Step 4: Fetch Exchange Rate

Get the real-time exchange rate for a given crypto asset.

GET /payin/fetch-rate
{
  "asset": "usdt",
  "fiat": "aud",
  "network": "bsc",
}

{
  "status": true,
  "message": "Success",
  "data": {
    "asset": "USDT",
    "fiat": "AUD",
    "network": "BSC",
    "rate": 1.51
  }
}

Key Fields:

  • asset: Cryptocurrency to be received (e.g., "USDT", "USDC")
  • fiat: Fiat currency to send (e.g., "AUD" for Australian Dollar)
  • network: Network on which crypto will be settled (e.g., "BSC")
  • rate: Current exchange rate (amount of fiat per 1 unit of crypto)

Rates fluctuate constantly based on market conditions. We recommend fetching a new rate before each transaction to ensure accuracy.

Step 5: Create a Quotation

After getting the current rate, create a quotation to lock in the rate.

POST /payin/quotation
{
    "asset": "USDC",
    "fiat": "AUD",
    "network": "BSC",
    "sending_amount": "1000",
    "customer_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
    "bank_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
    "payment_method": "OSKO",
    "risk_parameters": {
        "ip_address": "127.0.0.1",
        "device_id": "",
    }
}

{
  "status": true,
  "message": "Success",
  "data": {
      "id": "da43453c-f854-42ac-9a1e-619b37060bbc",
      "customer_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
      "bank_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
      "asset": "USDC",
      "fiat": "AUD",
      "payment_method": "OSKO",
      "sending_amount": 1000.00,
      "rate": 1.51,
      "receiving_amount": 662.25,
      "quotation_fee": {
          "client_fee": 0.00,
          "client_fee_usdt": 0.00,
          "dollarpe_fee": 0.00,
          "pg_fee": 0.00,
          "gross_effective_exchange_rate": 1.51
      },
      "deposit_instructions": {
          "account_number": "1234567890",
          "bsf": "1234567890"
      },
      "created_at": "2025-04-17T14:10:27.567448+00:00",
      "expiry_time": "2025-04-17T14:20:27.566842+00:00"
  }
}

Key Fields:

  • asset: Cryptocurrency to be received
  • fiat: Fiat currency to send (e.g., "AUD" for Australian Dollar)
  • receiving_amount: Amount in cryptocurrency to receive
  • customer_id: ID of the KYC-verified customer
  • bank_id: ID of the verified bank account
  • bank_details: Bank account details for sending the fiat payment
  • expiry_time: Time until the quotation expires

You must complete your transaction before this time expires.

Step 6: Send Fiat Payment

Once you have the quotation and bank details, instruct the customer to send the fiat payment:

  1. Use the provided bank account details to make the payment
  2. Ensure the exact amount is sent as specified in the quotation
  3. Keep the UTR (Unique Transaction Reference) from the bank
  4. Complete the payment before the quotation expires

Step 7: Initiate the Payin

After the fiat payment is completed, create a payin request with the unique transaction number

POST /payin/initiate
{
  "quotation_id": "2e104290-07c8-49f1-a5ca-0d27f0078f8a",
  "customer_id": "def8b740-99f9-4cba-bc9e-99de57e927b4",
  "client_reference_id": "testUser123",
}

{
  "status": true,
  "message": "Success",
  "data": {
      "id": "9e67356c-cf5e-4fa2-958f-411e7607a307",
      "customer_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
      "quotation_id": "da43453c-f854-42ac-9a1e-619b37060bbc",
      "client_reference_id": "payin_first_test_3",
      "status": "PROCESSING",
      "created_at": "2025-04-17T14:11:35.504428Z",
      "asset": "USDC",
      "fiat": "AUD",
      "payment_method": "OSKO",
      "sending_amount": 1000.00,
      "dollarpe_rate": 1.51,
      "receiving_amount": 662.25,
      "deposit_instructions": {
          "bsf": "1234567890",
          "account_number": "1234567890"
      },
      "fees": {
          "client_fee": "0.00",
          "client_fee_usdt": "0.00",
          "dollarpe_fee": "0.00",
          "pg_fee": "0.00",
          "gross_effective_exchange_rate": 1.51
      }
  }
}

Key Fields:

  • quotation_id: ID received from Step 3
  • customer_id: ID of the KYC-verified customer
  • client_reference_id: Your internal reference ID for tracking (optional)
  • bank_id: ID of the verified bank account
  • status: Current status of the payin

Step 8: Monitor Transaction Status

After initiating the payin, you need to track the payin status. There are two ways to monitor this status:

Option A: Webhook Integration (Recommended)

Webhooks provide real-time updates about payin status changes. Configure your webhook endpoint to receive these notifications:

// Sample webhook payload for payin status updates
{
  "type": "PAYIN",
  "id": "ac7c5360-0b57-4fb7-88f2-df1c371930ee",
  "event": "COMPLETED", // or "FAILED", "PROCESSING"
  "failure_reason": null, // Contains failure reason if status is "FAILED"
  "timestamp": "2025-03-21T13:37:53.208137Z",
  "metadata": {}
}

If using webhooks, ensure your server acknowledges receipt with a 200 OK response to prevent duplicate notifications.

Option B: Status Polling

If webhooks aren't feasible, you can periodically check the status using the payin endpoint:

GET /payin/{payin_id}

{
  "status": true,
  "message": "Success",
  "data": {
      "id": "ac7c5360-0b57-4fb7-88f2-df1c371930ee",
      "quotation_id": "c9f343b5-ff56-4d52-93af-0962f75242b7",
      "customer_id": "8da49e5e-33d1-48b2-b107-eb34f851b2fd",
      "client_reference_id": "payin_first_test",
      "bank_id": "c863b696-7fbd-4b16-b3a7-134aefffb2fe",
      "asset": "USDT",
      "network": "BSC",
      "fiat": "AUD",
      "sending_amount": "1510.00",
      "rate": "1.51",
      "receiving_amount": "1000.00",
      "fees": {
          "client_fee": "0.00",
          "client_fee_usdt": "0.00",
          "dollarpe_fee": "0.00",
          "pg_fee": "0.00",
          "gross_exchange_rate": ""
      },
      "status": "PROCESSING",
      "failure_reason": "",
      "created_at": "2025-03-21T13:37:53.208137Z",
      "updated_at": "2025-03-21T13:37:53.208142Z"
  }
}

If using the polling approach, we recommend checking no more frequently than once every 60 seconds to avoid API rate limits.

Possible Status Values:

  • PROCESSING: Initial state, waiting for payment verification
  • SUCCESS: Payin has been successfully completed
  • FAILED: Payin has failed and failure_reason is updated

Step 9: Handle Transaction Completion

Successful Transactions

When a payin is completed successfully:

  1. Update your internal records with the transaction details
  2. Notify your user that the funds have been received
  3. Store the transaction details for future reference and customer support

Testing Your Integration

Sandbox Environment

Before going live, test your integration thoroughly in our sandbox environment:

  1. Use the base URL: https://sandbox.dollarpe.xyz
  2. Follow the same steps as production
  3. Test both successful and failed transaction scenarios

In the sandbox environment, you can simulate different failure scenarios by using specific test values. Refer to our Sandbox Testing Guide for details.

Getting Help

If you encounter any issues with your payin integration:

Our support team is available 24/7 to help with integration issues. For urgent matters, use the in-app chat or call our technical support hotline.