Transaction Endpoints

info

These endpoints relate creating new wallet transactions

Request Payment

Request funds from another user

Url: api/Transaction/RequestPayment

Body:

{
    fromAccountId : <users_account_id>,
    toAccountId : <your_account_id>
    reference : '<unique reference>'
    amount : <requested amount>
}

Response 200 (Success):

{
    key : <a unique id>,
    approveById : '<id of the person to approve the transaction>'
    ttl : <time left in seconds>
    expiryDate : <date/time when the transaction expires>
}

info

Body

fromAccountId - This is the id of the payees wallet - the user who is paying out the funds
toAccountId - This is the id of recipients wallet - the user who will receive the funds
reference - A unique reference create so that you can identify and link this transaction to your system
amount - The amount of the transaction
currencyCode - leave blank or do not include - the from and to wallets should have matching currencies and this currency will resolve from these wallets. It is not necessary to specify the currency.

Response

key - A unique id for this transaction
approvedById - The id of the person that can approve this transactions (The payee)
ttl - number of seconds left to approve this transaction.
expiryDate - the actual time this transaction will expire if not approved

danger

Other possible error responses

400 (Bad Request) The transaction could not be completed. The reason is returned Check error, contact merchant or fix problem and try again
401 (Unauthorized) Invalid or expired token
403 (Forbidden) You do not have the rights to create or approve this transaction.
500 (Internal Error) A critical unexpected system error has occurred. Contact Xprizo and report error

Send Payment

Send funds to another user

Url: api/Transaction/SendPayment?action=<action>&pin=<pin>

Body:

{
    fromAccountId : <your_account_id>,
    toAccountId : <users_account_id>
    reference : '<unique reference>'
    amount : <requested amount>
}

Response 200 (Success): (Action=Approve)

{
    key : <a unique id>,
    approveById : '<id of the person to approve the transaction>'
    ttl : <time left in seconds>
    expiryDate : <date/time when the transaction expires>
}

Response 200 (Success): (Action=Commit)

{
    id : <transactionId>
    description : <Error Description>
}

info

action - (0)=Approve, (1)=Commit, (2)=Callback
pin - Required if user implemented "Approval Security"

Body

fromAccountId - This is the id of the payees wallet - the user who is paying out the funds
toAccountId - This is the id of recipients wallet - the user who will receive the funds
reference - A unique reference create so that you can identify and link this transaction to your system
amount - The amount of the transaction
currencyCode - leave blank or do not include - the from and to wallets should have matching currencies and this currency will resolve from these wallets. It is not necessary to specify the currency.

Response 200 (Success) (action=Approve)

key - A unique id for this transaction
approvedById - The id of the person that can approve this transactions (The payee)
ttl - number of seconds left to approve this transaction.
expiryDate - the actual time this transaction will expire if not approved

Response 200 (Success) (action=Commit)

id - The Id of the transaction
description - The type of transaction processed (Payment)

danger

Other possible error responses

400 (Bad Request) The transaction could not be completed. The reason is returned Check error, contact merchant or fix problem and try again
401 (Unauthorized) Invalid or expired token
403 (Forbidden) You do not have the rights to create or approve this transaction.
500 (Internal Error) A critical unexpected system error has occurred. Contact Xprizo and report error

Card Deposit

Deposit Funds using a Credit Card

Url: api/Transaction/CardDeposit

Body:

{
    "accountId": <merchants wallet id>,
    "customer": <unique name for the depositor>,
    "reference": <unique reference>,
    "amount": <the deposit amount>,
    "description": <optional> 
    "creditCard": {
        "name": <name on card>
        "number": <card number>,
        "expiryMonth": <2 diget expiry month 01-12>,
        "expiryYear": <2 diget expiry year>,
        "ccv": <3 or 4 digets>
    },
    "callbackUrl": <optional callback when complete>
    "mid" : <optional is ofrequested amount>
}

Response 200 (Success):

{
    key : <a unique identifier for the transaction>
    status : <Active/Rejected/Pending/Redirect>
    value : <billingcode/reason/url>
}

info

Body

accountId - (Required) This is the id of the recipients (merchants) wallet - the wallet into which the the funds will be deposited.
customer - (Required) A unique name for of the person making the deposit. This user is stored in the merchants addressbook (you can use users name, email or phone numner of any other unique name)
reference - (Required) A unique reference used to identify this transaction.
amount - (Required) The deposit amount
description - (Optional) Text that can be used to describe the reason for the deposit. This information will appear on the transaction displayed in the wallet. in Test Mode. use:-
- 'Pass' to trigger a successful payment
- 'Reject' to rejected a payment
callbackUrl - (Optional) You can send a callback to an altername address
mid - (Optional) Use to force the deposit to use a specific Merchant ID

Response 200

key - One of the following depending on the status
- Active - the transaction id
- Rejected - the log file transacion id
- Pending - the key of the pending transaction
- Redirect - the key of the pending transaction
status - the status of the transaction - It can be one of the following:
- "Active" - The transaction is a valid active transaction
- "Rejected" - The transaction failed
- "Pending" - The transaction is awaiting approval.
- "Redirect" - The transaction failed
value - further detail about the transaction, depending on the status
- Active - The billing description
- Rejected - the reason the transaction was rejected
- Pending - The billing description if available else blank
- Redirect - the url to redirect to

danger

Other possible error responses

400 (Bad Request) The transaction could not be completed. The reason is returned. Check error, contact merchant or fix problem and try again
401 (Unauthorized) Invalid or expired token
403 (Forbidden) You do not have the rights to create or approve this transaction.
500 (Internal Error) A critical unexpected system error has occurred. Contact Xprizo and report error

MPesa Deposit

Deposit Funds using M-Pesa

Url: api/Transaction/MPesaDeposit

Body:

{
    accountId : <your_account_id>,
    mobileNumber : <mpesa_mobile_number>
    reference : '<unique reference>'
    description : '<extra information about the deposit>'
    amount : <requested amount>
}
    

Response 200 (Success):

{
    id : <id of the profile of the account>
    description : <the unique reference number>
}

info

Body

accountId - This is the id of the recipients wallet - the user who will receive the funds. Currently only Kenyan Shillings is supported so this must be a KES wallet.
reference - A unique reference used to identify this transaction. If you do not supply one, then a unique guid reference will be created for you
description - (Optional) text that can be used to describe the reason for the deposit. This information will appear on the transaction displayed in the wallet
amount - The Deposit amount in Kenyan Shillings (KES)

Response 200

id - The Id of the transaction
description - The type of transaction processed (Payment)

danger

Other possible error responses

400 (Bad Request) The transaction could not be completed. The reason is returned Check error, contact merchant or fix problem and try again
401 (Unauthorized) Invalid or expired token
403 (Forbidden) You do not have the rights to create or approve this transaction.
500 (Internal Error) A critical unexpected system error has occurred. Contact Xprizo and report error

Check Transaction Status (using unique reference)

Use this endpoint to check the status of a transaction using the unique reference of the transaction

GET Url: api/Transaction/StatusByReference/{accountId}/reference={reference}

Response 200 (Success):

{
    id : <transactionId>,
    description : '<status>'
}

info

accountId - This is the id of the wallet that contains the transaction. When requesting a payment use the id of the recipients wallet.
reference - The unique reference that was created on the transaction

Response

id - This is the unique id of the transaction.
description - the status of the transaction - It can be one of the following:
- Active - The transaction is a valid active transaction
- Pending - The transaction is awaiting approval (or rejection). If a pending transaction is rejected, it is deleted.
- Void - The transaction was created, put on hold and then later voided.
- Hold - The transaction is on hold and awaiting approval. If this transaction is rejected, it will be marked as 'void'.
- NotFound - A transaction on this wallet, with this reference does not exists. Either an invalid accountId and reference was entered, or the transaction was pending and has since expired or been rejected

Transaction Status

Use this endpoint to check the status of a transaction using the unique reference of the transaction

GET Url: api/Transaction/Status/{accountId}/reference={reference}

Response 200 (Success):

{
    key : <a unique identifier for the transaction>
    status : <Active/Rejected/Pending/NotFound>
    value : <billingcode/reason>
}

info

accountId - This is the id of the wallet that contains the transaction. When requesting a payment use the id of the recipients wallet.
reference - The unique reference that was created on the transaction

Response

key - One of the following depending on the status
- Active - the transaction id
- Rejected - the log file transacion id
- Pending - the key of the pending transaction
- NotFound - blank
status - the status of the transaction - It can be one of the following:
- "Active" - The transaction is a valid active transaction
- "Rejected" - The transaction failed
- "Pending" - The transaction is awaiting approval.
- "NotFound" - Transaction with this reference on this account does not exist
value - further detail about the transaction, depending on the status
- Active - The billing description
- Rejected - the reason the transaction was rejected
- Pending - The billing description if available else blank
- NotFound - "Not Found"

Approve Transaction

Approve a pending transaction

Url: api/Transaction/ApprovalAccept?key=<key>&pin=<pin>&once=<true/false>

Response 200 (Success):

{
    id : <transactionId>,
    description : '<status>'
}   

info

key - A unique id of the transaction you wish to approve
key - you pin code, if you have set "Approval Security" you wish to approve
once - Set this to true, if you want to automatically cancel this transaction if an error occurs when processing the transaction.

Response

id - The Id of the transaction
description - The type of transaction processed (Payment)

Cancel Transaction

Cancel a pending transaction

Url: api/Transaction/ApprovalCancel?key=<key>

info

key - A unique id of the transaction you wish to approve

Response 200 (Success):

Transaction Endpoints

Request Payment​

Send Payment​

Card Deposit​

MPesa Deposit​

Check Transaction Status (using unique reference)​

Transaction Status​

Approve Transaction​

Cancel Transaction​

Request Payment

Send Payment

Card Deposit

MPesa Deposit

Check Transaction Status (using unique reference)

Transaction Status

Approve Transaction

Cancel Transaction