# Buy Order

This `POST` endpoint is responsible for making a buy order and returns the checkout url and access token.

The buy order `POST` api takes your `publicKey` as a required parameter in the header and a body containing properties like the customer's email, phone number, customer deposit, receipt methods, etc. Unlike the standard buy endpoint, this will return additional properties like `checkoutUrl`, and `accessToken` which can be used to redirect your users and continue the order flow. 

A boolean property called `deferPaymentMethod` is added to the request body which can be set to true to delay providing your users' payment methods to initiate any of the order endpoints. It can also be set to false if you intend to provide the details and require a confirmation of the request immediately.

{% hint style="info" %}
When `deferPaymentMethod` is set to true, a call to [initiate-order-created-with-deferred-payment-method](https://doc.xendbridge.com/xendbridge-portal/checkout-url/initiate-order-created-with-deferred-payment-method "mention") should be made to complete the order initiation.
{% endhint %}

See the example below

## Initiates a buy order

<mark style="color:green;">`POST`</mark> `https://checkout-api-sandbox.xendbridge.com/api/ThirdPartyUI/Buy/Initiate`

#### Headers

| Name                                        | Type | Description |
| ------------------------------------------- | ---- | ----------- |
| publicKey<mark style="color:red;">\*</mark> |      | {publicKey} |

#### Request Body

| Name                                                       | Type   | Description                                |
| ---------------------------------------------------------- | ------ | ------------------------------------------ |
| emailAddress<mark style="color:red;">\*</mark>             |        | <annadoe@gmail.com>                        |
| phoneNumber<mark style="color:red;">\*</mark>              |        | 07064366723                                |
| userName<mark style="color:red;">\*</mark>                 |        | annadoe                                    |
| payInCurrencyCode<mark style="color:red;">\*</mark>        |        | NGN                                        |
| payInCurrencyNetwork<mark style="color:red;">\*</mark>     |        | LOCAL                                      |
| receiveInCurrencyCode<mark style="color:red;">\*</mark>    |        | BUSD                                       |
| receiveInCurrencyNetwork<mark style="color:red;">\*</mark> |        | BEP20                                      |
| orderAmount<mark style="color:red;">\*</mark>              |        | 50                                         |
| consumerDepositMethod<mark style="color:red;">\*</mark>    | Object |                                            |
| paymentMethod<mark style="color:red;">\*</mark>            |        | Bank                                       |
| paymentData<mark style="color:red;">\*</mark>              | Object |                                            |
| accountName<mark style="color:red;">\*</mark>              |        | John Doe                                   |
| accountNumber<mark style="color:red;">\*</mark>            |        | 0000187849                                 |
| bankName<mark style="color:red;">\*</mark>                 |        | Access Bank                                |
| consumerReceiptMethod<mark style="color:red;">\*</mark>    | Object |                                            |
| paymentMethod<mark style="color:red;">\*</mark>            |        | Crypto                                     |
| paymentData<mark style="color:red;">\*</mark>              | Object |                                            |
| walletAddress<mark style="color:red;">\*</mark>            |        | 0x52434Ac4BE04393e020c9b16C327d04d4367Cbcd |
| network<mark style="color:red;">\*</mark>                  |        | BEP-20                                     |
| deferPaymentMethod<mark style="color:red;">\*</mark>       | bool   | false                                      |

{% tabs %}
{% tab title="400: Bad Request Initiating another buy order while one is not finished is not allowed." %}

```javascript
{
    "Status": 2,
    "Message": "You Have A Pending Buy Order",
    "Data": null
}
```

{% endtab %}

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

```json
{
    "data": {
        "checkoutReference": "XCHKB_cfbb41a03e62402f875b40664c606df6fe526d10efda4e779585431fbb6ba583",
        "orderReference": "XB_8986d97efdfb402298f0aa009cf9c998",
        "checkoutUrl": "https://checkout-sandbox.xendbridge.com/order?ref=XCHKB_cfbb41a03e62402f875b40664c606df6fe526d10efda4e779585431fbb6ba583",
        "accessToken": "622654",
        "receiveInCurrencyCode": "BUSD",
        "payInCurrencyCode": "NGN",
        "customerPayInCurrencyNetwork": "LOCAL",
        "customerReceieveInCurrencyNetwork": "BEP20",
        "receivableAmount": 0.06597263,
        "payableAmount": 50.0,
        "receivableAmountWithoutMarkup": 0,
        "providerName": "John Doe",
        "providerFirstName": "John",
        "providerLastName": "Doe",
        "providerEmail": "owolabidamilola98@gmail.com",
        "initiatedAt": "2023-02-13T11:32:19.3426901Z",
        "orderExpiryDate": "2023-02-13T11:37:19.30397Z",
        "initiatedAtTimestamp": 1676287939303,
        "orderExpiryTimestamp": 1676288239303,
        "estimatedOrderCompletionTimestamp": null,
        "fundedProviderAtTimeStamp": null,
        "fundedCustomerAtTimeStamp": null,
        "orderCompletedAtTimeStamp": null,
        "p2POrderStatus": "Acknowledged",
        "disputeStatus": "NoDispute",
        "disputeReference": null,
        "orderType": "Buy",
        "providerContact": {
            "phoneNumber": "2348181186644",
            "whatsappNumber": ""
        },
        "customerContact": {
            "email": null,
            "name": null,
            "phoneNumber": null
        },
        "providerPaymentMethods": {
            "paymentMethod": "Bank",
            "paymentType": "Bank",
            "paymentData": [
                {
                    "bankName": "Access",
                    "accountNumber": "0709876786",
                    "accountName": "John Doe",
                    "address": null,
                    "swiftCode": null,
                    "iban": null,
                    "sortCode": null,
                    "currency": "NGN",
                    "network": "LOCAL"
                }
            ],
            "orderPaymentMethod": {
                "bankName": "Access",
                "accountNumber": "0709876786",
                "accountName": "John Doe",
                "address": null,
                "swiftCode": null,
                "iban": null,
                "sortCode": null,
                "currency": "NGN",
                "network": "LOCAL"
            }
        },
        "consumerDepositMethod": {
            "paymentMethod": "Bank",
            "paymentType": 0,
            "paymentData": {
                "bankName": "Access Bank",
                "accountNumber": "0000187849",
                "accountName": "Emmanuel Diala",
                "address": null,
                "swiftCode": null,
                "iban": null,
                "sortCode": null,
                "currency": "NGN",
                "network": "LOCAL"
            }
        },
        "consumerReceiptMethod": {
            "paymentMethod": "Crypto",
            "paymentType": 0,
            "paymentData": {
                "walletAddress": "0x52434Ac4BE04393e020c9b16C327d04d4367Cbcd",
                "network": "BEP20",
                "currency": "BUSD"
            }
        },
        "providerTransactionMetadata": null,
        "customerTransactionMetadata": null
    },
    "status": "OK",
    "message": ""
}
```

{% endtab %}
{% endtabs %}

<details>

<summary>JSON Request Format</summary>

```json
{
  "emailAddress": "annadoe@gmail.com",
  "phoneNumber": "07064366723",
  "userName": "annadoe",
  "payInCurrencyCode": "NGN",
  "payInCurrencyNetwork": "LOCAL",
  "receiveInCurrencyCode": "BUSD",
  "receiveInCurrencyNetwork": "BEP20",
  "orderAmount": 50,
  "deferPaymentMethod": false,
  "consumerDepositMethod": {
    "paymentMethod": "Bank",
    "paymentData": {
      "accountName": "Emmanuel Diala",
      "accountNumber": "0000187849",
      "bankName": "Access Bank"
    }
  },
  "consumerReceiptMethod": {
    "paymentMethod": "Crypto",
    "paymentData": {
      "walletAddress": "0x52434Ac4BE04393e020c9b16C327d04d4367Cbcd",
      "network": "BEP20"
    }
  }
}
```

</details>

If `deferPaymentMethod` is set to true, you can provide the minimum payload below which starts the order initiation process and returns the ***checkoutUrl*** .

<details>

<summary>JSON Request Format</summary>

```json
{
  "emailAddress": "johndoe@gmail.com",
  "phoneNumber": null,
  "userName": "johndoe",
  "payInCurrencyCode": "NGN",
  "payInCurrencyNetwork": "LOCAL",
  "receiveInCurrencyCode": "BUSD",
  "receiveInCurrencyNetwork": "BEP20",
  "orderAmount": 1,
  "deferPaymentMethod": true
}
```

</details>

{% tabs %}
{% tab title="Request Fields" %}

<table><thead><tr><th width="198.11337367685582">Parameters</th><th width="150">Type</th><th width="167">Definitions</th></tr></thead><tbody><tr><td>emailAddress</td><td>string</td><td><code>Required</code> This is the consumer's email address.</td></tr><tr><td>phoneNumber</td><td>string</td><td><code>Required</code> This is the consumer's phone number.</td></tr><tr><td>userName</td><td>string</td><td><code>Required</code> This is the consumer's username</td></tr><tr><td>payInCurrencyCode</td><td>enum</td><td><code>Required</code> This is the currency code to pay with. Must be <code>NGN</code> for buy order.</td></tr><tr><td>receiveInCurrencyCode</td><td>enum</td><td><code>Required</code> This is the currency code to receive the currency in. Must be <code>BUSD</code> for buy order.</td></tr><tr><td>orderAmount</td><td>decimal</td><td><code>Required</code> The order amount by the consumer.</td></tr><tr><td>consumerDepositMethod</td><td>object</td><td><code>Required</code> This holds the properties of the deposit method of the consumer which is are the bank details.</td></tr><tr><td>paymentMethod</td><td>enum</td><td><code>Required</code> The payment method by which transactions are made. It should be <code>BANK</code>for buy order.</td></tr><tr><td>paymentData</td><td>object</td><td><code>Required</code> This holds the properties of the bank details of the consumer.</td></tr><tr><td>accountName</td><td>string</td><td><code>Required</code> This is the account name of the consumer.</td></tr><tr><td>accountNumber</td><td>string</td><td><code>Required</code> The local account number of the consumer</td></tr><tr><td>bankName</td><td>string</td><td><code>Required</code> This is the bank name of the consumer.</td></tr><tr><td>consumerReceiptMethod</td><td>object</td><td><code>Required</code> This holds the properties of the consumer receiving method. The <code>paymentMethod</code> prop must be <code>Crypto</code> .</td></tr><tr><td>paymentData</td><td>object</td><td><code>Required</code> This holds the properties of the consumer receiving account details.</td></tr><tr><td>walletAddress</td><td>string</td><td><code>Required</code> The crypto wallet address of the consumer.</td></tr><tr><td>network</td><td>string</td><td><code>Required</code> This is the network on which the address is on.</td></tr></tbody></table>
{% endtab %}

{% tab title="Response Fields" %}

<table><thead><tr><th width="289.9265033407573">Parameters</th><th width="150">Type</th><th>Definitions</th></tr></thead><tbody><tr><td>checkoutReference</td><td>string</td><td>This is the reference to the checkout order.</td></tr><tr><td>orderReference</td><td>string</td><td>This the reference to a particular order.</td></tr><tr><td>checkoutUrl</td><td>string</td><td>This is the url created from the request and can be used to contiue</td></tr><tr><td>accessToken</td><td>string</td><td></td></tr><tr><td>receiveInCurrencyCode</td><td>enum</td><td>This is the currency code to receive the currency in.</td></tr><tr><td>payInCurrencyCode</td><td>enum</td><td>This is the currency code to pay with.</td></tr><tr><td>receivableAmount</td><td>decimal</td><td>This the receivable amount of the currency.</td></tr><tr><td>payableAmount</td><td>decimal</td><td>This is the payable amount of the currency.</td></tr><tr><td>providerName</td><td>string</td><td>This the provider's name.</td></tr><tr><td>providerFirstName</td><td>string</td><td>This is the provider's first name.</td></tr><tr><td>providerLastName</td><td>string</td><td>This is the provider's last name.</td></tr><tr><td>providerEmail</td><td>string</td><td>This is the provider's email address.</td></tr><tr><td>initiatedAt</td><td>DateTime</td><td>The date time the order was made.</td></tr><tr><td>orderExpiryDate</td><td>DateTime</td><td>The expiry date time of the order.</td></tr><tr><td>initiatedAtTimestamp</td><td>long</td><td>The time in milliseconds an order was made</td></tr><tr><td>orderExpiryTimestamp</td><td>long</td><td>The time in milliseconds of when thee order will expire.</td></tr><tr><td>fundedProviderAtTimeStamp</td><td>long</td><td>The time of when a customer indicates payment for an order in milliseconds.</td></tr><tr><td>fundedCustomerAtTimeStamp</td><td>long</td><td>The time of when a provider indicates payment of order to the customer in milliseconds</td></tr><tr><td>orderCompletedAtTimeStamp</td><td>long</td><td>The time in milliseconds an order was completed.</td></tr><tr><td>p2POrderStatus</td><td>enum</td><td>The status of the order at the curent time. It could be <code>Submitted</code>, <code>Cancelled</code>, <code>Acknowledged</code>, <code>FundedProvider</code>, <code>FundReceivedFromUser</code>, <code>FundedUser</code>, <code>Completed</code>, <code>OrderTimedOut</code></td></tr><tr><td>disputeStatus</td><td>enum</td><td>The status of the dispute on an order. It could either be <code>NoDispute</code>, <code>DisputeRaisedByCustomer</code>, <code>DisputeRaisedByProvider</code>, <code>DisputeRaisedByBothParties</code>, <code>DisputeResolved</code>or <code>CouldNotBeResolved</code>.</td></tr><tr><td>orderType</td><td>enum</td><td>This is the status of the order, whether it's a <code>Buy</code> or <code>Sell</code>.</td></tr><tr><td>providerContact</td><td>object</td><td>This is holds properties of a provider's contact information.</td></tr><tr><td>phoneNumber</td><td>string</td><td>The phone number of either the provider or customer.</td></tr><tr><td>whatsappNumber</td><td>string</td><td>The whatsapp number of either the provider or customer.</td></tr><tr><td>customerContact</td><td>object</td><td>This holds the props of the contact information.</td></tr><tr><td>email</td><td>string</td><td>This is an email address of the customer.</td></tr><tr><td>name</td><td>string</td><td>This is the name of the customer.</td></tr><tr><td>phoneNumber</td><td>string</td><td>The phone number of the customer</td></tr><tr><td>providerPaymentMethods</td><td>object</td><td>This holds the properties of the payment methods of the provider.</td></tr><tr><td>paymentMethod</td><td>enum</td><td>This is the method of payment. It could be <code>Bank</code> or <code>Crypto</code></td></tr><tr><td>paymentType</td><td>enum</td><td>This is the type of payment. It could be <code>Bank</code>, <code>Crypto</code>, <code>UserName</code>or <code>MobileMoney</code>.</td></tr><tr><td>paymentData</td><td>object</td><td>This holds the properties of the payment method.</td></tr><tr><td>bankName</td><td>string</td><td>The bank name of the the provider or customer.</td></tr><tr><td>accountNumber</td><td>string</td><td>The bank account number of the provider or customer.</td></tr><tr><td>accountName</td><td>string</td><td>The bank account name of the provider or customer.</td></tr><tr><td>currency</td><td>enum</td><td>The currency in which the order was made. It could be <code>BUSD</code> or <code>NGN</code>.</td></tr><tr><td>orderPaymentMethod</td><td>object</td><td>This holds properties of the payment method in which the order is to be made to.</td></tr><tr><td>consumerDepositMethod</td><td>object</td><td>This holds the properties of the consumer deposit details.</td></tr><tr><td>consumerrReceiptMethod</td><td>object</td><td>This holds the properties of the consumer receiving method details.</td></tr><tr><td>walletAddress</td><td>string</td><td>This is the crypto wallet address of the consumer.</td></tr><tr><td>network</td><td>enum</td><td>This is the network currently supported in the system which the wallet address is based on.</td></tr><tr><td>providerTransactionMetadata</td><td>object</td><td>This holds the properties of the transaction metadata of an order.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}