Disbursement

On this page, we’ll dive into the different disbursement endpoints you can use to manage disbursement transactions programmatically. You can disburse both fiat and cryptocurrency.

The disbursement model

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

Properties

Name
disbursementId
Type
string
Description
Unique identifier for the disbursement transaction.
Name
recipient
Type
object
Description
Details of the recipient.
Name
recipient.recipientId
Type
string
Description
Unique identifier for the recipient.
Name
recipient.email
Type
string
Description
Email address of the recipient.
Name
recipient.name
Type
string
Description
Name of the recipient.
Name
recipient.bank
Type
object
Description
Bank details of the recipient.
Name
recipient.bank.bankName
Type
string
Description
Name of the bank.
Name
recipient.bank.accountName
Type
string
Description
Name on the bank account.
Name
recipient.bank.accountNumber
Type
string
Description
Bank account number.
Name
recipient.bank.bankCode
Type
string
Description
Code of the bank.
Name
recipient.bank.currency
Type
string
Description
Currency of the bank account.
Name
recipient.bank.country
Type
string
Description
Country of the bank.
Name
amount
Type
number
Description
The amount of the disbursement.
Name
currency
Type
string
Description
The currency of the disbursement.
Name
feeAmount
Type
number
Description
The amount of the fee.
Name
feePercentage
Type
number
Description
The percentage of the fee.

Name
status
Type
string
Description
The status of the disbursement transaction. This can be either pending, failed or completed.
Name
createdBy
Type
string
Description
Unique identifier of the user who created the disbursement.
Name
activityHistory
Type
array
Description
Array of activity history objects.
Name
activityHistory.activity
Type
string
Description
Description of the activity.
Name
activityHistory.status
Type
string
Description
Status of the activity.
Name
activityHistory.description
Type
string
Description
Description of the activity.
Name
activityHistory.updatedAt
Type
object
Description
Timestamp of the activity update.
Name
reference
Type
string
Description
This can be the client transaction ID for the disbursement transaction.
Name
createdAt
Type
string
Description
Timestamp when the disbursement was created.
Name
updatedAt
Type
string
Description
Timestamp when the disbursement was last updated.

GET/v1/disbursement/fiat

Disbursement Fiat List

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

Query Params attributes

Name
limit
Type
integer
Description
Limit the number of disbursement transactions returned.
Name
page
Type
integer
Description
Specify the page number of the disbursement transactions to retrieve.
Name
sort
Type
string
Description
Sort the disbursement transactions by a specific field. You can sort by createdAt or updatedAt. By default, disbursement 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
disbursementId
Type
string
Description
Search for a specific disbursement transaction by its disbursementId.
Name
status
Type
string
Description
Filter the disbursement transactions by status. You can filter by pending, failed, or completed.
Name
currency
Type
string
Description
Filter the disbursement transactions by currency.

Request

GET

/v1/disbursement/fiat

curl -X GET "https://staging.rampable.co/v1/disbursement/fiat?limit=10&page=1&sort=createdAt&status=pending&currency=IDR" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Response

{
      "disbursementId": "e254a4ba-6c6b-4953-af22-30d7447fe3ee",
      "recipient": {
          "recipientId": "mocked_recipient_id",
          "email": "mocked_email@example.com",
          "name": "Mocked Name",
          "bank": {
              "bankName": "Mocked Bank",
              "accountName": "Mocked Account",
              "accountNumber": "mocked_account_number",
              "bankCode": "mocked_bank_code",
              "currency": "Mocked Currency",
              "country": "Mocked Country"
          }
      },
      "amount": 40000,
      "currency": "IDR",
      "feeAmount": 5000,
      "feePercentage": 12.5,
      "status": "completed",
      "createdBy": "672873dfc82e12312dc77ce2",
      "activityHistory": [
          {
              "activity": "Disburse requested",
              "status": "completed",
              "description": "order is valid",
              "updatedAt": "2024-11-12T06:07:02.386Z"
          },
          {
              "activity": "Recipient validated",
              "status": "completed",
              "description": "recipient is valid",
              "updatedAt": "2024-11-12T06:07:02.386Z"
          },
          {
              "activity": "Sent to recipient account",
              "status": "completed",
              "description": "transaction is success",
              "updatedAt": "2024-11-12T06:07:11.442Z"
          }
      ],
      "reference": "referenceId",
      "createdAt": "2024-11-12T06:07:00.762Z",
      "updatedAt":"2024-11-12T06:07:11.443Z"
  }

GET/v1/disbursement/fiat/:disbursementId

Disbursement Fiat Detail

This endpoint allows you to retrieve the details of a specific fiat disbursement transaction.

Request

GET

/v1/disbursement/fiat/:disbursementId

curl -X GET "https://staging.rampable.co/v1/disbursement/fiat/cd738d41-8f37-4fb4-9c0b-8cd75b687530" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Response

{
  "statusCode": 200,
  "message": "getFiatDisbursementDetailHandler successfully",
  "data": {
      "disbursementId": "e254a4ba-6c6b-4953-af22-30d7447fe3ee",
      "recipient": {
        "recipientId": "mocked_recipient_id",
        "email": "mocked_email@example.com",
        "name": "Mocked Name",
        "bank": {
          "bankName": "Mocked Bank",
          "accountName": "Mocked Account",
          "accountNumber": "mocked_account_number",
          "bankCode": "mocked_bank_code",
          "currency": "Mocked Currency",
          "country": "Mocked Country"
        }
      },
      "amount": 40000,
      "currency": "IDR",
      "feeAmount": 5000,
      "feePercentage": 12.5,
      "status": "completed",
      "createdBy": "672873dfc82e12312dc77ce2",
      "activityHistory": [
        {
          "activity": "Disburse requested",
          "status": "completed",
          "description": "order is valid",
          "updatedAt": "2024-11-12T06:07:02.386Z"
        },
        {
          "activity": "Recipient validated",
          "status": "completed",
          "description": "recipient is valid",
          "updatedAt": "2024-11-12T06:07:02.386Z"
        },
        {
          "activity": "Sent to recipient account",
          "status": "completed",
          "description": "transaction is success",
          "updatedAt": "2024-11-12T06:07:11.442Z"
        }
      ],
      "reference": "referenceId",
      "createdAt": "2024-11-12T06:07:00.762Z",
      "updatedAt": "2024-11-12T06:07:11.443Z"
    }
}

POST/v1/disbursement/fiat

Create Disbursement Fiat V1

This endpoint is used to initiate a fiat disbursement transaction. In order to initiate a disbursement, you must provide the amount, currency, recipient, and paymentMethod.

Please ensure that the amount is a positive number and that you are using valid currency codes.

Required attributes

Name
disburseData
Type
array
Description
This is an array of disbursement data.
Name
currency
Type
string
Description
This is the currency of the disbursement.
Name
recipientId
Type
string
Description
This is the unique identifier of the recipient.
Name
amount
Type
number
Description
This is the amount of the disbursement.

Optional attributes

Name
reference
Type
string
Description
This can be the client transaction ID for the disbursement transaction.

Request

POST

/v1/deposit/fiat

curl --location \
https://staging.rampable.co/v1/disbursement/fiat \
--header 'x-client-secret: ••••••' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "disburseData": [
        {
            "currency" : "IDR",
            "recipientId": "670f8112cd0b0ddab0a03860",
            "amount": 10000,
            "reference": "referenceId1"
        },
        {
            "currency" : "IDR",
            "recipientId": "670f8112cd0b0ddab0a03860",
            "amount": 200000,
            "reference": "referenceId12"
        },
        {
            "currency" : "IDR",
            "recipientId": "670f8112cd0b0ddab0a03860",
            "amount": 3000000,
            "reference": "referenceId123"
        }
    ]
}'

Response

{
  "statusCode": 200,
  "message": "Disbursement created successfully",
  "data": {
      "totalRecipient": 2,
      "disburseData": [
          {
              "disbursementId": "82dc0772-1b4c-4894-8b14-7ebd74ffec58",
              "recipient": {
                  "recipientId": "666b127a8a1656b0d892cf8b",
                  "email": "email@gmail.com",
                  "name": "test recipient",
                  "bank": {
                      "bankName": "BANK DIGITAL BCA",
                      "accountName": "accountName",
                      "accountNumber": "1234567890",
                      "bankCode": "051",
                      "currency": "IDR",
                      "country": "INDONESIA"
                  }
              },
              "currency": "IDR",
              "amount": 12000,
              "status": "pending",
              "feeAmount": 5000,
              "feePercentage": 41.67,
              "reference": "referenceId1"
          },
          {
              "disbursementId": "182cd82d-c2c8-48fc-a0e1-1742dd28cff6",
              "recipient": {
                  "recipientId": "666b127a8a1656b0d892cf8b",
                  "email": "email@gmail.com",
                  "name": "test recipient",
                  "bank": {
                      "bankName": "BANK NEGARA INDONESIA",
                      "accountName": "accountName",
                      "accountNumber": "0987654321",
                      "bankCode": "009",
                      "currency": "IDR",
                      "country": "INDONESIA"
                  }
              },
              "currency": "IDR",
              "amount": 7800,
              "status": "pending",
              "feeAmount": 5000,
              "feePercentage": 64.1,
              "reference": "referenceId2"
          }
      ],
      "sumFees": [
          {
              "currency": "IDR",
              "totalAmount": 10000
          }
      ],
      "sumAmount": [
          {
              "currency": "IDR",
              "totalAmount": 19800
          }
      ]
  }
}

HTTP Status 400 Example

Error Response

{
    "statusCode": 400,
    "error": "Not Found",
    "message": "Payment method not found"
}

POST/v2/disbursement/fiat

Create Disbursement Fiat V2

This endpoint allows you to create a disbursement transaction for fiat currency. That you can passing recipientId or directly input the recipient details.

Request body

Name
currency
Type
string
Description
The currency for all disbursements in this request.
Name
disburseData
Type
array
Description
Array of disbursement data objects.
Name
disburseData[].recipient
Type
object
Description
Direct recipient details (required if recipientId not provided).
Name
recipient.email
Type
string
Description
Email address of the recipient. Optional field.
Name
recipient.name
Type
string
Description
Name of the recipient. Optional field.
Name
recipient.bank
Type
object
Description
Bank details of the recipient.
Name
bank.bankName
Type
string
Description
Name of the bank.
Name
bank.accountName
Type
string
Description
Name on the bank account.
Name
bank.accountNumber
Type
string
Description
Bank account number.
Name
bank.bankCode
Type
string
Description
Code of the bank.
Name
disburseData[].recipientId
Type
string
Description
Unique identifier of an existing recipient (required if recipient details not provided).
Name
disburseData[].amount
Type
number
Description
Amount to disburse.
Name
disburseData[].reference
Type
string
Description
Reference ID for the disbursement. Optional field.

Request

POST

/v2/disbursement/fiat

curl --location \
  https://staging.rampable.co/v2/disbursement/fiat \
  --header 'x-client-secret: ••••••' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: ••••••' \
  --data '{
    "currency": "IDR",
    "disburseData": [
      {
        "recipient": {
          "email": "test@gmial.com",
          "name": "Client Name",
          "bank": {
            "bankName": "BANK RAKYAT INDONESIA", 
            "accountName": "Client Name",
            "accountNumber": "123456789",
            "bankCode": "bank_rakyat_indonesia"
          }
        },
        "amount": 10000,
        "reference": "reference 1"
      },
      {
        "recipientId": "671766b24633f04ac6273109",
        "amount": 10000,
        "reference": "reference 2"
      }
    ]
  }'

Response

{
  "statusCode": 200,
  "message": "Disbursement created successfully",
  "data": {
    "totalRecipient": 2,
    "disburseData": [
      {
        "disbursementId": "1a5a4781-768e-4f04-9323-3409d5cf031e",
        "groupId": "b4599b0e-4b27-492b-a0ed-650ba590de73",
        "recipient": {
          "bank": {
            "bankName": "BANK RAKYAT INDONESIA",
            "accountName": "Client Name",
            "accountNumber": "123456789",
            "bankCode": "bank_rakyat_indonesia",
            "currency": "IDR"
          }
        },
        "currency": "IDR",
        "amount": 10000,
        "status": "pending",
        "feeAmount": 5000,
        "feePercentage": 50,
        "activityHistory": [
          {
            "activity": "Disburse requested",
            "status": "pending",
            "description": "waiting for system validation",
            "updatedAt": "2025-02-12T08:42:38.568Z"
          },
          {
            "activity": "Recipient validated",
            "status": "pending",
            "description": "waiting for bank confirmation received by system",
            "updatedAt": "2025-02-12T08:42:38.568Z"
          },
          {
            "activity": "Sent to recipient account",
            "status": "pending",
            "description": "transaction is under process and will be transferred out to recipient after validation is done",
            "updatedAt": "2025-02-12T08:42:38.568Z"
          }
        ],
        "reference": "reference 2"
      },
      {
        "disbursementId": "e62f3c62-4588-46db-a485-a1e22d3b43ca",
        "groupId": "b4599b0e-4b27-492b-a0ed-650ba590de73",
        "recipient": {
          "recipientId": "671766b24633f04ac6273109",
          "email": "felixlambet@gmail.com",
          "name": "Fiat Disburse Test 1",
          "bank": {
            "bankName": "BANK BNI",
            "accountName": "Frans Timoty",
            "accountNumber": "7729225131",
            "bankCode": "bank_bni",
            "currency": "IDR",
            "country": "INDONESIA"
          }
        },
        "currency": "IDR",
        "amount": 10000,
        "status": "pending",
        "feeAmount": 5000,
        "feePercentage": 50,
        "activityHistory": [
          {
            "activity": "Disburse requested",
            "status": "pending",
            "description": "waiting for system validation",
            "updatedAt": "2025-02-12T08:42:38.568Z"
          },
          {
            "activity": "Recipient validated",
            "status": "pending",
            "description": "waiting for bank confirmation received by system",
            "updatedAt": "2025-02-12T08:42:38.568Z"
          },
          {
            "activity": "Sent to recipient account",
            "status": "pending",
            "description": "transaction is under process and will be transferred out to recipient after validation is done",
            "updatedAt": "2025-02-12T08:42:38.568Z"
          }
        ],
        "reference": "reference 2"
      }
    ],
    "sumFees": 10000,
    "sumAmount": 20000
  }
}