Onramps

This guide provides essential information for developers to implement onramp feature programmatically.

The onramp model

The onramp model is the data structure that represents a onramp transaction in Rampable. The following attributes are associated with the onramp model:

Every user only allowed to have 5 pending onramp transactions at any given moment. If you want to create more onramp transactions, you need to wait until the previous onramp transactions are expired or completed.

Properties

Name
id
Type
string
Description
24 alphanumeric, unique identifier for the onramp transaction.
Name
onrampId
Type
string
Description
UUID version 4, unique identifier for the onramp transaction.
Name
externalOrderId
Type
string
Description
The external order id, for payment reference.
Name
acceptanceMethod
Type
string
Description
Acceptance or payment method that choosen for paying the fiat money. See Reference
Name
receiver.id
Type
string
Description
Unique identifier of the receiver, consist of 24 charachter of alphanumeric.
Name
receiver.name
Type
string
Description
Name of the receiver.
Name
receiver.email
Type
string
Description
Email address of the receiver.
Name
receiver.walletAddress
Type
string
Description
Crypto wallet address of the receiver.
Name
feeDetail.rate_amount
Type
string
Description
The exchange rate between fiat currency and given crypto currency.
Name
feeDetail.total_fee_amount
Type
number
Description
The amount of fee in crypto currency.
Name
feeDetail.total_fee_amount_in_currency
Type
string
Description
The amount of fee in fiat currency.
Name
inputAmount
Type
number
Description
The amount of the onramp in the input currency. This value will have the same value as inputAmountExact
Name
inputAmountExact
Type
number
Description
The exact amount of the onramp in the input currency. This value will have the same value as inputAmount
Name
outputAmount
Type
number
Description
The amount of the onramp in the output currency. This value is the transaction amount before calculating the fee.
Name
outputAmountExact
Type
number
Description
The exact amount of the onramp in the output currency. This value is the transaction amount before calculating the fee.
Name
inputCurrency
Type
string
Description
The input currency (fiat) of the onramp transaction.
Name
outputCurrency
Type
string
Description
The output currency (crypto) of the onramp transaction.
Name
reason
Type
string
Description
The reason for the onramp transaction.
Name
description
Type
string
Description
The description for the onramp transaction.
Name
status
Type
string
Description
The status of the onramp transaction. This can be either pending, processing, completed, or failed.
Name
organizationId
Type
string
Description
Unique identifier for the organization associated with the onramp transaction.
Name
organizationName
Type
string
Description
The name of the organization associated with the onramp transaction.
Name
transactionHash
Type
string
Description
The transaction hash of the onramp transaction, this would be available after the transaction is paid.
Name
blockchain
Type
string
Description
The blockchain of the onramp transaction. (e.g. Ethereum)
Name
blockchainType
Type
string
Description
The blockchain type of the onramp transaction.(e.g. EVM)
Name
memo
Type
string
Description
The onramp transaction's memo, this might be required on some blockchain (e.g. Stellar).
Name
userId
Type
string
Description
The user id of the onramp transaction.
Name
cryptoId
Type
string
Description
The crypto currency and the blockchain of the onramp transaction. (e.g. usdt-polygon). See Reference
Name
expiredDate
Type
string
Description
The expired date of the onramp transaction. Using ISO 8601 format.
Name
createdAt
Type
string
Description
The date the onramp transaction was created. Using ISO 8601 format.
Name
updatedAt
Type
string
Description
The date the onramp transaction was last updated. Using ISO 8601 format.

GET/v1/onramp/quote

Quote

This endpoint allows you to get quote price for onramp transaction. To get quote price, you must provide amount, inputCurrency, outputCurrency.

Required attributes

Name
amount
Type
number
Description
The amount of the onramp transaction in the input currency.
Name
inputCurrency
Type
string
Description
The crypto id of the onramp transaction (e.g. "IDR"). See Reference
Name
outputCurrency
Type
string
Description
The currency of the onramp transaction (e.g. "usdt-polygon"). See Reference

Optional attributes

Name
withLimit
Type
boolean
Description
Using the withLimit means you can get the quote using only the client secret without having to include your user access token in request headers as well, which is useful for client-side applications.
It means there is no daily limit calculation applied for the quote based on the user's limits when you use withLimit equal to false (pure quote only).

Request

GET

/v1/onramp/quote

curl --location 'https://sandbox.rampable.co/v1/onramp/quote?amount=16000&inputCurrency=idr&outputCurrency=usdt-polygon' \

--header 'x-client-secret: d9659c0857a91ae28a59ce9f9a8155f1b37ba1df91d4b4a50b3ecbb9ecdc2667' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response

  {
    "statusCode": 200,
    "message": "getQuotePriceHandler successfully",
    "data": {
        "status": true,
        "acceptance_method": "",
        "onramp_service": "indodax",
        "coin": "usdt",
        "currency": "idr",
        "amount_in_crypto": 1.0218048114372003,
        "amount_in_currency": 16000,
        "rate_amount": 15658.56788,
        "total_fee_percentage": 1.25,
        "total_fee_amount": 0.012772560142965003,
        "total_fee_amount_in_currency": 200,
        "total_received_amount_in_crypto": 1.0090322512942353,
        "total_received_amount_in_currency": 15800.000000000002,
        "expiry_time": 10
    }
  }

GET/v1/onramp

List all onramp transactions

This endpoint allows you to retrieve a paginated list of all your onramp transactions. By default, a maximum of ten onramp transactions are shown per page.

Query Params attributes

Name
limit
Type
integer
Description
Limit the number of onramp transactions returned.
Name
page
Type
integer
Description
Specify the page number of the onramp transactions to retrieve.
Name
sort
Type
string
Description
Sort the onramp transactions by a specific field. You can sort by createdAt or updatedAt. By default, onramp transactions are sorted by createdAt. You can also sort in reverse order by adding a hyphen (-) before the field you want to sort by.
Name
search
Type
string
Description
Search for a onramp transaction by name or email.
Name
status
Type
string
Description
Filter onramp transactions by status. This can be either pending, processing, completed, or failed.
Name
reason
Type
string
Description
Filter onramp transactions by reason.
Name
minInputAmount
Type
number
Description
Filter onramp transactions by minimum input amount.
Name
maxInputAmount
Type
number
Description
Filter onramp transactions by maximum input amount.
Name
minOutputAmount
Type
number
Description
Filter onramp transactions by minimum output amount.
Name
maxOutputAmount
Type
number
Description
Filter onramp transactions by maximum output amount.
Name
organizationId
Type
string
Description
Filter onramp transactions by organization id.
Name
organizationName
Type
string
Description
Filter onramp transactions by organization name.
Name
blockchain
Type
string
Description
Filter onramp transactions by blockchain.
Name
receiverName
Type
string
Description
Filter onramp transactions by receiver name.

Request

GET

/v1/onramp

curl -X GET "https://sandbox.rampable.co/v1/onramp?search=&limit=10&status=expired&reason=" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Response

{
  "statusCode": 200,
  "message": "getOnrampHandler successfully",
  "data": {
      "docs": [
          {
              "feeDetail": {
                  "rate_amount": 15676.51352,
                  "total_fee_amount": 224.5397227839727,
                  "total_fee_amount_in_currency": 3520000.0000000005
              },
              "receiver": {
                  "id": "64914aXXXXXX6d801de2e35b",
                  "name": "Vicking",
                  "email": "vicking@gmail.com",
                  "phoneNumber": "",
                  "walletAddress": "0x9E79cDXXXXXX7F66451FXXXX77b6Fd732EXXXX"
              },
              "onrampId": "d3112216-897a-XXXX-XXXX-f5d5c9f0c644",
              "acceptanceMethod": "virtual_account_mandiri",
              "inputAmount": 10000,
              "inputAmountExact": 10000,
              "inputCurrency": "IDR",
              "outputCurrency": "usdt",
              "outputAmount": 0.6351903920125651,
              "outputAmountExact": 0.4954485057698008,
              "reason": "",
              "description": "",
              "status": "expired",
              "organizationId": "648XXfbf0a0XXXXee4XX2afc",
              "organizationName": "Some Organisation",
              "blockchain": "polygon",
              "routeId": "flashMobile",
              "externalOrderId": "1706273065XXXX6568",
              "expiredDate": "2024-01-26T12:54:25.707Z",
              "cryptoId": "usdt-polygon",
              "useSmartContract": false,
              "blockchainType": "EVM",
              "acceptanceDetail": {
                "trans_id": "ag9fbgc9feXXXXzbszs",
                "merchant_code": "FmXXXXXXXX",
                "order_id": "170627306XXXXX6568",
                "no_reference": "170627306XXXXX6568",
                "amount": "10000",
                "frontend_url": "https://app-dev.rampable.co/fm?data=eyJ0cmFuc19pXXXXXXXXXXX=",
                "fm_refnum": "ag9fbgc9XXXXa0zbszs",
                "payment_method": "va_mandiri",
                "va_number": "8998109XXXXX46568",
                "expired_time": "2024-01-26 19:54:25",
                "status_code": "201",
                "status_desc": "pending",
                "signature": "cdXXXXXXXXXXXX3a9a289ddfecd6a2e",
                "is_custom_page": true
              },
              "createdAt": "2024-01-26T12:44:25.724Z",
              "updatedAt": "2024-01-26T12:54:26.074Z",
              "id": "65b3a929b6b4XXXXXXX7f3dd0"
          },
          ....
      ],
      "totalDocs": 11,
      "offset": 0,
      "limit": 10,
      "totalPages": 2,
      "page": 1,
      "pagingCounter": 1,
      "hasPrevPage": false,
      "hasNextPage": true,
      "prevPage": null,
      "nextPage": 2
  }
}

GET/v1/onramp/detail/:onrampId

Onramp Transaction Detail

This endpoint allows you to retrieve a onramp transaction detail by onrampId.

Request

GET

/v1/:onrampId

  curl -X GET "https://sandbox.rampable.co/v1/onramp/detail/xxxxxxx" \
        -H "Authorization: Bearer YOUR_TOKEN"

Response

  {
    "statusCode": 200,
    "message": "getOnrampHandler successfully",
    "data": {
        "onrampId": "d27547ff-XXXX-XXXX-XXXX-c276b8730383",
        "acceptanceMethod": "virtual_account_bni",
        "feeDetail": {
          "rate_amount": 15676.51352,
          "total_fee_amount": 224.5397227839727,
          "total_fee_amount_in_currency": 3520000.0000000005
        },
        "receiver": {
            "id": "64c422d5e7XXXXXXXX",
            "name": "",
            "email": "",
            "phoneNumber": "",
            "walletAddress": "GDC2QXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        },
        "inputAmount": 16000,
        "inputAmountExact": 16000,
        "inputCurrency": "IDR",
        "outputCurrency": "usdc",
        "outputAmount": 1.0189502456147725,
        "outputAmountExact": 1.006213367544588,
        "reason": "Salary",
        "description": "Salary for January 2024",
        "status": "cancelled",
        "organizationId": "-",
        "organizationName": "-",
        "blockchain": "stellar",
        "userId": "XXXXXXXXXXXXXXX",
        "externalOrderId": "1706604XXXXXXXXX",
        "expiredDate": "2024-01-30T08:56:32.611Z",
        "cryptoId": "usdc-stellar",
        "useSmartContract": false,
        "blockchainType": "STELLAR",
        "memo": "",
        "activityHistory": [
            {
                "activity": "Paid by Payee",
                "status": "failed",
                "description": "Transaction has been cancelled",
                "_id": "65b8b894e70322c4c3fe6059",
                "updatedAt": "2024-01-30T08:51:32.615Z"
            },
            {
                "activity": "Converted to",
                "status": "failed",
                "description": "Transaction has been cancelled",
                "_id": "65b8b894e70322c4c3fe605a",
                "updatedAt": "2024-01-30T08:51:32.616Z"
            },
            {
                "activity": "Sent to recipient wallet",
                "status": "failed",
                "description": "Transaction has been cancelled",
                "_id": "65b8b894e70322c4c3fe605b",
                "updatedAt": "2024-01-30T08:51:32.616Z"
            },
            {
                "activity": "Received by recipient",
                "status": "failed",
                "description": "Transaction has been cancelled",
                "_id": "65b8b894e70322c4c3fe605c",
                "updatedAt": "2024-01-30T08:51:32.616Z"
            }
        ],
        "acceptanceDetail": {
            "trans_id": "ag9ff9dXXXXXXXXXX",
            "merchant_code": "FmXXXXXX",
            "order_id": "1706604XXXXXXXX",
            "no_reference": "1706604XXXXXXXX",
            "amount": "16000",
            "frontend_url": "https://app-dev.rampable.co/fm?data=XXXXXXXXXXXXXXXXXXXXXXM3YTIifQ==",
            "signature": "1f5ef0d30XXXXXXXXXXXXXXXXXXXX",
            "is_custom_page": false
        },
        "clientName": "Xellar",
        "clientId": "65383b6dXXXXXXXXXXXX",
        "createdAt": "2024-01-30T08:51:32.648Z",
        "updatedAt": "2024-01-30T08:56:32.951Z",
        "id": "65b8b894eXXXXXXXXXXXXXXX"
    }
  }

POST/v1/onramp

Create Onramp

This endpoint allows you to add a new transaction to your onramp transaction list in Rampable. To add a onramp transaction, you must provide their Rampable name and email also bank country and currency which automatically bind using recipient id.

Recipient must be created first before you get started with this endpoint. See Create Recipient for more information.

Required attributes

Name
receiverWalletAddress
Type
string
Description
The wallet address of the receiver.
Name
acceptanceMethod
Type
string
Description
The acceptance (payment of the fiat currency) method. See Reference
Name
paymentPhoneNumber
Type
string
Description
Phone number that woud be used on acceptance method of e-wallet.
Name
inputAmount
Type
number
Description
The amount of onramp transaction (fiat currency).
Name
inputCurrency
Type
string
Description
The input currency (fiat) of the onramp. See Reference
Name
outputCurrency
Type
string
Description
The crypto ID of the onramp. See Reference

Optional attributes

Name
reason
Type
string
Description
The reason for the onramp.
Name
description
Type
string
Description
The description for the onramp.
Name
memo
Type
string
Description
Memo that might be used on some blockchain network (e.g. Stellar).

After the create onramp process was done, the onramp will be in pending status. The onramp will be processed automatically after the payment page has been paid by user. If the offramp is successful, the status will be updated to processed.

Users need to send the fiat currency to payment detail provided on the acceptanceDetail

Request

POST

/v1/onramp

curl -X POST "https://sandbox.rampable.co/v1/onramp" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
    "receiverWalletAddress": "GDC2QZWDOW4IQXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "acceptanceMethod": "virtual_account_bni",
    "inputAmount": 16000,
    "paymentPhoneNumber": "08224XXXXXXXXX",
    "inputCurrency": "IDR",
    "outputCurrency": "usdc-stellar",
    "reason": "Test Create",
    "description": "Test create",
    "withLimit": false
}'

Response

{
  "statusCode": 201,
  "message": "Onramp request created successfully",
  "data": {
      "onrampId": "e5b11a32-XXXX-XXXX-XXXXX-ed0d0ec9c1b7",
      "acceptanceMethod": "virtual_account_bni",
      "feeDetail": {
        "rate_amount": 15676.51352,
        "total_fee_amount": 224.5397227839727,
        "total_fee_amount_in_currency": 3520000.0000000005
      },
      "receiver": {
          "id": "64c422d5e78XXXXXXXXXXXXX",
          "name": "",
          "email": "",
          "phoneNumber": "",
          "walletAddress": "GDC2QZWDOW4IQXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
      },
      "inputAmount": 16000,
      "inputAmountExact": 16000,
      "inputCurrency": "IDR",
      "outputCurrency": "usdc",
      "outputAmount": 1.0201160925777184,
      "outputAmountExact": 0.8798501298482821,
      "reason": "Test Create",
      "description": "Test create",
      "status": "pending",
      "organizationId": "-",
      "organizationName": "-",
      "blockchain": "stellar",
      "userId": "req-igv",
      "externalOrderId": "1706992XXXXXXXX",
      "expiredDate": "2024-02-03T20:44:35.473Z",
      "cryptoId": "usdc-stellar",
      "useSmartContract": false,
      "blockchainType": "STELLAR",
      "memo": "",
      "activityHistory": [
          {
              "activity": "Paid by Payee",
              "status": "pending",
              "description": "Waiting for payment from sender",
              "_id": "65bea4878fc071c5583ab9dd",
              "updatedAt": "2024-02-03T20:39:35.476Z"
          },
          {
              "activity": "Converted to",
              "status": "pending",
              "description": "Waiting for fiat money to be received by system, to be converted to crypto asset afterward",
              "_id": "65bea4878fc071c5583ab9de",
              "updatedAt": "2024-02-03T20:39:35.476Z"
          },
          {
              "activity": "Sent to recipient wallet",
              "status": "pending",
              "description": "Transaction is under process and will be transferred out to the recipient after conversion is done",
              "_id": "65bea4878fc071c5583ab9df",
              "updatedAt": "2024-02-03T20:39:35.476Z"
          },
          {
              "activity": "Received by recipient",
              "status": "pending",
              "description": "Transaction is executed successfully and closed",
              "_id": "65bea4878fc071c5583ab9e0",
              "updatedAt": "2024-02-03T20:39:35.476Z"
          }
      ],
      "acceptanceDetail": {
          "is_custom_page": true,
          "va_number": "",
          "frontend_url": "https://app-dev.rampable.co/fm?data=eyJ0cmFuc1XXXXXXXXXXXXXXXXXfQ=="
      },
      "clientName": "Xellar",
      "clientId": "65383b6d2361032a06bd4f55",
      "createdAt": "2024-02-03T20:39:35.484Z",
      "updatedAt": "2024-02-03T20:39:35.484Z",
      "id": "65bea4878fc071c5583ab9dc"
  }
}