Mono Colombia
GuidesAPI reference
CoreLedger

Perform a transfer between ledger accounts

Transfer funds smoothly between any two of your subaccounts

General considerations

  • This endpoint could be only used for accounts with type subaccount.
  • Both payer and receiving accounts should be active.
  • The associated account holders should also be active.

Considerations for same currency transfers

  • You can specify either source_amount or target_amount, the other field should be set to null. It will be set equal to the given amount.
  • The currency code of the amount should be equal to the payer and receiving accounts' currency code.

Considerations for transfers with different currencies

  • You can specify either source_amount or target_amount, the other field should be set to null. It will be calculated according to the given amount, fx_rate, and configured fees.
  • The currency code of the source_amount should be equal to the payer account currency code.
  • The currency code of the target_amount should be equal to the receiving account currency code.
  • The fx_rate is the conversion rate from target currency to source currency For example, with source currency COP and target currency USD, the rate would be like 4000. For source currency USD and target currency COP, the rate would be like 0.00025. The rate includes any FX markup configured (or overridden in the request).

How the amounts are calculated

If given target amount

source_amount = target_amount * fx_rate + fixed_fee (rounded to the appropriate number of decimal places)

If given source amount

target_amount = (source_amount - fixed_fee) / fx_rate (rounded to the appropriate number of decimal places)

How the fx_rate field works

If the fx_rate field is not given, it's calculated by using the current marked rate (as returned by the FX rates endpoint) and adding the spread (FX markup). For example, for a market rate of 4000 and a spread of 1%. fx_rate will be 4000 * (1 + 0.01) = 4040.

If fx_rate is given, it's assumed to include the spread already, so the given rate won't be modified in any way.

How the override_fees field works

There are two fees that apply to this operation:

  • A fixed amount fee named account_to_account_fx, in the currency of the source amount
  • A percentage fee named account_to_acount_fx_spread, included in the conversion rate

These fees are configured in the system but can be overridden for individual requests by passing them in override_fees.

For account_to_account_fx, the fixed and tx_description fields can be provided to override the defaults. For account_to_account_fx_spread, percentage can be overridden.

What is returned in calculated_fees

For each supported fee (account_to_account_fx and account_to_account_fx_spread), a fee object is returned in calculated_fees that contains the final amount of the fee. This amount is always in the currency of the source amount and represents how much was charged for the operation. The spread fee is calculated from the difference in rates between the actual conversion rate (fx_rate) and the market rate.

POST
/v1/ledger/transfers

Authorization

authorization

AuthorizationBearer <token>

In: header

Header Parameters

x-idempotency-key?string

Idempotency key in UUID format

Formatuuid
Example"f30f1d0b-795f-49f5-80dc-41a7bffccfde"

Request Body

application/json

Attributes used to perform the transfer

amount?object|nullDeprecated

Deprecated; will be removed in the future. Please use the source_amount field instead.

description?string|null

String field

Lengthlength <= 255
Example"Transfer XYZ"
external_idstring

Unique identifier of the transfer operation

Lengthlength <= 255
Example"37979c4d-9a6b-40de-b258-42e62f7ee4f1"
fx_rate?string|null

Exchange rate for currency conversion (must be >= 0)

Match^-?\d+(\.\d+)?$
Range0 <= value
Example"123.45"
metadata?object|null

A tenant-managed flat map for providing additional data about the transfer. The values are stored and displayed as strings, and the provided information will be returned as-is in the account transaction details.

Example{ "id": 3, "reference": 123 }
override_fees?array|null

Custom fees to override the calculated ones

payer_account_idstring

Indicates the format for resource's ID

Match^[A-Za-z]{2,6}_[\w-]{22}$
Example"lacc_5tgliBmzjZ6mpQPRbQjfKj"
receiving_account_idstring

Indicates the format for resource's ID

Match^[A-Za-z]{2,6}_[\w-]{22}$
Example"lacc_5tgliBmzjZ6mpQPRbQjfKj"
reference?string|null

String field

Lengthlength <= 255
Example"123"
source_amount?object|null

The amount to be debited from the source account, specified in the same currency as the source account, This amount includes the fees if they were configured. If this field is null, its value will be automatically calculated from the target amount.

target_amount?object|null

The amount to be credited to the target account, specified in the same currency as the target account. If this field is null, its value will be automatically calculated from the source amount.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api.cert.monoban.co/v1/ledger/transfers" \  -H "Content-Type: application/json" \  -d '{    "external_id": "37979c4d-9a6b-40de-b258-42e62f7ee4f1",    "payer_account_id": "lacc_5tgliBmzjZ6mpQPRbQjfKj",    "receiving_account_id": "lacc_5tgliBmzjZ6mpQPRbQjfKj"  }'
{
  "amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "calculated_fees": {
    "account_to_account_fx": {
      "amount": {
        "amount": 100000000,
        "currency": "COP"
      },
      "id": "fee_5tgliBmzjZ6mpQPRbQjfKj"
    },
    "account_to_account_fx_spread": {
      "amount": {
        "amount": 100000000,
        "currency": "COP"
      },
      "id": "fee_5tgliBmzjZ6mpQPRbQjfKj"
    }
  },
  "description": "Transfer XYZ",
  "external_id": "37979c4d-9a6b-40de-b258-42e62f7ee4f1",
  "fx_rate": "123.45",
  "id": "accop_5tgliBmzjZ6mpQPRbQjfKj",
  "metadata": {
    "id": 3,
    "reference": 123
  },
  "operation_type": "account_to_account",
  "override_fees": [
    {
      "fixed": {
        "amount": 100000000,
        "currency": "COP"
      },
      "percentage": "123.45",
      "tx_description": "string",
      "type": "account_to_account_fx"
    }
  ],
  "payer_account_id": "lacc_5tgliBmzjZ6mpQPRbQjfKj",
  "receiving_account_id": "lacc_5tgliBmzjZ6mpQPRbQjfKj",
  "reference": "123",
  "source_amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "target_amount": {
    "amount": 100000000,
    "currency": "COP"
  }
}
{
  "amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "calculated_fees": {
    "account_to_account_fx": {
      "amount": {
        "amount": 100000000,
        "currency": "COP"
      },
      "id": "fee_5tgliBmzjZ6mpQPRbQjfKj"
    },
    "account_to_account_fx_spread": {
      "amount": {
        "amount": 100000000,
        "currency": "COP"
      },
      "id": "fee_5tgliBmzjZ6mpQPRbQjfKj"
    }
  },
  "description": "Transfer XYZ",
  "external_id": "37979c4d-9a6b-40de-b258-42e62f7ee4f1",
  "fx_rate": "123.45",
  "id": "accop_5tgliBmzjZ6mpQPRbQjfKj",
  "metadata": {
    "id": 3,
    "reference": 123
  },
  "operation_type": "account_to_account",
  "override_fees": [
    {
      "fixed": {
        "amount": 100000000,
        "currency": "COP"
      },
      "percentage": "123.45",
      "tx_description": "string",
      "type": "account_to_account_fx"
    }
  ],
  "payer_account_id": "lacc_5tgliBmzjZ6mpQPRbQjfKj",
  "receiving_account_id": "lacc_5tgliBmzjZ6mpQPRbQjfKj",
  "reference": "123",
  "source_amount": {
    "amount": 100000000,
    "currency": "COP"
  },
  "target_amount": {
    "amount": 100000000,
    "currency": "COP"
  }
}
{
  "code": "400 Bad Request",
  "errors": [
    {
      "error_code": "validation_error",
      "message": "Generic changeset errors",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Malformed request"
}
{
  "code": "401 Unauthorized",
  "errors": [
    {
      "error_code": "expired_token",
      "message": "The token is expired, inactive, or doesn't exist.",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Authorization header is missing or invalid."
}
{
  "code": "403 Forbidden",
  "errors": [
    {
      "error_code": "not_authorized",
      "message": "Not authorized to have access to this resource.",
      "path": null,
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Not authorized to have access to this resource"
}
{
  "code": "422 Unprocessable Entity",
  "errors": [
    {
      "error_code": "missing_field",
      "message": "The field is missing on the request body or parameters.",
      "path": "#/path/to/field",
      "url": null
    }
  ],
  "id": "log_7MkWaFqvfosB8fzHhb1Eql",
  "message": "Validation errors"
}

Get the tenant global configuration GET

Previous Page

Payouts

Create and manage payouts with target resolution