> For the complete documentation index, see [llms.txt](https://docs.betaramps.com/documentation-beta-ramps/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.betaramps.com/documentation-beta-ramps/request-payments/crypto-payment-orders.md).

# Crypto Payment Orders

## Create a New Order

<mark style="color:green;">`POST`</mark> `https://live.betaapp.com/v1/order`

Beta will freeze the quote for this order for 20 minutes.

\
If the payer deposits a different amount/asset than requested or after this timeframe, our platform will automatically trigger workflows for the payer to top-up the remaining amount or receive a refund for its deposit.

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token} |
| accept<mark style="color:red;">\*</mark>        | String | application/json       |
| x-sub-account-id                                | String | Subaccount ID, If any. |

#### Request Body

| Name                                                        | Type    | Description                                                                             |
| ----------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| network<mark style="color:red;">\*</mark>                   | String  | *Crypto Network*: bitcoin, erc-20, ripple                                               |
| source\_asset<mark style="color:red;">\*</mark>             | String  | *Crypto Asset*: BTC, ETH, XRP                                                           |
| target\_asset<mark style="color:red;">\*</mark>             | String  | *Fiat Asset*: USD, BRL, MXN                                                             |
| target\_amount<mark style="color:red;">\*</mark>            | Number  | Amount in Fiat                                                                          |
| description<mark style="color:red;">\*</mark>               | String  | Description of the product or service provided. It could be the Order ID If e-commerce. |
| recipient\_email<mark style="color:red;">\*</mark>          | String  | Payer's e-mail                                                                          |
| recipient\_language\_code<mark style="color:red;">\*</mark> | String  | Payer's Prefered language: EN, PT                                                       |
| link\_exp                                                   | integer | Time in hours for the payment link to expire. (Default is 72)                           |

{% tabs %}
{% tab title="200: OK Sucess" %}

```json
{
  "amount": 0,
  "asset": {
    "large_image_url": "string",
    "medium_image_url": "string",
    "name": "string",
    "small_image_url": "string",
    "symbol": "string",
    "type": "string"
  },
  "date_time": "string",
  "deposit": true,
  "exp_time": 0,
  "message": "string",
  "network": "string",
  "tag": "string",
  "wallet_address": "string"
}
```

{% endtab %}

{% tab title="400: Bad Request Error message " %}

```json
{
  "message": "string"
}
```

{% endtab %}
{% endtabs %}

**Request Example:**

{% code overflow="wrap" %}

```json
curl -X 'POST' \
  'https://live.betaapp.com/v1/order' \
  -H 'accept: application/json' \
  -H 'X-sub-account-id: 22376b76...4cef3543083b' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJlaEF1NURPY...ctfx2I4g' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "2x Tickets for England vs Germany football match",
  "link_exp": 24,
  "network": "bitcoin",
  "recipient_email": "testing@betaapp.com",
  "source_asset": "BTC",
  "target_amount": 3500,
  "target_asset": "BRL"
}'
```

{% endcode %}

**Response Example:**

```json
{
  "asset": {
    "name": "Bitcoin",
    "symbol": "BTC",
    "type": "crypto",
    "small_image_url": "https://storage.googleapis.com/cryptoassets_images/20px/BTC-20.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=840657900520-compute%40developer.gserviceaccount.com%2F20230914%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20230914T141816Z&X-Goog-Expires=1199&X-Goog-Signature=9ca0f9729d3a8e25814653e670cc28f8db8e25ca386c477745e1fb8a36744c0bc7b35f21d13d14a0aaaed21558ccc2ef3817236b2468a7bf3243947adfecc9b3d319b4e054293916dbb4bfcff1f4f87dcf5dadb80db7b4ecf38a6d251a5a9977b797a9f6018da38c4721eeeec3d449f1bac5bc27831a29fb44ff75ea4209b11388614bd47213597363bf50d4a6af2684e874db0a406f8b8694f89a58c56691e5974668e0cbf8d8edc2bbc8e7786a421f18ec13e40489598a2ef78694824953e353a8115eef8f9d16e1d99b71ecefe951914a14d66d23ee800db6525d78d541e59b396592ba8eb3d72674b49be175e082251d8a433f26a20ac97d9d95a596ea55&X-Goog-SignedHeaders=host",
    "medium_image_url": "https://storage.googleapis.com/cryptoassets_images/35px/BTC-35.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=840657900520-compute%40developer.gserviceaccount.com%2F20230914%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20230914T141816Z&X-Goog-Expires=1199&X-Goog-Signature=aa9cbcb5cc9eb44210d41dbb9180fa42823c1f78cae951b32e1e8fa58bf80e57be5b61f06c400e414f3e533e3209e080d1aad7d1c15c769d21936695fac0e9c0614717d931528cb82299c21ec23399b173c63695a30de41ab330fc609180838324051a967b5d0f1ec3472f82369a35b01139dfc5f8f464e9c883a7d18b8674714852412bc764cad22b85c11ee5e2dd921f5e288fc41c8f7898f8ac308b9ac92f4be0e3f271fd47c628b9edc791fb7cd5ee9264d8cd29a3a09469923273fd5e532f9c45ddcf42c66552e4cf007058ac54bc76cfb8ac6ce978f99172f84a8bbe1a82dee96267d51250a9c725599358fb857bd3263c9de516a28d55261a8587f8e5&X-Goog-SignedHeaders=host",
    "large_image_url": "https://storage.googleapis.com/cryptoassets_images/69px/BTC-69.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=840657900520-compute%40developer.gserviceaccount.com%2F20230914%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20230914T141816Z&X-Goog-Expires=1199&X-Goog-Signature=a79ef8b30dea1887cf46b36eff8f003f7e524667df6118cf23824349c9aba8751ca8d7fe10036f8a216625f7134eca554b7ad19c39f9e24b9c23bb60a2160541a2a752fdda6f033dddc79f837d5869fef85a4b6f546770c2accd8f66241c1a686e07f85b1c5620e739fac10b4e93bae5cfae8f44ae2bf1374a0895dd801c4555ec41dbea267d390c554858c05fc469b00c7a527b3a63703fb9567da277482877d874071b1cb98d5a17e7643071a9057068998ce50b9341e5f435d823ac48f4545ce13e97ecd724dc9caf504f95c366b2382865128a2a6d29ded89fe04061a18feec4f9416149a5c41bb5aa6a778805c19ed500462ae140b33b2843c1d7757f76&X-Goog-SignedHeaders=host"
  },
  "amount": 0.027916,
  "network": "bitcoin",
  "wallet_address": "bc1qdus0ghjhxcr3eyw4rcswlpvr8w34wpf6thexs8",
  "tag": "",
  "exp_time": 1200,
  "deposit": false,
  "date_time": "2023-09-14T14:18:25.510733216Z"
}
```

**Displaying the information:**

{% hint style="info" %}
The `wallet_address`, `tag`, and `network`, are the parameters you should use to display the crypto deposit details.
{% endhint %}

**Here is an example of how the New Order Response could be displayed on the Front-End**

<figure><img src="/files/9MZfl38EC7Kmf26yWyTd" alt=""><figcaption><p>Wallet address displayed on the Checkout</p></figcaption></figure>

## Retrieve Order List

<mark style="color:blue;">`GET`</mark> `https://live.betaapp.com/v1/order`

This endpoint retrieves the Order List of a specific `account_id` or `subaccount_id`.

You can also filter the list by `status`, `e-mail`, or `description`.

#### Query Parameters

| Name                                   | Type    | Description                                                        |
| -------------------------------------- | ------- | ------------------------------------------------------------------ |
| order\_by                              | String  | Parameters: id, recipient\_email, description, created\_at, status |
| search                                 | String  | It could be e-mail or description                                  |
| status                                 | String  | *Parameters: open, pending, confirmed, canceled.*                  |
| page<mark style="color:red;">\*</mark> | Integer | Page number for this query                                         |
| size<mark style="color:red;">\*</mark> | Integer | Number of items per page                                           |

#### Headers

| Name                                            | Type   | Description                  |
| ----------------------------------------------- | ------ | ---------------------------- |
| x-sub-account-id                                | String | Only If you have subaccounts |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {access\_token}       |
| accept<mark style="color:red;">\*</mark>        | String | application/json             |

{% tabs %}
{% tab title="200: OK " %}

```
{
  "message": "string",
  "orders": [
    {
      "account_id": "string",
      "created_at": "string",
      "description": "string",
      "id": "string",
      "recipient_email": "string",
      "status": "string",
      "target_amount": 0,
      "target_asset": "string",
      "valid_until": "string"
    }
  ]
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

<pre><code><strong>{
</strong>  "message": "string"
}
</code></pre>

{% endtab %}
{% endtabs %}

**Request Example:**

{% code overflow="wrap" %}

```json
  curl -X 'GET' \
  'https://live.betaapp.com/v1/order?page=10&size=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJlaEF1NURPY...ctfx2I4g'
```

{% endcode %}

**Response Example:**

```json
{
  "message": "success",
  "orders": [
    {
      "id": "abf4cbc6-65a8-4643-9d27-f04ba86e22dd",
      "account_id": "a2b6b539...484097",
      "sub_account_id": "94850a8c...881047"
      "recipient_email": "testing@betaapp.com",
      "description": "2x Tickets for England vs Germany football match",
      "status": "pending",
      "source_asset": "BTC",
      "source_amount": 0.20,
      "target_asset": "BRL",
      "target_amount": 3500,
      "valid_until": "2023-09-17T14:18:20.510288Z",
      "created_at": "2023-09-14T14:18:20.510288Z"
    },
    {
      "id": "ab6e6ed4-503a-46f3-a514-2cae05c4edda",
      "account_id": "a2b6b539...99484097",
      "sub_account_id": "94850a8c...881047"
      "recipient_email": "testing@betaapp.com",
      "description": "Testing Payment",
      "status": "open",
      "source_asset": "BTC",
      "source_amount": 0.0016,
      "target_asset": "MXN",
      "target_amount": 1000,
      "valid_until": "2023-09-16T19:04:22.407027Z",
      "created_at": "2023-09-13T19:04:22.407027Z"
    }
  ],
  "page": 1,
  "size": 10,
  "total_page": 1,
  "total_row": 2
}
```

## Retrieve Order Details

<mark style="color:blue;">`GET`</mark> `https://live.betaapp.com/v1/order/details/{id}`

This endpoint provides all the detail for a specific payment.

#### Query Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | String | Order ID    |

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | Srting | Bearer {access\_token} |
| accept<mark style="color:red;">\*</mark>        | String | application/json       |

{% tabs %}
{% tab title="200: OK " %}

```
{
  "created_at": "string",
  "description": "string",
  "id": "string",
  "message": "string",
  "recipient_email": "string",
  "settlement_status": "string",
  "status": "string",
  "target_amount": 0,
  "target_asset": "string",
  "timelines": [
    {
      "comments": "string",
      "executed": true,
      "executed_at": "string",
      "order_step": "string"
    }
  ]
}
```

{% endtab %}

{% tab title="400: Bad Request " %}

<pre><code><strong>{
</strong>  "message": "string"
}
</code></pre>

{% endtab %}
{% endtabs %}

**Request Example:**

{% code overflow="wrap" %}

```json
curl -X 'GET' \
  'https://live.betaapp.com/v1/order/details/abf4cbc6-65a8-4643-9d27-f04ba86e22dd' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJlaEF1NURPY...ctfx2I4g'
```

{% endcode %}

**Response Example:**

```json
{
  "id": "abf4cbc6-65a8-4643-9d27-f04ba86e22dd",
  "source_asset": "BTC",
  "source_amount": 0.20,
  "target_asset": "BRL",
  "target_amount": 3500,
  "description": "2x Tickets for England vs Germany football match",
  "recipient_email": "testing@betaapp.com",
  "status": "pending",
  "settlement_status": "",
  "created_at": "2023-09-14T14:18:20.510288Z",
  "timelines": [
    {
      "order_step": "Order Created",
      "executed": true,
      "comments": "",
      "executed_at": "2023-09-14T14:18:20.510288Z"
    },
    {
      "order_step": "Payment Link Opened",
      "executed": true,
      "comments": "",
      "executed_at": "2023-09-14T14:18:23.291284Z"
    },
    {
      "order_step": "Deposit Initiated",
      "executed": true,
      "comments": "",
      "executed_at": "2023-09-14T14:18:27.875453Z"
    },
    {
      "order_step": "Paid",
      "executed": false,
      "comments": "",
      "executed_at": "0001-01-01T00:00:00Z"
    },
    {
      "order_step": "Settlement",
      "executed": false,
      "comments": "",
      "executed_at": "0001-01-01T00:00:00Z"
    }
  ]
}
```