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.

When deferPaymentMethod is set to true, a call to Initiate Order Created With Deferred Payment Method should be made to complete the order initiation.

See the example below

Initiates a buy order

POST https://checkout-api-sandbox.xendbridge.com/api/ThirdPartyUI/Buy/Initiate

Headers

Name	Type	Description
publicKey*		{publicKey}

Request Body

Name	Type	Description
emailAddress*		[e-mail]
phoneNumber*		07064366723
userName*		annadoe
payInCurrencyCode*		NGN
payInCurrencyNetwork*		LOCAL
receiveInCurrencyCode*		BUSD
receiveInCurrencyNetwork*		BEP20
orderAmount*		50
consumerDepositMethod*	Object
paymentMethod*		Bank
paymentData*	Object
accountName*		John Doe
accountNumber*		0000187849
bankName*		Access Bank
consumerReceiptMethod*	Object
paymentMethod*		Crypto
paymentData*	Object
walletAddress*		0x52434Ac4BE04393e020c9b16C327d04d4367Cbcd
network*		BEP-20
deferPaymentMethod*	bool	false

400: Bad Request Initiating another buy order while one is not finished is not allowed.

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

200: OK Success

{
    "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": "[e-mail]",
        "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": ""
}

JSON Request Format

{
  "emailAddress": "[e-mail]",
  "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"
    }
  }
}

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

JSON Request Format

{
  "emailAddress": "[e-mail]",
  "phoneNumber": null,
  "userName": "johndoe",
  "payInCurrencyCode": "NGN",
  "payInCurrencyNetwork": "LOCAL",
  "receiveInCurrencyCode": "BUSD",
  "receiveInCurrencyNetwork": "BEP20",
  "orderAmount": 1,
  "deferPaymentMethod": true
}

Request Fields

Parameters	Type	Definitions
emailAddress	string	Required This is the consumer's email address.
phoneNumber	string	Required This is the consumer's phone number.
userName	string	Required This is the consumer's username
payInCurrencyCode	enum	Required This is the currency code to pay with. Must be NGN for buy order.
receiveInCurrencyCode	enum	Required This is the currency code to receive the currency in. Must be BUSD for buy order.
orderAmount	decimal	Required The order amount by the consumer.
consumerDepositMethod	object	Required This holds the properties of the deposit method of the consumer which is are the bank details.
paymentMethod	enum	Required The payment method by which transactions are made. It should be BANKfor buy order.
paymentData	object	Required This holds the properties of the bank details of the consumer.
accountName	string	Required This is the account name of the consumer.
accountNumber	string	Required The local account number of the consumer
bankName	string	Required This is the bank name of the consumer.
consumerReceiptMethod	object	Required This holds the properties of the consumer receiving method. The paymentMethod prop must be Crypto .
paymentData	object	Required This holds the properties of the consumer receiving account details.
walletAddress	string	Required The crypto wallet address of the consumer.
network	string	Required This is the network on which the address is on.

Response Fields

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