Quick Buy

The Quick Buy module provides the infrastructure to perform buy exchanges on behalf of customers, using a customer's external financial card. This module includes a series of endpoints tailored to the needs of users looking to perform and monitor quick buy exchanges for their customers, as well as manage their saved cards.

Offering functions from quoting to execution, along with detailed tracking mechanisms, the Quick Buy module endpoints include:

• List Cards - Retrieve a list of payment cards associated with a customer.

• Get Card by ID - Enables a user to retrieve information about a payment card by submitting the ID of the payment card.

• Delete Card - Allows a user to delete a payment card, removing it from being an option for further exchanges.

• Get Available Asset Pairs: Provides a list of asset pairs enabled for the API user and available for quick buy. The response will also include information on limits and minimums associated with each asset pair for exchanges.

• Get Quote: Provides an estimate for a quick buy exchange, detailing the price and amount before the actual exchange is executed, ensuring that the customer is informed about the potential transaction.

• Submit Exchange: This endpoint will allow a customer to initiate a quick buy exchange. The customer can either use a saved payment card or enter details of a payment card. The user has the option of saving the payment card for use in further exchanges.

• List Exchanges: Provides a generated list of quick buy exchanges, with the ability to filter by customer, order type, and more.

• Get Order by ID: Provides a details of a quick buy order buy submitting the ID of the exchange.

---

List Cards

Retrieve a list of payment cards associated with a customer

• Endpoint: /api/v1/customer/quick-buy/cards/list

• Method: GET

Get saved payment cards

GET/api/v1/customer/quick-buy/cards/list

Query parameters

Header parameters

Response

200400

OK

Body

application/json

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsnullable array of AvamaeTemplate.Core.Types.Dtos.CustomerRole.QuickBuyModule.PaymentCardDto (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/customer/quick-buy/cards/list', {
    method: 'GET',
    headers: {
      "otp": "text"
    },
});
const data = await response.json();

Response

200400

{
  "status": "text",
  "errors": [
    {
      "errorType": "text",
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": [
    {
      "cardholderName": "text",
      "cardDescription": "text",
      "cardType": "text",
      "cardLast4Digits": "text",
      "expiryDate": "2024-10-16T08:38:44.296Z"
    }
  ]
}

Request Query Example

{{endpoint}}/api/v1/customer/quick-buy/cards/list?customersId=14349

Response Body Example

{
    "id": 0,
    "details": [
        {
            "id": 1227,
            "cardholderName": "John Doe",
            "cardDescription": "ECMC...0004",
            "cardType": "ECMC_CREDIT",
            "cardLast4Digits": "0004",
            "expiryDate": null
        }
    ],
    "status": "1",
    "errors": []
}

---

Get Card by ID

Enables a user to retrieve information about a payment card by submitting the ID of the payment card.

• Endpoint: /api/v1/customer/quick-buy/cards/getbyid

• Method: GET

Get saved payment card by id

GET/api/v1/customer/quick-buy/cards/getbyid

Query parameters

Header parameters

Response

200400

OK

Body

application/json

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsnullable array of AvamaeTemplate.Core.Types.Dtos.CustomerRole.QuickBuyModule.PaymentCardDto (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/customer/quick-buy/cards/getbyid', {
    method: 'GET',
    headers: {
      "otp": "text"
    },
});
const data = await response.json();

Response

200400

{
  "status": "text",
  "errors": [
    {
      "errorType": "text",
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": [
    {
      "cardholderName": "text",
      "cardDescription": "text",
      "cardType": "text",
      "cardLast4Digits": "text",
      "expiryDate": "2024-10-16T08:38:44.296Z"
    }
  ]
}

Request Query Example

{{endpoint}}/api/v1/customer/quick-buy/cards/getbyid?customersId=14349&paymentCardsId=1229

Response Body Example

{
    "id": 0,
    "details": {
        "id": 1229,
        "cardholderName": "John Doe",
        "cardDescription": "VISA...1111",
        "cardType": "VISA_CREDIT",
        "cardLast4Digits": "1111",
        "expiryDate": "2025-12-31T00:00:00"
    },
    "status": "1",
    "errors": []
}

---

Delete Card

Allows a user to delete a payment card, removing it from being an option for further exchanges.

• Endpoint: /api/v1/customer/quick-buy/cards/delete

• Method: POST

Delete saved payment card by id

POST/api/v1/customer/quick-buy/cards/delete

Query parameters

Header parameters

Response

200400

OK

Body

application/json

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.QuickBuyModule.PaymentCardDto (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/customer/quick-buy/cards/delete', {
    method: 'POST',
    headers: {
      "otp": "text"
    },
});
const data = await response.json();

Response

200400

{
  "status": "text",
  "errors": [
    {
      "errorType": "text",
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": {
    "cardholderName": "text",
    "cardDescription": "text",
    "cardType": "text",
    "cardLast4Digits": "text",
    "expiryDate": "2024-10-16T08:38:44.296Z"
  }
}

Request Query Example

{{endpoint}}/api/v1/customer/quick-buy/cards/delete?customersId=14349&paymentCardsId=1226

Response Body Example

{
    "id": 1226,
    "status": "1",
    "errors": []
}

---

Get Available Asset Pairs

Provides a list of asset pairs enabled for the API user and available for quick buy. The response will also include information on limits and minimums associated with each asset pair for exchanges.

• Endpoint: /api/v1/customer/quick-buy/orders/assets

• Method: GE

Get available exchanges

GET/api/v1/customer/quick-buy/orders/assets

Header parameters

Response

200400

OK

Body

application/json

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsnullable array of AvamaeTemplate.Core.Types.Dtos.CustomerRole.QuickBuyModule.PriceInfoDto (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/customer/quick-buy/orders/assets', {
    method: 'GET',
    headers: {
      "otp": "text"
    },
});
const data = await response.json();

Response

200400

{
  "status": "text",
  "errors": [
    {
      "errorType": "text",
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": [
    {
      "assetCode": "text",
      "assetSymbol": "text",
      "assetName": "text",
      "buyPrice": 0,
      "minAmount": 0,
      "maxAmount": 0,
      "minPrice": 0,
      "maxPrice": 0
    }
  ]
}

Request Query Example

{{endpoint}}/api/v1/customer/quick-buy/orders/assets

Response Body Example

{
    "id": 0,
    "details": [
        {
            "assetCode": "BTC",
            "assetSymbol": "₿",
            "assetName": "Bitcoin",
            "buyPrice": 67466.800000000000000000,
            "minAmount": 0.000100000000000000,
            "maxAmount": 10.000000000000000000,
            "minPrice": 15.000000000000000000,
            "maxPrice": 200000.000000000000000000,
            "maxDecimalPrecision": 0
        }
    ],
    "status": "1",
    "errors": []
}

---

Get Quote

This endpoint provides a quoted market price for a proposed asset exchange for a particular customer, detailing the amount and price for an exchange. By specifying details of the desired trade, a customer can see the cost or proceeds they might expect from completing a transaction, including any applicable fees. This helps customers decide whether to proceed with an exchange based on real-time financial data. For quick buy exchanges, all exchanges will refer to the specified crypto currency being bought in exchange for fiat currency.

• Endpoint: /api/v1/customer/quick-buy/orders/quote

• Method: GET

Get quote for exchange

GET/api/v1/customer/quick-buy/orders/quote

Query parameters

Header parameters

Response

200400

OK

Body

application/json

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.QuickBuyModule.EstimateResponseDto (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/customer/quick-buy/orders/quote', {
    method: 'GET',
    headers: {
      "otp": "text"
    },
});
const data = await response.json();

Response

200400

{
  "status": "text",
  "errors": [
    {
      "errorType": "text",
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": {
    "assetCode": "text",
    "currencyCode": "text",
    "assetAmount": 0,
    "currencyAmount": 0
  }
}

Query Parameters:

• customersId (Integer): ID of the customer making the exchange—required.

• assetCode (String): The crypto currency to be bought, such as "BTC"—required.

• assetAmount (Decimal, Nullable): Desired amount of crypto currency to be bought. Must be null if currencyAmount is specified.

• currenyAmount (Decimal, Nullable): Desired amount of currency to be exchanged. Must be null if assetAmount is specified.

Response Body Parameters:

• id (Integer): Not used.

• details (Object): Contains the quote details.

  • customersId (Integer): ID of the customer.

  • assetCode (String): Crypto currency asset to be bought in the exchange.

  • currenyCode (String): Fiat currency asset involved in the exchange.

  • assetAmount (Decimal): Amount of crypto currency asset to be bought.

  • currencyAmount (Decimal): Amount of fiat currency required for exchange.

Request Query Example

{{endpoint}}/api/v1/customer/quick-buy/orders/quote?customersId=14349&assetCode=BTC&currencyAmount=500

Response Body Example

{
    "id": 14349,
    "details": {
        "customersId": 14349,
        "assetCode": "BTC",
        "currencyCode": "USD",
        "assetAmount": 0.00705853,
        "currencyAmount": 500.0
    },
    "status": "1",
    "errors": []
}

Possible Error Codes

Error Message Code	Description
Required	Named field missing or zero
Invalid	Value given for named field is invalid
Documents_Not_Verified	Cannot perform this action for this customer due to the KYC state
Amount_Must_Be_Positive	Invalid or missing amount

---

Submit Exchange

This endpoint is intended for initiating a quick buy exchange, enabling a customer to purchase an asset at a specified price.

• Endpoint: /api/v1/customer/quick-buy/orders/submit

• Method: POST

Quick buy crypto

Possible validation errors:

• Required
• Invalid
• Invalid_PaymentCard
• Failed(500 - Field Create_Payment or Create_Card indicates possible incorrect card details)
• Invalid_Asset
• Price_Too_Low
• Price_Updated - Quoted price may be out of data
• Asset_Pair_Unavailable

POST/api/v1/customer/quick-buy/orders/submit

Header parameters

Body

application/json-patch+jsonapplication/jsontext/jsonapplication/*+json

customersIdnullable integer (int32)

currencyCodenullable string

assetCode*string

assetPairnullable string

assetAmount*number (double)

currencyAmount*number (double)

quantityTypeAvamaeTemplate.Core.Enums.ExchangeQuantityTypes (enum)

01

paymentCardsIdnullable integer (int32)

cardDetailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.QuickBuyModule.QuickBuyRequestDto+CardDetailsDto (object)

chargeCardIdempotencyKeystring (uuid)

Response

200400

OK

Body

application/json

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.General.ChargeSavedCardResultsDto (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/customer/quick-buy/orders/submit', {
    method: 'POST',
    headers: {
      "otp": "text",
      "Content-Type": "application/json-patch+json"
    },
    body: JSON.stringify({
      "assetAmount": 0,
      "assetCode": "text",
      "currencyAmount": 0
    }),
});
const data = await response.json();

Response

200400

{
  "status": "text",
  "errors": [
    {
      "errorType": "text",
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": {
    "status": 0
  }
}

Request Body Parameters:

• customersId (Integer): ID of the customer making the exchange—required.

• assetCode (String): The crypto currency to be bought, such as "BTC"—required.

• assetAmount (Decimal, Required): Desired amount of crypto currency to be bought.

• currenyAmount (Decimal, Required): Desired amount of currency to be exchanged.

• paymentCardsId (Integer, Nullable): Id of saved payment card. Must be null if CardDetails is not null.

• cardDetails (JSON Object): Details of payment card. Must be null if paymentCardsId is not null.

  • cardNumber (String, Required): Card number.

  • cvv (String, Required): Card CVV

  • cardHolderName (String, Required): Cardholder name.

  • addressLine1 (String, Required): Cardholder address line 1.

  • addressLine2 (String): Cardholder address line 2.

  • townCity (String, Required): Cardholder town or city.

  • countryISO2 (String, Required): Cardholder country of address.

  • stateProvince (String, Required): Cardholder state or province.

  • postCode (String, Required): Cardholder ZIP/Postal Code.

  • expMonth (Integer, Required): Card expiration month.

  • expYear (Integer, Required): Card expiration year.

  • bSaveCard (Boolean, Required): Indicates whether the payment card should be saved.

Request Example:

{
    "customersId": 14349,
    "assetCode": "BTC",
    "assetAmount": 0.00718246,
    "currencyAmount": 500,
    "paymentCardsId": null,
    "cardDetails": {
        "cardNumber": "4111111111111111",
        "cvv": "123",
        "cardholderName": "John Doe",
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "townCity": "Springfield",
        "countryISO2": "US",
        "stateProvince": "IL",
        "postCode": "62704",
        "expMonth": 12,
        "expYear": 2025,
        "bSaveCard": true
    }
}

Response Body Parameters:

• id (Integer): Not used.

• details (Object):

  • status (String): The status of the transaction, such as "Pending".

    • Possible values: Pending, Failed, Approved, ActionRequired.

  • exchangesId(Integer): The ID of the associated asset exchange.

Success Response Example:

{
    "id": 0,
    "details": {
        "status": "Approved",
        "exchangesId": 14483
    },
    "status": "1",
    "errors": []
}

Possible Error Codes

Error Message Code	Description
Required	Named field missing or zero
Invalid	Value given for named field is invalid
Documents_Not_Verified	Cannot perform this action for this customer due to the KYC state

---

List Exchanges

Provides a system generated list of quick buy exchanges, with ability to filter by the the customersID or asset pair.

• Endpoint: /api/v1/customer/quick-buy/orders/list

• Method: GET

Get list of orders

GET/api/v1/customer/quick-buy/orders/list

Query parameters

Header parameters

Response

200400

OK

Body

application/json

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsnullable array of AvamaeTemplate.Core.Types.Dtos.CustomerRole.QuickBuyModule.AssetExchangeDto (object)

pageSizenullable integer (int32)

pageNumbernullable integer (int32)

numberOfPagesnullable integer (int32)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/customer/quick-buy/orders/list', {
    method: 'GET',
    headers: {
      "otp": "text"
    },
});
const data = await response.json();

Response

200400

{
  "status": "text",
  "errors": [
    {
      "errorType": "text",
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": [
    {
      "exchangeType": 0,
      "status": 0,
      "assetPair": "text",
      "requestAmount": 0,
      "requestPrice": 0,
      "executedAmount": 0,
      "executedPrice": 0,
      "commissionFee": 0,
      "transferType": 0,
      "bHasOpenRfi": false,
      "cardDescription": "text"
    }
  ]
}

Request Query

Optional Request Query Parameters:

• customersId (Integer): The ID of the customer initiating the purchase.

• assetPair (String): The asset pair to be filtered, such as "BTC/USDC".

• PageNumber (Integer): List page number (default = 1)

• PageSize (Integer): List page size (default = 10)

Request Query Example

{{endpoint}}/api/v1/customer/quick-buy/orders/list?customersId=14349

Response Body Example

{
    "id": 1777,
    "details": [
        {
            "id": 14487,
            "exchangeType": "Buy",
            "status": "Completed",
            "creditTransactionsId": 79311,
            "customersId": 14349,
            "assetPair": "BTC/USD",
            "requestAmount": 0.007113640000000000,
            "requestPrice": 500.000000000000000000,
            "executedAmount": 0.007144470000000000,
            "executedPrice": 500.000000000000000000,
            "commissionFee": 21.530000000000000000,
            "transferType": null,
            "bHasOpenRfi": false,
            "paymentCardsId": 1229,
            "cardDescription": "VISA...1111"
        },
        {
            "id": 14484,
            "exchangeType": "Buy",
            "status": "Pending",
            "creditTransactionsId": 78928,
            "customersId": 14349,
            "assetPair": "BTC/USD",
            "requestAmount": 0.007080710000000000,
            "requestPrice": 500.000000000000000000,
            "executedAmount": null,
            "executedPrice": null,
            "commissionFee": 21.530000000000000000,
            "transferType": null,
            "bHasOpenRfi": false,
            "paymentCardsId": 1229,
            "cardDescription": "VISA...1111"
        }
    ],
    "pageSize": 10,
    "pageNumber": 1,
    "numberOfPages": 2,
    "status": "1",
    "errors": []
}

---

Get Order by Id

Provides a system generated list of quick buy exchanges, with ability to filter by the the customersID or asset pair.

• Endpoint: /api/v1/customer/quick-buy/orders/getbyid

• Method: GET

Get details of an order

GET/api/v1/customer/quick-buy/orders/getbyid

Query parameters

Header parameters

Response

200400

OK

Body

application/json

statusnullable string

errorsnullable array of AvamaeTemplate.Core.Types.Results.Base.ErrorResultDto (object)

idinteger (int64)

detailsAvamaeTemplate.Core.Types.Dtos.CustomerRole.QuickBuyModule.AssetExchangeDto (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/customer/quick-buy/orders/getbyid', {
    method: 'GET',
    headers: {
      "otp": "text"
    },
});
const data = await response.json();

Response

200400

{
  "status": "text",
  "errors": [
    {
      "errorType": "text",
      "fieldName": "text",
      "messageCode": "text"
    }
  ],
  "details": {
    "exchangeType": 0,
    "status": 0,
    "assetPair": "text",
    "requestAmount": 0,
    "requestPrice": 0,
    "executedAmount": 0,
    "executedPrice": 0,
    "commissionFee": 0,
    "transferType": 0,
    "bHasOpenRfi": false,
    "cardDescription": "text"
  }
}

Request Query

Optional Request Query Parameters:

• customersId (Integer): The ID of the customer initiating the purchase.

• assetPair (String): The asset pair to be filtered, such as "BTC/USDC".

• PageNumber (Integer): List page number (default = 1)

• PageSize (Integer): List page size (default = 10)

Request Query Example

{{endpoint}}/api/v1/customer/quick-buy/orders/getbyid?exchangesId=14468

Response Body Example

{
    "id": 1777,
    "details": {
        "id": 14468,
        "exchangeType": "Buy",
        "status": "Completed",
        "creditTransactionsId": 76573,
        "customersId": 14349,
        "assetPair": "BTC/USD",
        "requestAmount": 0.007186150000000000,
        "requestPrice": 500.000000000000000000,
        "executedAmount": 0.007211890000000000,
        "executedPrice": 500.000000000000000000,
        "commissionFee": 21.530000000000000000,
        "transferType": null,
        "bHasOpenRfi": false,
        "paymentCardsId": 1226,
        "cardDescription": "VISA...1111"
    },
    "status": "1",
    "errors": []
}