# 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"
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.betaramps.com/documentation-beta-ramps/request-payments/crypto-payment-orders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.