Receiving a Payment

️

Before proceeding to this documentation, please read the introduction section to understand how our transaction operations work from an accounting point of view.

Requesting payment follows the same principles as sending payments. A POST request is sent to the https://api.bixi.co/3.0/pay endpoint, and set the memo being set to debit. The transaction will be debited from API consumer account and will be credited to the recipient account.

The payment request should send the following paramenters as a JSON formatted request body:

Property	Type	Required	Example	Description
`memo`	`ENUM` (`debit`)	Yes	`debit`	An `ENUM` value of `debit` for debiting from `accountNumber`.
`accountNumber`	`string`	Yes	`+252600000000`	This should be the fully qualifed Mobile Money Transfer Account, without the leading `00` or `+` code. Example `+252600000000`.
`accountType`	`ENUM`	Yes	`mmt`	Can be any of `mmt`, `bank`, `card`, `wallet`, `trc20`
`receiptId`	`string`	Yes	`INV1234`	This is the receipt ID, such as custom invoice ID. This should be between `1` and `11` in length. This is not unique.
`amount`	`number`	Yes	`1.01`	Example, `1.00`, `1`, or `0.01`. The amount must be in `USD`.
`description`	`string`	Yes	`Descriptive text`	Receipt description. Example, `Receipt for sales bill 123`.

Example CURL request:

curl \
  --request POST \
  --url https://api.bixi.co/3.0/pay \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer Your-API-Token' \
  --data '{
    "data": {
      "type": "transactions",
      "attributes": {
        "memo": "debit",
        "accountNumber": "+252600000000",
        "accountType": "mmt",
        "receiptId": "123456",
        "amount": 1.00,
        "description": "Receipt for sales bill No. 123456"
      }
    }'

The payment confirmation response will look like this. Notice the value of the memo property is debit. This is because the amount is debited from accountNumber.

{
  "data": {
    "id": "9d1ad1f3-4d9b-47f2-8ea1-d766face25ed",
    "type": "transactions",
    "attributes": {
      "receiptId": "123456",
      "referenceId": "528ebffa-4f1a-42ed-8d51-2bc344153eef",
      "accountNumber": "252600000000",
      "accountType": "mmt",
      "issuer": "hormuud",
      "status": "approved",
      "description": "Receipt for sales bill No. 123456",
      "memo": "debit",
      "currency": "USD",
      "issuerTransactionId": "536117",
      "charges": 0.03,
      "amount": 1,
      "amountInWords": "One",
      "total": 0.97,
      "totalInWords": "Zero Point Nine Seven",
      "timestamps": {
        "created": "2024-09-01T00: 00: 00.000000Z"
      }
    }
  }
}