Xprizo Manuals - API Manual

The API manual provides comprehensive documentation on the various endpoints that constitute our application programming interface (API). It is meant for developers to quickly find the information they need to seamlessly integrate our API into their applications, services, or projects.

Introduction
Addressbook
Transaction Endpoints (api/Transaction)
Preference Endpoints (api/Preference)
Wallet Endpoints (api/Wallet)

Introduction

The purpose of this document is to provide a comprehensive guide to offer detailed insights into our API environments, and Authentication methods to be used at the time of integration.

Base URL for Live https://wallet.xprizo.com/api

2. Authentication

Xprizo employs JWT tokens and API keys as authentication methods for accessing API functions. You have the flexibility to choose either authentication method when interacting with the endpoints. You need to pass a JWT token or API key in the header of each request.

2.1. JSON Web Tokens (JWT)

2.1.1. Creating a Token

Creating a token is done by calling the GetToken endpoint with your username and password. If you are not a registered user you can register by going to the Sandbox or Live server.

Request:

curl --location '{baseurl}/Security/GetToken' \
--header 'accept: text/plain; x-api-version=1.0' \
--header 'x-api-version: 1.0' \
--header 'Content-Type: application/json; x-api-version=1.0' \
--data-raw '{
  "userName": "use username, mobile number to email",
  "password": "your password"
}'

Response:

{
  "id": <a unique Id>,
  "token": <use this token for furture calls>,
  "expires": <the time the token expires>
}

2.1.2. Usages of Token

Use this token in the header of all secure requests to other endpoint

curl -X 'GET' \
  '{baseurl}/Wallet/Info?contact=1' \
  -H 'accept: text/plain' \
  -H 'Authorization: bearer <token>

2.2. API Keys

2.2.1. Creating an API Key

To configure your API key, access your User Account, navigate to 'settings' by clicking the profile icon, and locate 'security' in the list. Within the security settings, you will find an option to set the API key. It's important to note that if the API key is removed, a new key must be issued and utilized for transactions.

Screenshot 2024-01-22 213458.png

2.2.2. Usages of API Key

Use the API key in the header in the following way.

curl --location --request GET '{baseurl}/Wallet/Info?contact={username/emailid/mobilenumber}&currencyCode={currencyCode}' \
--header 'Accept: text/plain; x-api-version=1.0' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}'

2.3. Know your account ID

To submit deposits for processing, you will need your accountId (wallet ID) from your account. You can find this by the following process, login to your account and open settings, find ‘wallet’ on the list and you will find an ID associated with the wallet of required currency. If a wallet doesn’t exist, you will be required to create one by clicking the button.

Addressbook

Get AddressBook Item Information

Introduction

The GET /api/Addressbook/Info endpoint allows you to retrieve information about a specific item in the address book. You can search using a username, email, or mobile number.

Create Request

curl -X 'GET' \
  'https://wallet.xprizo.com/api/Addressbook/Info?value=John%20Doe' \
  -H 'accept: text/plain' \
  -H 'x-api-version: 1'

Endpoint: Get Information about an AddressBook Item

URL: /api/Addressbook/Info
Method: GET
Description: Retrieve information about an AddressBook item by providing a username, email, or mobile number.

Parameter	Description
Query	(string, required): Enter the username, email, or mobile number of the contact you are searching for.
Header	(string, required): Specify the API version.

Responses

Response (200 Success)

The request was successful, and the information about the AddressBook item is returned.

{
  "id": 0,
  "description": "string"
}

Errors

400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Get Active User Count in Address Book

Introduction

The GET /api/Addressbook/Count endpoint allows you to retrieve the number of active users in the address book.

Create Request

curl -X 'GET' \
  'https://wallet.xprizo.com/api/Addressbook/Count?contactId=2131' \
  -H 'accept: text/plain' \
  -H 'x-api-version: 1'

Endpoint: Get Contact Count

URL: /api/Addressbook/Count
Method: GET
Description: Retrieve the count of AddressBook contacts based on a specific contact ID.

Parameter	Description
Query	contactId (integer, required): The ID of the contact for which you want to get the count.
Header	x-api-version (string, required): Specify the API version.

Responses

Response (200 Success)

The request was successful, and the information about the AddressBook item is returned.

Errors

400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Set User KYC Compliant

Introduction

The SetUserKYCCompliant API endpoint allows you to update the KYC (Know Your Customer) compliance status of a user in the address book. This endpoint requires proper authentication and versioning headers.

Create Request

curl -X 'PUT' \
  'https://wallet.xprizo.com/api/Addressbook/SetUserKYCCompliant/123?value=true' \
  -H 'accept: */*' \
  -H 'x-api-version: 1'

Endpoint: Set User KYC Compliant

URL: /api/Addressbook/SetUserKYCCompliant/{contactId}
Method: PUT
Description: Update the KYC compliance status of a specific user in the address book.

Parameter	Description
Path	contactId (integer, required): The ID of the contact whose KYC compliance status is being updated.
Query	contactId (integer, required): The ID of the contact for which you want to get the count.
Header	x-api-version (string, required): Specify the API version.

Responses

Response (200 Success)

The request was successful, and the information about the AddressBook item is returned.

Errors

400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Rename Contact in Address Book

Introduction

The PUT /api/Addressbook/RenameUser endpoint allows you to rename a contact in the address book.

Create Request

curl -X 'PUT' \
  'https://wallet.xprizo.com/api/Addressbook/RenameUser' \
  -H 'accept: */*' \
  -H 'x-api-version: 1' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": 0,
  "description": "string"
}'

Endpoint: Rename Contact

URL: /api/Addressbook/RenameUser
Method: PUT
Description: Rename a contact in the address book.

Parameter	Description
Header	x-api-version (string, required): Specify the API version.

Responses

Response (200 Success)

The request was successful, and the information about the AddressBook item is returned.

Errors

400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Disable Contact in Address Book

Introduction

The DELETE /api/Addressbook/Disable/{contactId} endpoint allows you to disable a contact in the address book.

Create Request

curl -X 'DELETE' \
  'https://wallet.xprizo.com/api/Addressbook/Disable/123' \
  -H 'accept: */*' \
  -H 'x-api-version: 1'

Endpoint: Disable Contact

URL: /api/Addressbook/Disable/{contactId}
Method: DELETE
Description: Disable a contact in the address book.

Parameter	Description
Path	contactId (integer, required): The ID of the contact whose KYC compliance status is being updated.
Header	x-api-version (string, required): Specify the API version.

Responses

Response (200 Success)

The request was successful, and the information about the AddressBook item is returned.

Errors

400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Enable Contact in Address Book

Introduction

The DELETE /api/Addressbook/Enable/{contactId} endpoint allows you to enable a previously disabled contact in the address book.

Create Request

curl -X 'DELETE' \
  'https://wallet.xprizo.com/api/Addressbook/Enable/123' \
  -H 'accept: */*' \
  -H 'x-api-version: 1'

Endpoint: Enable Contact

URL: /api/Addressbook/Enable/{contactId}
Method: DELETE
Description: Enable a previously disabled contact in the address book.

Parameter	Description
Path	contactId (integer, required): The ID of the contact whose KYC compliance status is being updated.
Header	x-api-version (string, required): Specify the API version.

Responses

Response (200 Success)

The request was successful, and the information about the AddressBook item is returned.

Errors

400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Add Contact to Address Book

Introduction

The POST /api/Addressbook/Add endpoint allows you to add a new contact to the address book. The contact information can be a phone number, email, or a name.

Create Request

curl -X 'POST' \
  'https://wallet.xprizo.com/api/Addressbook/Add' \
  -H 'accept: */*' \
  -H 'x-api-version: 1' \
  -H 'Content-Type: application/json' \
  -d '{
  "value": "string"
}'

Endpoint: Add Contact

URL: /api/Addressbook/Add
Method: POST
Description: Add a new contact to the address book.

Parameter	Description
Header	x-api-version (string, required): Specify the API version.

Responses

Response (200 Success)

The request was successful, and the information about the AddressBook item is returned.

Errors

400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Validate a User Using Rules

Introduction

The POST /api/Addressbook/ValidateUser endpoint allows you to validate a user based on specific rules. The validation can be performed using a contact name, which can be a phone number, an email address, or a name.

Create Request

curl -X 'POST' \
  'https://wallet.xprizo.com/api/Addressbook/ValidateUser?ruleName=test' \
  -H 'accept: text/plain' \
  -H 'x-api-version: 1' \
  -H 'Content-Type: application/json' \
  -d '{
  "value": "string"
}'

Endpoint: Validate User

URL: /api/Addressbook/ValidateUser
Method: POST
Description: Validate a user using specified rules.

Endpoint: Set User KYC Compliant

URL: /api/Addressbook/SetUserKYCCompliant/{contactId}
Method: PUT
Description: Update the KYC compliance status of a specific user in the address book.

Parameter	Description
Request	value (string, required): The contact information to be validated. This can be a phone number, email, or name.
Query	contactId (integer, required): The ID of the contact for which you want to get the count.
Header	x-api-version (string, required): Specify the API version.

Responses

Response (200 Success)

The request was successful, and the information about the AddressBook item is returned.

{
  "id": 0,
  "description": "string"
}

Errors

400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Delete an Address Book Contact

Introduction

The DELETE /api/Addressbook/Delete/{contactId} endpoint allows you to delete a specific contact from the address book.

Create Request

curl -X 'DELETE' \
  'https://wallet.xprizo.com/api/Addressbook/Delete/123' \
  -H 'accept: */*' \
  -H 'x-api-version: 1'

Endpoint: Delete Address Book Contact

URL: /api/Addressbook/Delete/{contactId}
Method: DELETE
Description: Delete a specific contact from the address book.

Parameter	Description
Path	contactId (integer, required): The unique ID of the contact to be deleted.
Header	x-api-version (string, required): Specify the API version.

Responses

200 Success The request was successful, and the information about the AddressBook item is returned.
400 Bad Request The request could not be understood or was missing required parameters.
401 Unauthorized Authentication failed or the user does not have permission for the requested operation.
500 Server Error An error occurred on the server.

Transaction Endpoints (api/Transaction)

Tip: Use the page navigation section on the left to navigate quickly from one endpoint to another.

General Definitions

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

To obtain the API key for authentication, click here to generate the API key.

Deposit With 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": "<Description/narrative for the deposit/payment>",
 "reference": "<Unique reference>",
 "amount": <Deposit/payment amount, 2 decimal places, dot as decimal>,
 "accountId": <ID of the wallet into which the amount will be deposited - NOT profile ID>,
 "transferAccountId": <ID of the wallet to which the amount will be transferred after depositing, typically used for currency conversion - SEE NOTES BELOW>,
 "customerData": {
 "name": "<Full name of the user/customer>",
 "email": "<Email address of the user/customer>",
 "mobile": "<Mobile phone number of the user/customer>",
 "birthDate": "<Date of birth of the user/customer. String with format 'YYYY-MM-DD'>",
 "gender": "<Gender of the user/customer. 'M', 'F', or 'X'>",
 "address": {
 "address": "<Building number/name, unit/apt number/letter, etc>",
 "street": "<Name of street, roadway, thoroughfare, etc>",
 "city": "<Name of town, city, etc>",
 "zipPostalCode": "<Alphanumeric depending on country>",
 "stateProvinceRegion": "<Administrative sub-division, such as state, province, or territory>",
 "countryCode": "<Two-letter string using uppercase characters, e.g., 'KE', 'AE'>"
 },
 "IpAddress": "<Customer's IP address in string format, IPv4 or IPv6>"
 },
 "creditCard": {
 "name": "<Name on card>",
 "number": "<Card number>",
 "expiryMonth": <2 digit expiry month, 01-12>,
 "expiryYear": <4 digit expiry year>,
 "cvv": "<3 or 4 digits>"
 },
 "routingCode": "string",
 "redirect": "string"
}'

Please note that if a parameter is indicated as REQUIRED, providing that parameter is MANDATORY. The transaction will be rejected if any mandatory parameter is missing.

DO NOT use the same card details, or the same customerData information, for multiple users/customers - it will be detected and your transactions rejected.

If you manage to process transactions with any of the mandatory fields missing, we provide no guarantee that you will be able to continue doing so, and will provide no advance notice when enforcing of such mandatory fields is implemented and deployed.

Parameter	Description
accountId	(REQUIRED) This is the ID of the wallet into which the amount will be deposited. Do NOT use profile ID here. The Wallet ID can be seen in the 'Wallets' screen of your Xprizo console/dashboard, column 'Account'.
transferAccountId	(Optional) This is the ID of the wallet to which the amount will be transferred after depositing. **Note: This is required when you want to deposit money in a wallet of currency that is not supported by the acquirer. In this case we will do an internal transfer and at the time of the transfer currency conversion charges may apply.
reference	(REQUIRED) A unique, alphanumeric string used to identify and track this specific transaction within your own system. If you're a merchant, you can use your own order ID here, as long as it is unique.
customer	(Deprecated) Please provide "customerData" object with user/customer details.
name	(REQUIRED) The full name of the user/customer. MUST match name on card.
email	(REQUIRED) Email address of the user/customer. DO NOT use one email address for multiple users/customers.
mobile	(REQUIRED) Mobile phone number of the user/customer. Must be provided in E.164 format, which consists of a leading + symbol followed by the country code and the full subscriber number (including area code) without any spaces, dashes, or leading zeros (e.g., "+25412345678"). DO NOT use one mobile phone number for multiple users/customers.
birthDate	(REQUIRED) The date of birth of the user/customer. String with format "YYYY-MM-DD".
gender	(REQUIRED) The gender of the user/customer. Must be 'M', 'F', or 'X'.
address	(REQUIRED) Building number/name, unit/apt number/letter, etc, of the user/customer's postal address.
street	(REQUIRED) Name of street, roadway, thoroughfare, etc, of the user/customer's postal address.
city	(REQUIRED) Name of town, city, etc, of the user/customer's postal address.
zipPostalCode	(REQUIRED) Zip/post code of the user/customer's postal address. Alphanumeric depending on country.
stateProvinceRegion	(Optional) Administrative sub-division, such as state, province, or territory, of the user/customer's postal address.
countryCode	(REQUIRED) Country of the user/customer's postal address. The country code must be provided as a two-letter string following the ISO 3166-1 alpha-2 standard, using uppercase characters (e.g., "KE", "AE").
ipAddress	(REQUIRED) Customer's IP address in string format, IPv4 or IPv6.
amount	(REQUIRED) The deposit amount, with 2 decimal places, using dot as the decimal.
description	(REQUIRED) Description/narrative for the deposit/payment.
routingCode	Use one of the routing codes that have been set on your account (routing codes are used for different currencies and limits). These will be configured by the Xprizo Team and you can find them here.
redirect	(REQUIRED) The card is processed using 3DS, so 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 successfully Pending – The transaction was unable to be completed and needs further action Rejected - The transaction was rejected Redirect – (3DS) the user needs to be redirected to another URL to complete the transaction
value	Active – the value will show the description Pending - the value will show the description Rejected - the value will show the reason Redirect - 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.

Message	Detail of Message
Invalid routing code	Your 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 exists	You need to generate a new reference and try again
A 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.

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

Deposit With 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.

Deposit With MPESA

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. You can check your account id here
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 successfully Pending – The transaction was unable to be completed and needs further action Rejected - The transaction was rejected
value	Active – the value will show the description Pending - the value will show the description Rejected - 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.

Withdrawal With MPESA

Request

curl --location '{baseurl}/Transaction/MPesaWidthdrawal' \
--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 transactions. Who will receive the funds. Sample +254706****73
accountId	This is the ID of your wallet - You can check your account ID here
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 successfully Pending – The transaction was unable to be completed and needs further action Rejected - The transaction was rejected
value	Active – the value will show the description Pending - the value will show the description Rejected - 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.

Deposit With UPI

Request

curl --location '{baseurl}/Transaction/UpiDeposit?useApprovalProcess=false' \
--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-raw '{
  "description": <description of the transaction>,
  "reference": <unique ID or reference supplied from your end>,
  "amount": <amount to be deposited>,
  "currencyCode": <currency of the transaction, must be INR>,
  "type": <transaction type, must be 1>,
  "accountId": <account ID for the account into which funds will be deposited>,
  "customer": <alternative end user name>,
  "customerData": {
    "name": <the name of the end user>,
    "email": <end user's email address>,
    "address": {
      "address": <deprecated, use address fields below>,
      "street": <address street>,
      "city": <address city>,
      "stateProvinceRegion": <address state, province, or region>,
      "zipPostalCode": <address postcode>,
      "countryCode": <country code, must be IN>
    }
  },  
  "redirect": <URL to which your end user will be directed after approving the transaction>
}'

Parameter	Description
description	(Optional) Description of the transaction.
reference	(Required) A unique ID or reference supplied from your end, which you can use to identify and link this transaction to your system.
amount	(Required) The amount of the transaction.
currencyCode	(Required) Currency code for the transaction currency, must be "INR".
type	(Required) Transaction type, must be 1.
accountId	(Required) Account ID for the account into which funds will be deposited. See here how to check for your account ID.
customer	(Optional, see notes below) The name of the end user (alternative).
customerData.name	(Optional, see notes below) The name of the end user.
customerData.email	(Optional) End user's email address.
customerData.address.address	Deprecated, use address fields below.
customerData.address.street	(Optional) Address street.
customerData.address.city	(Optional) Address city.
customerData.address.stateProvinceRegion	(Optional) Address state, province, or region.
customerData.address.zipPostalCode	(Optional) Address postcode.
customerData.address.countryCode	(Required) Country code, must be "IN".
redirect	(Required) URL to which your end user will be directed after approving the transaction.

Important Notes

If customerData.name is present, it will be used as the end user's name.
If customer is present, and customerData.name is not present, customer will be used as the end user's name.
If customerData.name and customer are both not present, details from your Xprizo profile will be used:
- If your profile is of 'Individual' type, first and last name from your profile will be used.
- If your profile is of 'Legal Entity' type, trading name from your profile will be used if present, otherwise registered name from your profile will be used.
The following query parameters will be added to the specified redirect URL when the user is redirected on completion of the transaction:
- key: System unique ID for the transaction.
- status: Transaction status.
- reference: The unique ID or reference supplied from your end.

Response (200)

{
    
    "key": <System unique ID for the transaction>,
    "statusCode": <Numeric code for transaction status>,
    "status": <Transaction status>,
    "description": <Currently empty/unused>,
    "value": <URL to which you need to redirect your end user to approve the transaction>,
    "reference": <Unique ID or reference supplied from your end>
    
}

Parameter	Description
key	System unique ID for the transaction.
statusCode	A numeric code for the status of the transaction.
status	The status of the transaction.
value	The URL to which you need to redirect your end user to approve the transaction.
description	Currently empty/unused.
reference	Unique ID or reference supplied from your end, which you can use to identify and link this transaction to your system.

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.

Send Payment (Xprizo Wallet)

Request

curl --location '{baseurl}/Transaction/SendPayment?action=<action>&pin=<pin>' \
--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":<your_account_id>,
    "toAccountId": <users_account_id>,
    "reference": <unique reference>,
    "amount":  <requested amount>,
    "description": <purpose of payment>
}'

Parameter	Description
action	0 or default (Transaction will go in approval mode and payee needs to approve the transaction) 1 (Transaction will be completed with any approval) 2 (Transaction will be on hold until Xprizo will receive HTTP code 200 on payment webhook)
pin	Required if the user implemented "Approval Security"
fromAccountId	This is the ID of the payee's wallet - the user who is paying out the funds
toAccountId	This is the ID of the 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) If action = 0 or Not provided in request

{
    "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>

Response (200) If action = 1 or 2

{
    "id":<a unique identifier for the transaction>,
    "description": "<The type of transaction processed (Payment)>"
}

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.

Approve Payment (Xprizo Wallet)

Request

curl --location '{baseurl}/Transaction/ApprovalAccept?key=<key>&pin=<pin>&once=<true/false>' \
--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}'

Parameter	Description
key	A unique ID of the transaction you wish to approve
pin	Required if the user implemented "Approval Security"
once	Set this to true, if you want to automatically cancel this transaction if an error occurs when processing the transaction.

Response (200)

{
    "id":<a unique identifier for the transaction>,
    "description": "<The type of transaction processed (Payment)>"
}

Cancel Payment (Xprizo Wallet)

Request

curl --location '{baseurl}/Transaction/ApprovalCancel?key=<key>' \
--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}'

Parameter	Description
key	A unique ID of the transaction you wish to approve

Response (200) Transaction is canceled successfully

Check Transaction Status

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 transaction Pending - 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 description When Void this will contain the void reason When Rejected or Cancelled, it will contain the reason. When pending or NotFound, it will be blank

Preference Endpoints (api/Preference)

General Definitions

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

Update Approval Webhook

Approval Webhook is triggered when a new pending transaction is created or when this pending transaction is approved, canceled, or rejected.

Request

curl --location --request PUT '{baseurl}/Preference/SetApprovalWebhook?url={url}' \
--header 'Accept: text/plain; x-api-version=1.0' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}'

Parameter	Description
url	Url to receive callbacks

Response (200)

Your callback URL must respond with JSON object {'status': 'success' } and HTTP code 200 to Xprizo.

Test Approval Webhook

You can test your callback URL's response by using this endpoint

Request

curl --location --request GET '{baseurl}/Preference/TestApprovalWebhook' \
--header 'Accept: text/plain; x-api-version=1.0' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}'

Response (200)

Your callback URL must respond with JSON object {'status': 'success' } and HTTP code 200 to Xprizo.

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 = Accepted- The transaction was approved and processed
3 = Rejected - The transaction was rejected by the acquirer
4 = Cancelled - The transaction was canceled by the creator

Update Payment Webhook

Payment Webhook is triggered when a payment transaction with an action set to 2 (callback) is created.
Callbacks are only sent to the profile that created the transaction.
Callbacks will keep sending requests to the platform for 24 hours or until it gets a response.
If a 200 (success) response is received then the transaction will be processed.
If any other response (except a timeout) is received then the transaction will be voided.

Request

curl --location --request PUT '{baseurl}/Preference/SetPaymentWebhook?url={url}' \
--header 'Accept: text/plain; x-api-version=1.0' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}'

Parameter	Description
url	Url to receive callbacks

Response (200)

Payment Webhook Responses

This will triggered when the send payment is initiated in Callback mode, Based on the response of this webhook by the Recipient, Xprizo will approve or void the transaction.

{
  "id": 3291,
  "currencyCode": "INR",
  "amount": 10,
  "reference": "652-1706532591321",
  "status": "Success"
}

Parameter	Description
status	Status of transaction
id	The unique ID of the transaction provided by Xprizo
reference	Recipient's unique transaction identifier for this transaction
currencyCode	The currency of this transaction
amount	The amount of this transaction

Recipient will use this response and check for transactions having the same reference in their system and if everything is fine then they will respond with HTTP status code 200 else they will provide another HTTP status code (excluding timeout).

If the Status code is 200 then this transaction will be marked as Completed in the Xprizo system else it will be VOID (excluding timeout).

Wallet Endpoints (api/Wallet)

General Definitions

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

Get Wallet Information

Request

curl --location --request GET '{baseurl}/Wallet/Info?contact={username/emailid/mobilenumber}&currencyCode={currencyCode}' \
--header 'Accept: text/plain; x-api-version=1.0' \
--header 'x-api-version: {apiversion}' \
--header 'x-api-key: {apikey}'

Parameter	Description
contact	enter the user's mobile number, username, or email for searching
currencyCode	the currency code of the wallet to search for - leave blank to fetch the user's default wallet.

Response (200)

{
    "id": <accountId>,
    "contactId": <contactId>,
    "contact": <owners Name>,
    "currencyCode": <currency code>,
    "symbol": <currency symbol>,
    "name": <wallet name>,
    "profilePicture": <owners picture>,
    "isDefault": <is the owners default wallet>,
    "isMerchant": <is the owners have merchant wallet>
}

Xprizo Manuals - API Manual

Introduction

1. Environment​

1.1. Testing (Sandbox)​

1.2 Production (Live)​

2. Authentication

2.1. JSON Web Tokens (JWT)​

2.1.1. Creating a Token​

2.1.2. Usages of Token

2.2. API Keys​

2.2.1. Creating an API Key

2.2.2. Usages of API Key

2.3. Know your account ID

Addressbook

Get AddressBook Item Information

Get Active User Count in Address Book

Set User KYC Compliant

Rename Contact in Address Book

Disable Contact in Address Book

Enable Contact in Address Book

Add Contact to Address Book

Validate a User Using Rules

Delete an Address Book Contact

Transaction Endpoints (api/Transaction)

General Definitions

Deposit With Card

Deposit With Xprizo Wallet

Deposit With MPESA

Withdrawal With MPESA

Deposit With UPI

Send Payment (Xprizo Wallet)

Approve Payment (Xprizo Wallet)

Cancel Payment (Xprizo Wallet)

Check Transaction Status

Preference Endpoints (api/Preference)

General Definitions

Update Approval Webhook

Test Approval Webhook

Approval Webhook Responses

Update Payment Webhook

Payment Webhook Responses

Wallet Endpoints (api/Wallet)

General Definitions

Get Wallet Information

1. Environment

1.1. Testing (Sandbox)

1.2 Production (Live)

2.1. JSON Web Tokens (JWT)

2.1.1. Creating a Token

2.2. API Keys