# Assigning Virtual Accounts

There are 2 ways you can create an order on our system using Virtual Accounts. The first way we are responsible for assigning the Virtual account (`https://prod-order-exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/CreateOrder/` and the other way you fetch an available account from our end an show to your users. We would explore the first way using the endpoint below. The other way is right below

## This endpoint is used to create an order on Intrapay  *(Old Auto Assigned VA for NGN)* 

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

`The endpoint above has been changed to https://prod-order-exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/CreateOrder/ for efficiency sake`&#x20;

So,  if you want a redirect URL (a screen that allows your users input their phone number & network), Please include *<mark style="color:green;">**x-partner-id, x-merchant-secret**</mark>* in the **header** and ignore *<mark style="color:red;">**intrapay\_merchant\_id**</mark>* in the request body.

However,  if you have a system for collecting the phone number and network (mobile money regions) or you want to collect in NIGERIA; you should not add *<mark style="color:red;">**x-partner-id**</mark>* and *<mark style="color:red;">**x-merchant-secret**</mark>* in the header, and send *<mark style="color:green;">**"intrapay\_merchant\_id"**</mark>* and *<mark style="color:green;">**partner\_id**</mark>* in the **request body** instead

The intrapay merchant id is different for each account (currency) created on Intrapay. You can find your intrapay merchant id at the bottom left AFTER YOU HAVE SETUP the wallet of that currency.&#x20;

The merchant secret is also different per currency. Find your merchant secret at the partner mapping screen by clicking on your name on the partner list.

<mark style="color:red;">Please make sure we have whitelisted all your IPs</mark>

#### Headers

| Name                                            | Type   | Description                                                             |
| ----------------------------------------------- | ------ | ----------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | ***Bearer*** pk\_partner\_xxx                                           |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json                                                        |
| x-partner-id                                    | String | Your partner ID                                                         |
| x-merchant-secret                               | String | the merchant secret copied from intrapay dashboard(differs per country) |

#### Request Body

| Name                                                     | Type   | Description                                                                                                                                                                                            |
| -------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| partner\_order\_id<mark style="color:red;">\*</mark>     | String | Id of order generated on partners's system                                                                                                                                                             |
| amount\_to\_collect<mark style="color:red;">\*</mark>    | String | amount seller or buy as listed                                                                                                                                                                         |
| intrapay\_merchant\_id<mark style="color:red;">\*</mark> | Number | merchant id on Intrapay (this is different per account)                                                                                                                                                |
| timestamp<mark style="color:red;">\*</mark>              | Number | Time order was signed. unix or epoch time in milleseconds (GMT+0)                                                                                                                                      |
| order\_expiration<mark style="color:red;">\*</mark>      | String | the time to be elapsed before order becomes invalid.  unix or epoch time in milleseconds (GMT+0)                                                                                                       |
| currency<mark style="color:red;">\*</mark>               | String | currency the buyer is paying the merchant with                                                                                                                                                         |
| partner\_callback\_url<mark style="color:red;">\*</mark> | String | partner payment notification url used by IntraPay to notify Partner System about the Payment status of the order                                                                                       |
| partner\_redirect\_url<mark style="color:red;">\*</mark> | String | provided by partner url to redirect buyer                                                                                                                                                              |
| signature<mark style="color:red;">\*</mark>              | String | SHA-512 of request payload signed with both merchant and partner secret key(SK\_merchant\_xxx+SK\_partner\_xxx)                                                                                        |
| phone                                                    | String | <p>The phone number of the sender. Not needed in non mobile money regions. This should not be included if you are going to use our page to collect the number.<br><br>Add country code 254XX671000</p> |
| mobile\_money\_network                                   | String | The mobile network operator. eg MTN, Safaricom(MPESA), ATM. Not needed in non mobile money regions. This should not be included if you are going to use our page to collect the number                 |
| partner\_id                                              | String | The partner Id returned from the onboarding endpoint                                                                                                                                                   |

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

```javascript
//API Response 
{
message:"OK",
redirect_url:""
}

//Response sent to callback URL
{
  "status": "success",
  "messsage": "",
  "virtual_account": {
  "account_name": "",
    "bank_name": "",
    "account_number": ""
  },
  "order_details": {
  "status": "PENDING",
  "partner_order_id": "",
  "intrapay_order_reference": ""
 }

}
```

{% endtab %}

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

```javascript
{
  "status": "fail",
  "messsage": "",
  "error_code": ""
}


1001 - Order is already open / pending
1002 - Order has been canceled
1003- Order has been completed
1004- Order has expired
```

{% endtab %}
{% endtabs %}

#### Example Request- Code

{% tabs %}
{% tab title="Node" %}

```javascript
const request = require('request')
const options = {
  method: 'POST',
  url: 'http://localhost:5000/api/v1/no-auth/PartnerP2P/CreateOrder',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer pk_partner_xxxxxxxx'
  },
  body: {
    partner_order_id: 'my-server-order-id',
    amount_to_collect: '5',
    timestamp: 1693285902419,
    order_expiration: 1693285902419,
    currency: 'NGN', // GHS | KHS | NGN | UGX | ZAR
    intrapay_merchant_id: "",
    partner_id: "",
    partner_callback_url: 'https://xxx...',
    partner_redirect_url: 'https://example.com?status=success&order=my-server-order-id',
    signature: 'fe04ee69d4f9a93c71f3d1bbf37d49d541e5c4fb159c4a75924f398262e2af146d0e2e33b1379a9b57c641d822c410158e03b64faab34dc98d528bfa234f9dd3'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

{% endtab %}

{% tab title="cURL" %}

```
curl "https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/CreateOrder" \
  -H 'Content-Type: application/json' \
  -H 'x-intrapay-partner-secret: H36ZOEA-HK7EWOQ-TVM2C6A-QH6BW2Q53954' \
  -H 'Authorization: Bearer pk_partner_xxxx' \
  -X POST \
  -b 'connect.sid'='s%3AoNBPv4ez8npeuKVKlS9KwX_1Dshiamlf.n8opjPuoF3XsU%2Be0VTLMUe6xzeAXmpCfQrpW9KW1KDs' \
  -d '{
  "partner_order_id": "",
  "amount_to_collect": "",
  "intrapay_merchant_id": "",
  "timestamp": "",
  "order_expiration": "",
  "currency": "",
  "partner_callback_url": "",
  "partner_redirect_url": "",
  "partner_buyer_registered_name": "",
  "signature": "sha-512-of-req-body-signed-with-SK_merchant_xxx+SK_partner_xxx"
}' 
```

{% endtab %}
{% endtabs %}

### Get Available Assignable Virtual Account&#x20;

### This endpoint is used to fetch free/available virtual accounts from your account pool.&#x20;

<mark style="color:green;">`POST`</mark> `https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/GetCollectionPoolAccounts?choose_bank=All/`

This gives you ability to assign virtual account number to a collection order.&#x20;

Virtual Account Number are used once until an order is fulfilled or timeout

This endpoint also gives you the ability to decide the bank generating the virtual account. if choose\_bank=All virtual accounts from all bank partners (GTB, Globus) would be returned; However if set to GTB,  only VAs from GTB would be returned.&#x20;

#### Query Parameters

| Name         | Type   | Description                                                                                                             |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| choose\_bank | String | to select the bank providing the virtual account eg choose\_bank =GTB. This would return virtual accounts from GTB only |

#### Headers

| Name                                            | Type   | Description                   |
| ----------------------------------------------- | ------ | ----------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | ***Bearer*** pk\_partner\_xxx |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json              |

#### Request Body

| Name                                                     | Type   | Description                                                                                                     |
| -------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| intrapay\_merchant\_id<mark style="color:red;">\*</mark> | Number | merchant id on Intrapay (this is different per account)                                                         |
| signature<mark style="color:red;">\*</mark>              | String | SHA-512 of request payload signed with both merchant and partner secret key(SK\_merchant\_xxx+SK\_partner\_xxx) |
| partner\_id                                              | String | the partners id from partner onbaording endpoint                                                                |

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

```javascript
Response {
	"success": true,
	"message": "Collection Pool Accounts",
	"data": [
		{
			"virtual_account_id": xxx,
			"account_name": "xxxxx",
			"account_number": "xxxxxx",
			"status": "ACTIVE"
		},
        ....
    ]
}


//Active means account is not being used and is available for use 
```

{% endtab %}

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

{% endtab %}
{% endtabs %}

#### Example Request- Code

### Check if specific account is available for use

## This endpoint is used to check if a specific account is available for use&#x20;

<mark style="color:blue;">`GET`</mark> `https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/IsPoolAccountAvailable?account_number=xxxx/`

#### Query Parameters

<table><thead><tr><th>Name</th><th width="163">Type</th><th>Description</th></tr></thead><tbody><tr><td>account_number<mark style="color:red;">*</mark></td><td>String</td><td>this is the account number  you are trying to verify </td></tr></tbody></table>

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | partners public key |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json    |

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

```javascript
{
            success: true,
            message: m,
            data: data 
            
 }

//true means account is available for use 
```

{% endtab %}

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

{% endtab %}
{% endtabs %}

#### Example Request- Code&#x20;

### Create Order- using Available Virtual Account from your Account Pool

## This endpoint is used to create an order on Intrapay&#x20;

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

This endpoint puts you in charge of assigning virtual accounts to your collection orders.  So to create orders this way,  we have provided an endpoint above where you can get the list of available Virtual accounts (Accounts not assigned to any transaction yet) and once you get the free VA you send it along with your new order.&#x20;

The intrapay merchant id is different for each account (currency) created on Intrapay. You can find your intrapay merchant id at the bottom left AFTER YOU HAVE SETUP the wallet of that currency.&#x20;

The merchant secret is also different per currency. Find your merchant secret at the partner mapping screen by clicking on your name on the partner list.

#### Headers

| Name                                            | Type   | Description                   |
| ----------------------------------------------- | ------ | ----------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | ***Bearer*** pk\_partner\_xxx |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json              |

#### Request Body

| Name                                                                 | Type   | Description                                                                                                      |
| -------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| partner\_order\_id<mark style="color:red;">\*</mark>                 | String | Id of order generated on partners's system                                                                       |
| amount\_to\_collect<mark style="color:red;">\*</mark>                | String | amount seller or buy as listed                                                                                   |
| intrapay\_merchant\_id<mark style="color:red;">\*</mark>             | Number | merchant id on Intrapay (this is different per account)                                                          |
| timestamp<mark style="color:red;">\*</mark>                          | Number | Time order was signed. unix or epoch time in milleseconds (GMT+0)                                                |
| order\_expiration<mark style="color:red;">\*</mark>                  | String | the time to be elapsed before order becomes invalid.  unix or epoch time in milleseconds (GMT+0)                 |
| currency<mark style="color:red;">\*</mark>                           | String | currency the buyer is paying the merchant with                                                                   |
| partner\_callback\_url<mark style="color:red;">\*</mark>             | String | partner payment notification url used by IntraPay to notify Partner System about the Payment status of the order |
| partner\_redirect\_url<mark style="color:red;">\*</mark>             | String | provided by partner url to redirect buyer                                                                        |
| signature<mark style="color:red;">\*</mark>                          | String | SHA-512 of request payload signed with both merchant and partner secret key(SK\_merchant\_xxx+SK\_partner\_xxx)  |
| assigned\_virtual\_account\_number<mark style="color:red;">\*</mark> | String | The virtual account picked from the get free account endpoint. eg 1234567890                                     |
| partner\_id<mark style="color:red;">\*</mark>                        | String | The partner Id returned from the onboarding endpoint                                                             |

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

```javascript
//API Response 
{
message:"OK",
redirect_url:""
}

//Response sent to callback URL
{
  "status": "success",
  "messsage": "",
  "virtual_account": {
  "account_name": "",
    "bank_name": "",
    "account_number": ""
  },
  "order_details": {
  "status": "PENDING",
  "partner_order_id": "",
  "intrapay_order_reference": ""
 }

}
```

{% endtab %}

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

```javascript
{
  "status": "fail",
  "messsage": "",
  "error_code": ""
}


1001 - Order is already open / pending
1002 - Order has been canceled
1003- Order has been completed
1004- Order has expired
```

{% endtab %}
{% endtabs %}

#### Example Request- Code

### Fetch order

## This endpoint is used to fetch an order to verify its status

<mark style="color:blue;">`GET`</mark> `https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/FetchOrder/`

**Order Status**&#x20;

PENDING - Order is open / pending

CANCELED - Order has been canceled

COMPLETED- Order has been completed and payment was made

EXPIRED- Order has expired

**Payment Status**

PENDING - Order payment is not received yet&#x20;

PAID - Order payment has been completed and payment was made by the Buyer

REFUND - Buyer was refunded

**The following transactions can be deemed as pending via API responses :**

Mismatched ( with Bank Ref )

Pending (No bank Ref)&#x20;

Abandoned - pending > 4hours

All pending are

#### Query Parameters

| Name                                                 | Type   | Description                                    |
| ---------------------------------------------------- | ------ | ---------------------------------------------- |
| partner\_order\_id<mark style="color:red;">\*</mark> | String | the Id or reference of the order being checked |

#### Headers

| Name                                            | Type   | Description         |
| ----------------------------------------------- | ------ | ------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | partners public key |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json    |

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

```javascript
{
  "status": "success",
  "messsage": "",
  "data": {
        "payment": {
            "status": "PENDING | PAID | REFUND"

            },
        "virtual_account": {
        "amount": "",
        "account_name": "",
        "bank_name": "",
        "account_number": ""
      },
     "order_details": {
     "status": "PENDING | COMPLETED | EXPIRED | CANCELED",
     "partner_order_id": "",
     "intrapay_order_reference": ""
     }

 }

}
```

{% endtab %}

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

```javascript
{
  "status": "fail",
  "messsage": ""
}
```

{% endtab %}
{% endtabs %}

#### Example Request- Code&#x20;

{% tabs %}
{% tab title="Node" %}

```javascript
const fetch = require('node-fetch');

fetch("https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/FetchOrder?partner_order_id=xxxxx", {
  "method": "GET",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer pk_partner_xxxx",
    "cookie": "connect.sid=s%253AoNBPv4ez8npeuKVKlS9KwX_1Dshiamlf.n8opjPuoF3XsU%252Be0VTLMUe6xzeAXmpCfQrpW9KW1KDs"
  }
})
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

{% endtab %}

{% tab title="cURL" %}

```
curl "https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/FetchOrder?partner_order_id=xxxxx" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer pk_partner_xxxx' \
  -X GET \
  -b 'connect.sid'='s%3AoNBPv4ez8npeuKVKlS9KwX_1Dshiamlf.n8opjPuoF3XsU%2Be0VTLMUe6xzeAXmpCfQrpW9KW1KDs' 
```

{% endtab %}
{% endtabs %}

### Cancel Order

## This endpoint is used to cancel an order.&#x20;

<mark style="color:green;">`POST`</mark>&#x20;

#### Headers

| Name                                            | Type   | Description             |
| ----------------------------------------------- | ------ | ----------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json        |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer pk\_partner\_xxx |

#### Request Body

| Name                                                 | Type   | Description                                                        |
| ---------------------------------------------------- | ------ | ------------------------------------------------------------------ |
| partner\_order\_id<mark style="color:red;">\*</mark> | String | Order id                                                           |
| signature<mark style="color:red;">\*</mark>          | String | sha-512-of-req-body-signed-with-SK\_merchant\_xxx+SK\_partner\_xxx |

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

```javascript
{
  "status": "success",
  "message": "",
  "partner_order_id": ""
}
```

{% endtab %}

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

```javascript
{
  "status": "fail",
  "messsage": ""
}
```

{% endtab %}
{% endtabs %}

### example request -code

{% tabs %}
{% tab title="Node" %}

```
const fetch = require('node-fetch');

fetch("https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/CancelOrder", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer pk_partner_xxxx",
    "cookie": "connect.sid=s%253AoNBPv4ez8npeuKVKlS9KwX_1Dshiamlf.n8opjPuoF3XsU%252Be0VTLMUe6xzeAXmpCfQrpW9KW1KDs"
  },
  "body": {
    "partner_order_id": "",
    "signature": "sha-512-of-req-body-signed-with-SK_merchant_xxx+SK_partner_xxx"
  }
})
  .then(response => console.log(response))
  .catch(err => console.error(err));
```

{% endtab %}

{% tab title="cURL" %}

```
curl "https://exchanger-api.fuspay.finance/api/v1/no-auth/PartnerP2P/CancelOrder" \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer pk_partner_xxxx' \
  -X POST \
  -b 'connect.sid'='s%3AoNBPv4ez8npeuKVKlS9KwX_1Dshiamlf.n8opjPuoF3XsU%2Be0VTLMUe6xzeAXmpCfQrpW9KW1KDs' \
  -d '{
  "partner_order_id": "",
  "signature": "sha-512-of-req-body-signed-with-SK_merchant_xxx+SK_partner_xxx"
}' 
```

{% endtab %}
{% endtabs %}


---

# 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.fuspay.finance/collection/assigning-virtual-accounts.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.