Transaction Endpoints (api/Transaction)

General Definitions

Parameter	Description
baseurl	Sandbox – https://test.xprizo.com/apiLive- https://wallet.xprizo.com/api
apiversion	1.0
apikey	API key For authentication

Create Deposit Request Using Card

Request

curl --location '{baseurl}/Transaction/CardDeposit' \
--header 'Accept: text/plain; x-api-version=1.0' \
--header 'Content-Type: application/json; x-api-version=1.0' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}' \
--data '{
 "description": <purpose of deposit>,
 "reference": <unique reference>,
 "amount": <the deposit amount>,
 "accountId": <merchants wallet id>,
 "customer": <unique name for the depositor>,
 "creditCard": {
 "name": <name on card>,
 "number": <card number>,
 "expiryMonth":<2 diget expiry month 01-12>,
 "expiryYear": <2 diget expiry year>,
 "cvv": <3 or 4 digets>
 },
 "routingCode": "string",
 "redirect": "string"
}'

Parameter	Description
accountId	(Required) This is the ID of the recipient’s wallet – the wallet into which the funds will be deposited.
reference	(Required) The reference is the unique transaction identifier for this transaction. This will be generated by processor user and will be used in status checks and callbacks.
customer	(Required) A unique identifier of the person making the deposit. If this customer is not found in the system, they will be added to recipient’s the address book. You can pass email id of that user.
amount	(Required) The deposit amount, with 2 decimal places, using dot as the decimal.
description	(Optional) Text that can be used to describe the reason for the deposit. In Test Mode. use:- Pass, Success – the transaction will be created as approved.Reject, Fail, Cancel – the transaction will be created and then rejected.
routingCode	Use one of the routing codes that have been set on your account (routing codes are used for different currencies and limits). This will be configured by the Xprizo Team and you can find these here.
redirect	(Required for 3DS) If the card is processed using 3ds then you will need to open a confirmation screen (the redirect URL for the confirmation screen is returned in the response to this request). This redirect is the URL that the user will be returned to after the confirmation screen has been closed.

Response (200)

{
    "key": <a unique identifier for the transaction>,
    "statusCode": <The number equivalent of the Status>,
    "status": <Active/Rejected/Pending/Redirect>,
    "value": <billingcode/reason/url>
}

Parameter	Description
key	a unique identifier for the transaction
statusCode	The number equivalent of the Status
status	Active – The transaction was completed successfullyPending – The transaction was unable to be completed and needs further actionRejected – The transaction was rejectedRedirect – (3DS) the user needs to be redirected to another URL to complete the transaction
value	Active – the value will show the descriptionPending – the value will show the descriptionRejected – the value will show the reasonRedirect – the value will show the URL to redirect to

Errors

400 (Bad Request) The transaction could not be completed. The reason is returned Check the error, contact Xprizo, or fix the problem and try again.
- MessageDetail of MessageInvalid routing codeYour account does not have the routing code configured. Please contact the Xprizo team to have this set up. Invalid routing code (No Mid Set)Your account does not have the MID configured. Please reach out to the Xprizo team to have this configured.A transaction with this reference already existsYou need to generate a new reference and try againA pending transaction with this reference already exists (Ref:652-1706532591287))The transaction is already available for this reference number with status pending, please check the status of this or try again with a new reference number
401 (Unauthorized) Invalid or expired token.
403 (Forbidden) You do not have the right to create or approve this transaction.
500 (Internal Server Error) A critical unexpected system error has occurred. Contact Xprizo and report the error.

Create Deposit Request Using Xprizo Wallet

Request

curl --location '{baseurl}/Transaction/RequestPayment' \
--header 'Accept: text/plain; x-api-version=1.0' \
--header 'Content-Type: application/json; x-api-version=1.0' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}' \
--data '{
    "fromAccountId": <users_account_id>,
    "toAccountId": <your_account_id>,
    "description": <purpose of deposit>,
    "amount": <requested amount>,
    "reference":<unique reference>
}'

Parameter	Description
fromAccountId	This is the ID of the payee’s wallet – the user who is paying out the funds
toAccountId	This is the ID of recipient’s wallet – the user who will receive the funds
description	(Optional) Text that can be used to describe the reason for the transaction
amount	The amount of the transaction
reference	A unique reference is created so that you can identify and link this transaction to your system

Response (200)

{
    "key":<a unique identifier for the transaction>,
    "approveById": <id of the person to approve the transaction>,
    "canCancel": <can be cancelled or not>,
    "ttl": <time left in seconds>,
    "expiryDate": <date/time when the transaction expires>,
    "error": ""
}

Parameter	Description
key	a unique identifier for the transaction
approveById	<id of the person to approve the transaction>
canCancel	<can be cancelled or not>
expiryDate	<date/time when the transaction expires>
ttl	<time left in seconds>

Errors

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

Create Deposit Request Using Mpesa Wallet

Request

curl --location '{baseurl}/Transaction/MPesaDeposit' \
--header 'Accept: text/plain; x-api-version=1.0' \
--header 'Content-Type: application/json; x-api-version=1.0' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}' \
--data '{
    "mobileNumber": <mpesa_mobile_number>,
    "accountId": <your_account_id>,
    "description": <purpose of deposit>,
    "amount": <requested amount>,
    "reference":<unique reference>
}'

Parameter	Description
mobileNumber	Mpesa Mobile number to be used for transaction
accountId	This is the ID of recipient’s wallet – the user who will receive the funds
description	(Optional) Text that can be used to describe the reason for the transaction. In Test Mode. use:- Pass, Success – the transaction will be created as approved.Reject, Fail, Cancel – the transaction will be created and then rejected.
amount	The amount of the transaction
reference	A unique reference is created so that you can identify and link this transaction to your system

Response (200)

{
    "key": <a unique identifier for the transaction>,
    "statusCode": <The number equivalent of the Status>,
    "status": <Active/Rejected/Pending>,
    "value": <transaction description>
}

Parameter	Description
key	a unique identifier for the transaction
statusCode	The number equivalent of the Status
status	Active – The transaction was completed successfullyPending – The transaction was unable to be completed and needs further actionRejected – The transaction was rejected
value	Active – the value will show the descriptionPending – the value will show the descriptionRejected – the value will show the reason

Errors

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

Approval Webhook Responses

Created Transaction & Approved Transaction Response on Webhook (Sample)

# Created Transaction
{
  "statusType": 1,
  "status": "New",
  "description": null,
  "actionedById": 724,
  "affectedContactIds": [
    723,
    2
  ],
  "transaction": {
    "id": 0,
    "createdById": 724,
    "type": "UCD",
    "date": "2024-02-07T03:41:59.823195+00:00",
    "reference": "652-1706532591283",
    "currencyCode": "USD",
    "amount": 5
  }
}

# Approved Transaction
{
  "statusType": 2,
  "status": "Accepted",
  "description": null,
  "affectedContactIds": [
    723,
    2
  ],
  "transaction": {
    "id": 3169,
    "createdById": 724,
    "type": "UCD",
    "date": "2024-02-07T03:43:50.9186754+00:00",
    "reference": "652-1706532591283",
    "currencyCode": "USD",
    "amount": 5
  }
}

Parameter	Description
statusType	This is the status 2 = Accepted
status	Text version of the status “Accepted”
affectedContactIds	A list of the contact IDs that were involved in this transaction
Transaction	Transaction that was created
id	The unique Id of the transaction provided by Xprizo
createdById	Id of the person who creates the transaction
type	The type of transaction (UCD = Card Deposit)
date	The date of the transaction
reference	Recipient’s unique transaction identifier for this transaction
currencyCode	The currency of this transaction
amount	The amount of this transaction

Rejected Transaction Response on Webhook (Sample)

{
 "statusType":3,
 "status":"Rejected",
 "description":"Reason for rejection",
 "actionedById":1,
 "affectedContactIds":[]
 "transaction": {
   "id":0,
   "createdById":2,
   "type":"UCD",
   "date":"2021-04-20T20:34:00.7606173+02:00",
   "reference":234234234,
   "currencyCode":"USD",
   "amount":100.00
 }
}

The following is a list of approval status codes that could be returned

0 = None – Used for testing
1 = New – A new pending transaction has been created
2 = Approved- The transaction was approved and processed
3 = Rejected – The transaction was rejected by the acquirer
4 = Cancelled – The transaction was cancelled by the creator

Transaction Status Check

This endpoint can be used to check the status of any type of transaction for example card deposit, Mpesa withdrawal etc.

Request

curl --location '{baseurl}/Transaction/Status/{accountId}/?reference={reference}' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}'

Parameter	Description
accountId	This is the ID of the wallet that contains the transaction. When requesting a payment use the ID of the recipient’s wallet.
reference	The reference is the Merchants unique transaction identifier for this transaction

Response (200)

{
    "key" : <a unique identifier for the transaction>
    "statusCode" : <0/3/1/-1/4/5/6>
    "status" : <Active/Rejected/Pending/NotFound/Cancelled/Hold/Void >
    "value" : <billingdescription/transaction description/Void reason>
}

# Pending Transaction 

{
    "key": "",
    "statusCode": 1,
    "status": "Pending",
    "value": "Pass"
}


# Approved Transaction

{
    "key": "3169",
    "statusCode": 0,
    "status": "Active",
    "value": "testing.com Pass"
}

# Rejected Transaction

{
    "key": "144",
    "statusCode": 3,
    "status": "Rejected",
    "value": "Failed Test"
}

# Not Found Transaction

{
    "key": "",
    "statusCode": -1,
    "status": "NotFound",
    "value": ""
}

# Hold Transaction (Mpesa Withdrawal)

{
    "key": "144",
    "statusCode": 5,
    "status": "Hold",
    "value": "Mpesa Withdrawal +254342222222"
}

# Void Transaction (Mpesa Withdrawal)

{
    "key": "144",
    "statusCode": 6,
    "status": "Void",
    "value": "342222222 Voided: No Response Data"
}

Parameter	Description
key	This is the unique ID of the transaction.When Active or Hold or Void this will contain the transaction ID When Rejected or Cancelled, it will be the ID given in the log file for the entry.When pending or NotFound, it will be blank.
status	The status of the transaction – It can be one of the following:Active – The transaction is a valid active transactionPending – The transaction is awaiting approval (or rejection).NotFound – A transaction on this wallet, with this reference does not exist. Rejected – the transaction has been rejected by the acquirer.Cancelled – If Xprizo cancels the transaction due to technical error or invalid calls.Hold – This is applicable for Mpesa withdrawal
value	When Active this will contain the billing description For card deposit & transaction description for other transactions.When Hold this will contain the withdrawal descriptionWhen Void this will contain the void reasonWhen Rejected or Cancelled, it will contain the reason.When pending or NotFound, it will be blank

Test Configuration For Routing Options

Routing Option	Routing Code Prefix	Configuration
Option A	MAN	Amount$1.00 or $2.00 – Active( 2DS Success)$3.00 or $4.00 – Rejected$5.00 or $6.00 – Rdirect (3DS Redirect URL)$7.00 or greater – Rejected Case In 3DS

Kenya

UAE

Need a guide?

Transaction Endpoints (api/Transaction)

General Definitions

Create Deposit Request Using Card

Request

Response (200)

Errors

Create Deposit Request Using Xprizo Wallet

Request

Response (200)

Errors

Create Deposit Request Using Mpesa Wallet

Request

Response (200)

Errors

Approval Webhook Responses

Created Transaction & Approved Transaction Response on Webhook (Sample)

Rejected Transaction Response on Webhook (Sample)

The following is a list of approval status codes that could be returned

Transaction Status Check

Request

Response (200)

Test Configuration For Routing Options

Explore other manuals

Wallet Endpoints (api/Wallet)

Preference Endpoints (api/Preference)

Introduction

Navigation

Company

Help

Downloads

Legal