Paywithcrypto – Cashonrails Documentation

Pay with Crypto

Overview

Pay with Crypto allows customers to make payments using various cryptocurrencies and digital tokens, providing a secure and decentralized payment option.

Base URL

https://api.cashonrails.com/api/v1/s2s

Integration Steps

1. Get Available Tokens

First, retrieve the list of supported cryptocurrency tokens:


curl -X GET '{{baseurl}}/paywithcrypto/list' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Response


[
    {
        "name": "Bitcoin",
        "code": "bitcoin",
        "symbol": "BTC",
        "network": "Bitcoin"
    },
    {
        "name": "Ethereum",
        "code": "ethereum",
        "symbol": "ETH",
        "network": "Ethereum"
    },
    {
        "name": "Tron",
        "code": "tron",
        "symbol": "TRX",
        "network": "Tron"
    },
    {
        "name": "USDT (TRC20)",
        "code": "usdt_trc20",
        "symbol": "USDT",
        "network": "Tron"
    }
]

2. Initialize Payment

Make a POST request to initialize the cryptocurrency payment:


curl --location '{{baseurl}}/paywithcrypto/initialize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data-raw '{
    "email": "customer@email.com",
    "amount": "100",
    "currency": "USDT",
    "reference": "s2sref_2858705278271676",
    "code": "tron"
}'

Request Parameters

Parameter	Type	Required	Description
email	string	Yes	Customer’s email address
amount	string	Yes	Amount to charge in the specified currency
currency	string	Yes	Cryptocurrency code (e.g., USDT, USDC)
reference	string	Yes	Unique transaction reference
code	string	Yes	Crypto token code from step 1

Sample Response


{
    "success": true,
    "message": "Address Assigned",
    "data": {
        "address": "0xb8137ef45a3baedab4543fcee92429c90bc377c2",
        "label": "eth_1348261105",
        "blockchain": "ETH",
        "network": "ERC20",
        "name": "Ethereum"
    },
    "_links": {
        "url": "https://api.cashonrails.com/api/v1/checkout/verify-transaction/unique-ref-er34r4eaaaae",
        "method": "GET"
    }
}

3. Customer Payment Process

The customer needs to send the cryptocurrency to the provided wallet address. They can:

Copy the wallet address from the response
Use their crypto wallet to send the payment
Send the exact amount in the specified cryptocurrency

Ensure customers send the payment to the correct address and on the correct network (e.g., ERC20 for Ethereum tokens).

4. Verify Transaction

Use the verification URL provided in the _links object or verify using the standard endpoint:


curl -X GET '{{baseurl}}/transaction/verify/{reference}' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

You can also use the direct verification link from the response:


curl -X GET 'https://api.cashonrails.com/api/v1/checkout/verify-transaction/{reference}' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Success Response


{
    "status": true,
    "message": "Transaction verified successfully",
    "data": {
        "reference": "s2sref_2858705278271676",
        "amount": "100",
        "currency": "USDT",
        "status": "success",
        "payment_method": "cryptocurrency",
        "blockchain": "ETH",
        "network": "ERC20",
        "address": "0xb8137ef45a3baedab4543fcee92429c90bc377c2",
        "transaction_hash": "0x1a2b3c4d5e6f...",
        "confirmations": 12,
        "transaction_date": "2024-02-21T12:34:56Z"
    }
}

Sample Pending Response


{
    "status": true,
    "message": "Transaction is being processed",
    "data": {
        "reference": "s2sref_2858705278271676",
        "status": "pending",
        "confirmations": 3,
        "required_confirmations": 6,
        "transaction_hash": "0x1a2b3c4d5e6f..."
    }
}

Sample Failed Response


{
    "status": false,
    "message": "Transaction failed",
    "data": {
        "reference": "s2sref_2858705278271676",
        "status": "failed",
        "reason": "Payment expired or insufficient amount"
    }
}

Crypto transactions require network confirmations and may take several minutes to complete. Always verify the transaction status before confirming payment to the customer.

5. Cancel Transaction

You can cancel a transaction that is still pending:


curl -X GET {{baseurl}}/transaction/cancel/{reference} \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Replace {reference} with your transaction reference.

Cancel Transaction Response

Success Response:


{
    "success": true,
    "message": "Transaction cancelled successfully",
    "data": {
        "reference": "s2sref_2858705278271676",
        "status": "cancelled",
        "amount": "100",
        "currency": "USDT",
        "cancelledAt": "2024-02-21T12:34:56Z"
    }
}

Cancellation Rules

Only pending transactions can be cancelled
Once crypto is sent to the wallet address, the transaction cannot be cancelled
Expired transactions are automatically cancelled
Completed transactions cannot be cancelled (contact support for refunds)

Supported Cryptocurrencies

Token	Symbol	Network	Confirmation Time
Bitcoin	BTC	Bitcoin	15-30 minutes
Ethereum	ETH	Ethereum	2-5 minutes
Tron	TRX	Tron	1-3 minutes
USDT (TRC20)	USDT	Tron	1-3 minutes
USDT (ERC20)	USDT	Ethereum	2-5 minutes

Best Practices

Address Verification: Always display the exact wallet address to customers
Network Confirmation: Ensure customers send on the correct network (ERC20, TRC20, etc.)
Confirmation Monitoring: Check confirmation status for pending transactions
Status Polling: Check transaction status periodically for pending payments
Error Handling: Implement proper handling for failed or expired transactions

Important Notes

Crypto payments are irreversible once confirmed on the blockchain
Network congestion may affect confirmation times
Always validate the exact crypto amount and network before sending
Use the verification link provided in the response for real-time status updates