Integrating with the Xprizo API

This chapter provides detailed steps for setting up your merchant profile, creating a processing profile with access to the merchant wallet, and navigating through testing (sandbox) and production (live) environments. Additionally, it walks you through the deposit process using Xprizo Wallet, card, MPESA, and UPI, covering the flow, validation, callbacks, deposit transaction creation, approval webhook set up, and status checking. Follow the sections below to manage your account and transactions efficiently.

Account Setup

You need to create two profiles where the first profile will be of the Merchant having a wallet to be able to receive funds and the other profile will be of Processing which will be used for creating the transactions on the merchant's account wallet.

Merchant profile

To create a merchant profile use the link below where you can find how to do registration, profile updation, KYC, and procedure for merchant requests.

How to Become a Merchant 

Processor profile

A processor profile is required to manage the transactions of the merchant wallet. This processor profile will help the merchant, to secure his wallet by giving only the required access to the processor on the merchant profile. To configure the processor profile use the below-mentioned link where you can find all the steps to configure the processor profile (linking of merchant profile and processor profile, and after that how to give access to the processor profile of the merchant profile).

** You can also use a merchant profile as a processor profile, but this is advisable to have a separate processor profile to manage the transactions to make your main merchant profile secure.

Processor Profile Configuration 

Test profile

To test the merchant account you will have to create a sample/test account which you will use to check if the integration is done properly or not.

Environment & Authentication​

Before starting the integration, the user needs to know about the available environment and authentication methods required for integration. Use the below-mentioned link where you can find details about the available environment, and authentication methods (how to generate token & API key and usage of these).

Environment & Authentication


Deposit Using Xprizo Wallet

To make a deposit, funds are transferred from a user's wallet to the merchant's wallet. This process is done by requesting a payment from the user through the Transaction/RequestPayment endpoint.

Flow

This is an example of the flow that should be used when integrating with Xprizo to perform deposits.

  • (on merchant) Create a new transaction.
    • Create a reference to be used for this transaction.
    • Set the transaction as pending.
  • (on Xprizo) Create the Xprizo transaction.
    • Find the user's wallet using their phone number or email or username, and the specified currency through the Wallet/Info endpoint.

    • Find the merchant's wallet with the same currency using the Wallet/Info endpoint.

    • Create transaction using Transaction/RequestPayment 
    • Wait for the callback.
    • Check the status of the transaction Transaction/Status endpoint.

  • (on merchant) Update or cancel the transaction
    • If the transaction is approved, update the transaction status in your system.

    • If the transaction is rejected, cancel the transaction on your system.

User Journey Mapping (21).jpg


Steps​

  • Create a payment Request
  • Wait for callback
  • Check Status

Once you've created a payment request, wait for a callback that will be sent once the user approves the request. While it's not mandatory to utilize callbacks, it's more efficient to do so. Alternatively, you can directly call the check status endpoint, but this isn't recommended as you would need to continuously poll the server to check the status. Use this endpoint to check the status Transaction/Status.

To receive callbacks, you must set this up on your account (the profile that is used to create this transaction). You can set up the callback by accessing the settings/preferences in Xprizo. Configure the "Approval Webhook" to your desired API endpoint where you want to receive the callback. Alternatively, you can set this up using the Preference/SetApprovalWebhook endpoint.

** You should, however, check the status, after you get a callback to confirm that the transaction was completed successfully. You can use Transaction/Status endpoint to check the status.


Deposit Using Card

Flow​

User Journey Mapping (20).jpg

Steps​

After you have called the Transaction/CardDeposit endpoint, a payment request is sent to the Acquirer network to process the card payment. A pending transaction is also created and Xprizo will continue monitoring the Acquirer network until an approval or rejection is received.

If the card is 'Approved' (2DS) then the transaction will be added to the merchant's wallet and the API will return an 'Active' status. No further action is required.

If there is a problem creating the transaction then the API will return a status of 'Rejected'.

It is possible that a card is not processed immediately such as some kind of delay or the user might need to approve the transaction using another device, then a 'Pending' status will be returned.

In the case of 3DS, there could be a redirect to an alternate URL. In this case, a 'Redirect' status and URL is returned.

The Merchant will get updates on the status of the transaction via callbacks. To receive a callback, you will need to request to set this up on your Merchant account (the profile that is used to create this transaction). This can be done by going to settings/preferences and setting the "Approval Webhook" to point to a URL of your choice. You can also set this using Preference/SetApprovalWebhook

A callback will be sent when

You can use this link to see the response coming on this Webhook.

** You should, however, check the status, after you get a callback to confirm that the transaction was completed successfully. You can use Transaction/Status endpoint to check the status.


Deposit Using MPESA

To make deposits from a user via M-Pesa, initiate a deposit by transferring funds from the user's M-Pesa account to your merchant's wallet using the Transaction/MPesaDeposit endpoint.

Flow​

User Journey Mapping (20).jpg

Steps​

  • Add an M-Pesa deposit Transaction
  • Wait for callback
  • Check Status

Once you've called the "MpesaDeposit" endpoint, a payment request is sent to the M-Pesa network and the user will then confirm the transaction on their phone. A pending transaction is also generated, and Xprizo will continuously monitor the M-Pesa network until a confirmation or failure is received.

  • If a confirmation is received, the pending transaction will transition into a completed transaction.
  • If the transaction is cancelled, a notification containing details about the cancellation will be generated and sent to the merchant's account.

Merchants will receive updates on the transaction status via callbacks. To enable callbacks, you'll need to configure this on your account (the profile used to create the transaction). You can accomplish this by navigating to the settings/preferences in Xprizo and configuring the "Approval Webhook" to point to a URL of your choice. Alternatively, you can achieve the same using the Preference/SetApprovalWebhook endpoint.

A callback will be sent when

  • the pending transaction is created.
  • the pending transaction is approved
  • the pending transaction is cancelled

It is not strictly necessary to use callbacks, you have the option to periodically check the status of the transaction. However, it's not recommended as it would require to poll the server continuously to check the status. However, it's advisable to verify the status after receiving a callback to ensure that the transaction was completed successfully.

Use this endpoint to check the status Transaction/Status.

** You should, however, check the status, after you get a callback to confirm that the transaction was completed successfully. You can use Transaction/Status endpoint to check the status.


Deposit Using UPI

This method applies ONLY to INR currency.

  • Initiate a UPI deposit transaction using the /Transaction/UpiDeposit endpoint.
  • Redirect your end user to the URL specified in the response you receive.
  • The end user will need to authorize the transaction.
  • When the process is completed, the end user will be redirected to the URL you specified when you called the /Transaction/UpiDeposit endpoint.
  • Wait for callback.
  • Check transaction status.

Once you have called the /Transaction/UpiDeposit endpoint, a pending transaction is generated in the Xprizo system and sends a request to our acquirer network to provide a URL for the UPI payment. You will need to redirect the end-user to this URL, and the user will need to authorize the transaction.

  • If authorization is received, the transaction will be marked as completed.
  • If the transaction is canceled, it will be marked as rejected.

You can query the status of the transaction at any point by calling the /Transaction/CheckStatus endpoint.

You can also receive transaction status updates via callbacks. To enable callbacks, you will need to configure this on the profile used to create the transaction. To do this:

  • Log in at wallet.xprizo.com.
  • Click on your profile icon at the top right, then 'Settings'.
  • Click on 'Preference' on the left menu.
  • Set 'Approval Webhook' to a URL of your choice where you will receive the callbacks.

Alternatively, you can use the /Preference/SetApprovalWebhook endpoint to achieve the same thing.

A callback will be sent when:

  • The pending transaction is created.
  • The pending transaction is approved.
  • The pending transaction is cancelled.

It is not strictly necessary to use callbacks. You can instead check the status of the transaction periodically. However, this is not recommended, as it would require you to poll the server continuously to check the status.

When using callbacks, it is still advisable to make a final status check to ensure that the transaction was completed successfully. You can use the /Transaction/Status endpoint to check the status of the transaction.


Withdrawals

Withdrawal to Xprizo Wallet

Withdrawals are carried out when a merchant wants to transfer funds from their wallet to a user's wallet. These transactions are initiated through the process of generating withdrawal requests. Typically, withdrawals can be done using three different methods. Each method provides merchants with flexibility in how they transfer funds, catering to their specific preferences and requirements. This flexibility ensures seamless fund transfers between merchants and users within the platform.

Create, Commit, Check

Employ this method if the final check is done on the platform's end, that is the platform verifies that the transaction was completed and will then update the user's wallet accordingly.

This method requires the platform to continually poll Xprizo in case there is no response to confirm whether the transaction was successfully created or not.

Flow

User Journey Mapping (26).jpg

Steps

Create, Approve, Check

Use this method if the creation and approval of transactions are not done at the same time. For instance, the platform might initiate the transaction, and the merchant may approve the transaction

With this method, the platform needs to continuously poll Xprizo in case there's no immediate response from Xprizo to confirm whether the transaction was successfully created or not.

Flow

User Journey Mapping (25).jpg

Steps

At any time you can cancel the transaction by calling Transaction/Cancel

Create, Hold, Check

Use this method if you prefer Xprizo to conduct the final check. Xprizo will verify that the transaction has been created on the platform by sending a callback and awaiting a valid response. Depending on the platform's response, Xprizo will either confirm the transaction or cancel it.

By using this method involves Xprizo initiating a transaction and placing it on hold. It will then send a callback to verify whether the platform has successfully updated the transaction on its end. If Xprizo receives a positive response, then the transaction will be completed. If a negative response is received or there is no response within 24 hours, the transaction is voided.

Flow

User Journey Mapping (27).jpg

Steps

Withdrawal to Bank Account

When a user needs to transfer funds from their wallet to someone's bank account, they can easily initiate this process by providing the recipient's name, account number, and the desired amount to be transferred. This withdrawal method facilitates direct transfers to bank accounts, ensuring seamless transactions between users and their chosen recipients.

Flow

User Journey Mapping (29).jpg

Steps