# Create Buy Order Endpoint

<mark style="color:green;">`POST`</mark> `https://exchanger-api.fuspay.finance/api/v1/no-auth/Axis/BuyUsdtWithFiat/`

All events will be communicated to the callback registered in the post request.

Event body will be updated as buy order progresses through the following phases:&#x20;

a. event.buy.init  (buy order started, awaiting fiat payment)

b. event.buy.received.fiat (fiat payment received)

c. event.buy.credited.crypto (transaction completed)

d. event.buy.error (error occurred)

<mark style="color:red;">Event body is signed with sha 512. sha512(body, public\_key+secret\_key)</mark>

### The diagram below shows the complete flow of a buy order&#x20;

<figure><img src="/files/MUfTuCM3ll7yZEmVNMBe" alt=""><figcaption></figcaption></figure>

{% file src="/files/RvKKZkFeu3vw6pdskPNz" %}

{% hint style="danger" %}
Axis does not handle third party on-ramp orders.  i.e . The name of the user, the payer bank account, has to pass 66% name match with the user's KYC name on Axis.\
\
All transactions that fail this test will be pending.  See the ["Pending Transactions"](https://app.gitbook.com/o/UlsbQabTdQpnUffvzs7w/s/FU24OF8juMGRM9K7EdyI/~/changes/37/order-history-and-status/pending-transactions) side bar for more information

{% endhint %}

#### Headers

| Name                                            | Type   | Description                      |
| ----------------------------------------------- | ------ | -------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | "Bearer ${partner\_secret\_key}" |
| x-partner-id<mark style="color:red;">\*</mark>  | String | "pxxxxxx"                        |

#### Request Body

<table><thead><tr><th width="220">Name</th><th width="163">Type</th><th>Description</th></tr></thead><tbody><tr><td>partner_order_id<mark style="color:red;">*</mark></td><td>String </td><td>id of your order</td></tr><tr><td>fiat_amount<mark style="color:red;">*</mark></td><td>String</td><td>the FIAT amount to be paid by the buyer </td></tr><tr><td>chain<mark style="color:red;">*</mark></td><td>String</td><td>e.g. "usdt-trc20", "usdc-matic", "eusd-mob", "usdt-pol".</td></tr><tr><td>buyer_crypto_address<mark style="color:red;">*</mark></td><td>STring</td><td>The buyer's crypto address </td></tr><tr><td>partner_callback_url<mark style="color:red;">*</mark></td><td>STring</td><td>your partner callback URL </td></tr><tr><td>fiat_currency<mark style="color:red;">*</mark></td><td>String</td><td>the fiat currency of the crypto-fiat pair eg. NGN, KHS, GHS</td></tr><tr><td>buyer_phone<mark style="color:red;">*</mark></td><td>String</td><td>The is the phone number of the buyer. This is collected for KYC purpose </td></tr><tr><td>buyer_email<mark style="color:red;">*</mark></td><td>String</td><td>This is an email representing the buyer. Also for KYC</td></tr><tr><td>first_name<mark style="color:red;">*</mark></td><td>String</td><td>The buyer's first name </td></tr><tr><td>last_name<mark style="color:red;">*</mark></td><td>String </td><td>Seller's last name</td></tr><tr><td>intrapay_merchant_id<mark style="color:red;">*</mark></td><td>String </td><td>Intrapay Merchant ID is a unique identification number gotten by signing up and setting up your wallet on Intrapay.</td></tr><tr><td>markup_fee<mark style="color:red;">*</mark></td><td>String</td><td>This is the percentage charge that would be applied in the transaction with the merchant. It is paid into your intrapay wallet.</td></tr><tr><td>refund_bank<mark style="color:red;">*</mark></td><td>String</td><td>this is bank code where the fiat will be refunded incase of an incomplete transaction</td></tr><tr><td>refund_account<mark style="color:red;">*</mark></td><td>String</td><td>this is account number where the fiat will be refunded incase of an incomplete transaction</td></tr><tr><td>refund_fullname<mark style="color:red;">*</mark></td><td>String</td><td>this is account name of the user where the refund will be sent to</td></tr></tbody></table>

Sample Request Body&#x20;

<pre class="language-json"><code class="lang-json">{
  "partner_order_id": "LIVE-TXN-TEST-007123",
  "fiat_currency": "KHS",
  "buyer_crypto_address": "0x8de6e4fc94464a74ee153ef159b5b636678aa57f",
  "chain": "usdt-trc20",
  "fiat_amount": "3000",
  "partner_callback_url": "https://webhook.site/f63c3262-55f3-462a-8ce1-49ea28c47038",
  "buyer_phone": "11111111",
  "buyer_email": "xxx@gmail.com",
  "first_name": "",
  "last_name": "",
  "intrapay_merchant_id":"",
  "markup_fee":"",
  "refund_bank": "", 
<strong>  "refund_account": "",
</strong>  "refund_fullname": ""
}
</code></pre>

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

{% code overflow="wrap" %}

```
Response {
"message":"OK"
}

The actual response (Event Body) is sent to your callback URL. we send to your callback URL to make responses fast.

```

{% endcode %}
{% endtab %}

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

{% endtab %}
{% endtabs %}

BUY EVENTS

{% tabs %}
{% tab title="event.buy.init (1)" %}

```json
{
    "event_name": "event.buy.init",
    "partner_order_id": "BETA-TEST-FUSPAY-0001",
    "fuspay_order_ref": "BETA-TEST-FUSPAY-0001_p176517",
    "fiat_amount_to_pay": 100,
    "crypto_amount_to_receive": 10,
    "exchange_rate": 10,
    "pair": "NGN/USDT",
    "fiat_currency": "NGN",
    "buyer_crypto_address": "TBqNaN3CvyuTmnMe55oRCzadZ1iAxYHrKr",
    "chain": "usdt-trc20",
    "fiat_payment_status": "PENDING",
    "crypto_payment_status": "PENDING",
    "payer_into_account": {
        "account_name": "Paypoint NA",
        "account_number": "9628586981",
        "bank_name": "Providus Bank"
    },
    "payment_link": null,
    "crypto_txn_hash": null,
    "partner_callback_url": "https://webhook.site/7659f3d1-e7a1-4671-88c8-949e6850dbb7",
    "transactional_kyc": {
        "email": "",
        "phone": "",
        "first_name": "",
        "last_name": ""
    },
    "signature": "6155296856767b99b28f3d11bdc3da770c0b1bb42059af6c774a42e459965359f1c5290b627acf09ce686d16cc42ed4"
}
```

{% endtab %}

{% tab title="event.buy.received.fiat (2)" %}

```json
{
    "event_name": "event.buy.received.fiat",
    "partner_order_id": "BETA-TEST-FUSPAY-0001",
    "fuspay_order_ref": "BETA-TEST-FUSPAY-0001_p176517",
    "fiat_amount_to_pay": 100,
    "crypto_amount_to_receive": 10,
    "exchange_rate": 10,
    "pair": "NGN/USDT",
    "fiat_currency": "NGN",
    "buyer_crypto_address": "TBqNaN3CvyuTmnMe55oRCzadZ1iAxYHrKr",
    "chain": "usdt-trc20",
    "fiat_payment_status": "PAID",
    "crypto_payment_status": "STARTED",
    "payer_into_account": {
        "account_name": "Paypoint NA",
        "account_number": "9628586981",
        "bank_name": "Providus Bank"
    },
    "payment_link": null,
    "crypto_txn_hash": null,
    "partner_callback_url": "https://webhook.site/7659f3d1-e7a1-4671-88c8-949e6850dbb7",
    "transactional_kyc": {
        "email": "",
        "phone": "",
        "first_name": "",
        "last_name": ""
    },
    "signature": "615529685924e0ab350cb28f3d11bdc3da770c0b1bb42059af6c774a42e459965359f1c5290b627acf09ce686d16cc42ed4"
}
```

{% endtab %}

{% tab title="event.buy.received.fiat\_kyc\_error (3)" %}

```json
//The kyc_error_type message could either be "NO_KYC", for when user has not done KYC or "THIRD_PARTY_ERROR", for when the buyer's fiat payment account name is different from the transctional kyc name.
{
    "event_name": "event.buy.received.fiat_kyc_error",
    "partner_order_id": "SENTZ-BUY-ORDER-TEST-MY-IP-16",
    "fuspay_order_ref": "SENTZ-BUY-ORDER-TEST-MY-IP-10_p533522",
    "fiat_amount_to_pay": 15000,
    "crypto_amount_to_receive": 10.07,
    "exchange_rate": 1490,
    "pair": "NGN/USDT",
    "fiat_currency": "NGN",
    "buyer_crypto_address": "TYYui3F5E7BjATJGBjgpk5fAn90CtfvNan",
    "chain": "usdt-trc20",
    "fiat_payment_status": "PAID",
    "crypto_payment_status": "STARTED",
    "payer_into_account": {
        "account_name": "Paypoint NA",
        "account_number": "9628586981",
        "bank_name": "Providus Bank"
    },
    "payment_link": null,
    "crypto_txn_hash": null,
    "partner_callback_url": "https://ec0b-2600-1700-f90-55f0-494-231d-7b2c-17da.ngrok-free.app",
    "transactional_kyc": {
        "email": "",
        "phone": "",
        "first_name": "",
        "last_name": ""
    },
    "signature": "5a596214cc2f1c3ecad6d8alf0fab65ed5d30112b722ed1ld3c9c3ee6",
    "created_at": "2024-06025T14:55:02.080Z",
    "sender_name": "AYANTOLA, TESLIM",
    "default_kyc_url": "https://kyc.fuspay.finance",
    "message": "Buyer needs to perform KYC",
    "kyc_error_type": "NO_KYC"
}

{
    "event_name": "event.buy.received.fiat_kyc_error",
    "partner_order_id": "SENTZ-BUY-ORDER-TEST-MY-IP-16",
    "fuspay_order_ref": "SENTZ-BUY-ORDER-TEST-MY-IP-16_p533522",
    "fiat_amount_to_pay":15500,
    "crypto_amount_to_receive":10.21,
    "exchange_rate":1518,
    "pair":"NGN/USDT",
    "fiat_currency":"NGN",
    "buyer_crypto_address": "TYYur3F5E7BjATJGBjgpk5fAm9DCtfvNmn",
    "chain":"usdt-trc20",
    "fiat_payment_status":"PAID",
    "crypto_payment_status":"STARTED",
    "payer_into_account":{                     
        "account_name":"Paypoint NA",  
        "account_number":"9610880057",
        "bank_name":"Providus Bank"
    }, 
    "payment_link":null,
    "crypto_txn_hash":null,
    "partner_callback_url":"https://ec0b-2600-1700-f90-55f0-494-231d-7b2c-17da.ngrok-free.app",
    "transactional_kyc":{
    "email":"",
    "phone":"",                           
    "first_name":"",                 
    "last_name":""
    },
    "signature": "617dc884f8061ee67b834b61487552d6b2bc1d9812d9b8efbb650ccd5965623f65ce24f21c",
    "created_at":"2024-06-28T15:15:13.000Z",
    "sender_name":"QProject Technologies Limited  Avis Charles Ayodeji",
    "default_kyc_url":null,
    "message":"Third Party Payment",
    "kyc_error_type":"THIRD_PARTY_PAYMENT"
}
```

{% endtab %}

{% tab title="event.buy.credited.crypto (4)" %}

```json
{
    "event_name": "event.buy.credited.crypto",
    "partner_order_id": "BETA-TEST-FUSPAY-0001",
    "fuspay_order_ref": "BETA-TEST-FUSPAY-0001_p176517",
    "fiat_amount_to_pay": 100,
    "crypto_amount_to_receive": 10,
    "exchange_rate": 10,
    "pair": "NGN/USDT",
    "fiat_currency": "NGN",
    "buyer_crypto_address": "TBqNaN3CvyuTmnMe55oRCzadZ1iAxYHrKr",
    "chain": "usdt-trc20",
    "fiat_payment_status": "PAID",
    "crypto_payment_status": "PAID",
    "payer_into_account": {
        "account_name": "Paypoint NA",
        "account_number": "9628586981",
        "bank_name": "Providus Bank"
    },
    "payment_link": null,
    "crypto_txn_hash": "f028a30dcc063a2c54e51c5babb3aa439afcd7393e7a5213145c1a9e5585a7",
    "partner_callback_url": "https://webhook.site/7659f3d1-e7a1-4671-88c8-949e6850dbb7",
    "transactional_kyc": {
        "email": "",
        "phone": "",
        "first_name": "",
        "last_name": ""
    },
    "signature": "29ab5f53ab696cf2cd5c0ebe429a8a6c145a705aa54dee3dd8bff48800b94b123c7beae6092d4f6de"
}
```

{% endtab %}

{% tab title="buy.event.close" %}

```json5
{
  event_name: 'buy.event.close',
  partner_order_id: string,
  fuspay_order_ref: string,
  fiat_amount_to_pay: number,
  crypto_amount_to_receive: number,
  exchange_rate: string,
  pair: 'NGN/EUSD',
  fiat_currency: 'NGN',
  buyer_crypto_address:string,
  chain: 'eusd-mob',
  fiat_payment_status: string,
  crypto_payment_status: string,
  payer_into_account: {
    account_name: string,
    account_number: string,
    bank_name: string
  },
  payment_link: null,
  crypto_txn_hash: null,
  partner_callback_url: string,
  transactional_kyc: { email: string, phone: string, first_name: string, last_name: string },
  signature: string,
  meta_data: {
    status: 'refunded',
    message: 'buyer has been refunded',
    refund_account: string,
    amount_refunded: string,
    fee: number
  }
}

```

{% endtab %}
{% endtabs %}

### Event Body Description

<table><thead><tr><th width="214">Keys</th><th width="264">Description</th><th>Values</th></tr></thead><tbody><tr><td>event_name</td><td>This is the name of the buy event</td><td>event buy init, event buy received fiat, event buy credited crypto.</td></tr><tr><td>partner_order_id</td><td>Id of order generated on partner's system</td><td></td></tr><tr><td>fuspay_order_ref</td><td>Reference number of order generated on Fuspay system</td><td></td></tr><tr><td>fiat_amount_to_pay</td><td>The equivalent fiat amount user would pay based on exchange rate</td><td></td></tr><tr><td>crypto_amount_to_receive</td><td>This is the amount of cryptocurrency to be received</td><td></td></tr><tr><td>exchange_rate</td><td>This is the exchange rate</td><td></td></tr><tr><td>pair</td><td></td><td></td></tr><tr><td>fiat_currency</td><td>This is the amount of fiat currency to be bought</td><td></td></tr><tr><td>buyer_crypto_address</td><td>The buyer's crypto address </td><td></td></tr><tr><td>chain</td><td>e.g. usdt-trc20, usdc-matic</td><td></td></tr><tr><td>fiat_payment_status</td><td>This is the fiat payment status. </td><td>Pending (payment has not been fully processed yet) or Paid (payment is fully processed and successful)</td></tr><tr><td>crypto_payment_status</td><td>This is the crypto payment status. </td><td>Started (payment is in process), Completed (payment is fully processed and completed)</td></tr><tr><td></td><td></td><td></td></tr><tr><td>account_name</td><td>This is the name of the account holder</td><td></td></tr><tr><td>account_number</td><td>This is the bank account number or phone number if MOMO</td><td></td></tr><tr><td>bank_name</td><td>The name of the bank</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>email</td><td>Email of the buyer</td><td></td></tr><tr><td>phone</td><td>Phone number of the buyer</td><td></td></tr><tr><td>first_name</td><td>First name of the buyer</td><td></td></tr><tr><td>last_name</td><td>Last name of the buyer</td><td></td></tr><tr><td></td><td></td><td></td></tr><tr><td>payment_link</td><td>This is the payment link given to the buyer </td><td>available for MOMO payments</td></tr><tr><td>crypto_txn_hash</td><td>This is the crypto transaction has given to the buyer</td><td>the hash of your crypto payment </td></tr><tr><td>partner_callback_url</td><td>The partner Id returned from the onboarding endpoint</td><td></td></tr><tr><td>signature</td><td>This is the buyer's signature</td><td> sha512 signed with public key + secret key    </td></tr><tr><td></td><td></td><td></td></tr></tbody></table>


---

# 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://axis-docs.fuspay.finance/buy-fiat-on-ramp/create-buy-order-endpoint.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.