Transaction Endpoints (api/Transaction)

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

General Definitions

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.

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>
}

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

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>
}'

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": ""
}

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>
}'

Response (200)

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

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>
}'

Response (200)

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

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>
}'

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>
    
}

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>
}'

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": ""
}

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}' 

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}' 

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}'

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