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:

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, processed, 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, processed, 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.

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.

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

Response with txData

{
  "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",
      "txData": {
        "data": [
          {
            "action": "claim_token",
            "dataHex": "0x19bbc77400000000000000000000000000000000000000000000",
            "contractAddress": "0x7d25315A95714d85988A388A2744D0C463574d2c",
            "tokenAddress": "0x9521728bF66a867BC65A93Ece4a543D817811Eb7",
            "receiverWalletAddress": "0xD1864f59C0b3fEa1A0aAD6b09E2d1b6441e07500",
            "amount": 36.6296,
            "chainID": 56,
          }
        ],
        "nativeCoinHash": "0x5ac17669624dde30c167bbf72290e5aea2b114b5e8cdd94888cceaf21c40be23"
      }
  }
}

Was this page helpful?