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": "", "reference": "", "amount": , "accountId": , "transferAccountId": , "customerData": { "name": "", "email": "", "mobile": "", "birthDate": "", "gender": "", "address": { "address": "", "street": "", "city": "", "zipPostalCode": "", "stateProvinceRegion": "", "countryCode": "" }, "IpAddress": "" }, "creditCard": { "name": "", "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": , "statusCode": , "status": , "value": } 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": , "toAccountId": , "description": , "amount": , "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":, "approveById": , "canCancel": , "ttl": , "statusCode": , "status": , "value": } 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": , "accountId": , "description": , "amount": , "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": , "statusCode": , "status": , "value": } 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": , "reference": , "amount": , "currencyCode": , "type": , "accountId": , "customer": , "customerData": { "name": , "email": , "address": { "address": , "street":
, "city":
, "stateProvinceRegion":
, "zipPostalCode":
, "countryCode": } }, "redirect": }' 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": , "statusCode": , "status": , "description": , "value": , "reference": } 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=&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":, "toAccountId": , "reference": , "amount": , "description": }' 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":, "approveById": , "canCancel": , "ttl": , "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. Approve Payment (Xprizo Wallet) Request curl --location '{baseurl}/Transaction/ApprovalAccept?key=&pin=&once=' \ --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":, "description": "" } Cancel Payment (Xprizo Wallet) Request curl --location '{baseurl}/Transaction/ApprovalCancel?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" : "statusCode" : <0/3/1/-1/4/5/6> "status" : "value" : } # 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