> For the complete documentation index, see [llms.txt](https://axis-docs.fuspay.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axis-docs.fuspay.finance/buy-fiat-on-ramp/create-buy-order-endpoint.md).

# 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>