VPAY-Documentation

V-Pay Developer Documentation

Getting Started with V-Pay

V-Pay enables you to easily accept online payments. The API is open to merchants licensed to operate in Rwanda. This documentation outlines different API end points and required parameters to make API calls. Visit https://vonsung.rw for more details.

  • Send a request to pay: This API enables you to send a request to pay to a mobile money subscriber. Our servers communicate directly to MTN Mobile Money and other PSP to process your payment request.
  • Check transaction status: Once the payment is completed, we retern a JSON response containing the transaction STATUS. However, if you want to check the status of your transaction, you may do so by a single API call

How to get merchant account

Step 1: Send an application documents to info@vonsung.co.rw and we will create a merchant account for you. Application documents include a commitment letter, business incorporation certificate, contact details of the company and representative, and ID copy of company representative.

Step 2: Once the merchant account is created, login to your merchant portal and generate apiKey and apiUser

Step 3: Explore our API documentation and start testing

Step 4: If you are done, switch to LIVE mode, and update test credentials with LIVE credentials

ℹ️ Resources

V-Pay homepage

VONSUNG.IO

Note:

If you are using Postman to test the integration, remember to include the following in your request headers:

Variable Value
Content-Type application/json
Content-Length  
Host  
 
Collection
 

POST: sendRequestToPay

Endpoint: https://pay.vonsung.rw/api/mtn_vPay

You should always pass apiUser and apiKey as header parameters whenever you attempt to make an API call. The body barameters are passed as JSON.

To get your apiUser and apiKey, login to your merchant dashboard and go to API section, then copy your API user and API key.

Definition of body parameters:

  • payer_phone: also known as MSISDN is phone number where the request to pay will be sent.
  • external_id: this is the transaction ID generated from your end (your integration platform). It is mainly used for the purpose of tracking the transaction status.
  • payer_name: the name of payer being charged for a transaction.
  • amount: integer value equavalent to the amount being charged (transaction amount).
  • payer_email: the email of payer being charged for a transaction.
  • payee_message: the payee note. Example: Purchase from Smarthire
  • send_receipt: boolean value (true if you want the payer to receive V-Pay receipt, false elsewhere)
HEADERS
apiUser: ********
apiKey: ********
Bodyraw (json):
{
    "payer_phone": "0788604106",
    "external_id": "A403344545932357785",
    "payer_name": "Celestin",
    "amount": 1000,
    "payer_email": "celestin@vonsung.co.rw",
    "payee_message": "Test",
    "send_receipt": true
}
Example Request:
 
curl --location 'https://pay.vonsung.rw/api/mtn_vPay' \
--header 'apiUser: ********' \
--header 'apiKey: ********' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payer_phone": "0788604106",
    "external_id": "A403344545935785",
    "payer_name": "Celestin",
    "amount": 50,
    "payer_email": "celestin@vonsung.co.rw",
    "payee_message": "Test"
}'
200 OK
 
Example Response (json):
{
  "payer_name": "Celestin",
  "payer_phone": "250788604106",
  "merchant": "VONSUNG LLC",
  "external_id": "A403344545935785",
  "transaction_id": "VT22",
  "amount": 50,
  "currency": "rwf",
  "status": "SUCCESSFUL"
}

GETgetStatusByTransactionId

https://pay.vonsung.rw/api/status

This request enables you to check the status of a transaction placed with V-Pay using the transaction ID (assigned by V-Pay).

HEADERS
apiUser: ********
apiKey: ********
Content-Type: application/json
Bodyraw (json):
{
    "transaction_id": "VP59219136"
}
 
Example Request:
curl --location --request GET 'https://pay.vonsung.rw/api/status' \
--header 'apiUser: ********' \
--header 'apiKey: ********' \
--header 'Content-Type: application/json' \
--data '{
    "transaction_id": "VT20"
}'
200 OK
 
Example Response (json):
{
  "transaction_id": "VT20",
  "external_id": "A403344535785",
  "payer_name": "Celestin",
  "payer_phone": "250788604106",
  "transaction_date": "2023-06-01 03:04:11 pm",
  "payment_method": "mtnrw",
  "mode": "test",
  "currency": "RWF",
  "amount": 50,
  "status": "SUCCESSFUL"
}

GETgetStatusByExternalTransactionId

https://pay.vonsung.rw/api/status

Alternatively, you can check the transaction status using the external transaction ID which you passed as external_id when sending a request to pay.

HEADERS
apiUser: ********
apiKey: ********
Content-Type application/json
Bodyraw (json):
{
    "external_id": "VF3611095424"
}
 
Example Request:
curl --location --request GET 'https://pay.vonsung.rw/api/status' \
--header 'apiUser: ********' \
--header 'apiKey: ********' \
--header 'Content-Type: application/json' \
--data '{
    "external_id": "A403344535785"
}'
200 OK
 
Example Response (json):
{
  "transaction_id": "VT20",
  "external_id": "A403344535785",
  "payer_name": "Celestin",
  "payer_phone": "250788604106",
  "transaction_date": "2023-06-01 03:04:11 pm",
  "payment_method": "mtnrw",
  "mode": "test",
  "currency": "RWF",
  "amount": 50,
  "status": "SUCCESSFUL"
}