Virtual Card Integration
If you are an approved merchant on Peerwallet and you have been approved to sell virtual cards on Peerwallet, this guide is for you.
If you are not a Merchant on Peerwallet, you should first learn more about Merchant services HERE and how to apply.
How It Works:Peerwallet makes it possible for different Merchants to integrate their Virtual card services. The process has to be automated as this would be tested by the Technical team in-charge of approving Virtual card offers on Peerwallet.
Illustration: When a user selects your Virtual card offer on Peerwallet to create and load a card, Peerwallet would send some values to an end point which you specified, then you take those values and then send to your Bank’s API to process, the next step is to reformat the response into how Peerwallet wants it and return the values. Look at the steps below for a quick summary.
Step 1 User visits Peerwallet, selects your Virtual card offer, then enters the required details with the initial amount to be loaded on the card.
Step 2 Peerwallet will send some values to the end point you specified when creating the virtual card offer on Peerwallet. Samples of the POST variables are; name, amount, card_name e.t.c
Step 3 At this point, you would collect the values sent from Peerwallet and then query your Bank’s API to create the card using the details sent to you by Peerwallet.
Step 4 When the card has been created and loaded, your Bank would return some values and card details for sure, follow the guide by Peerwallet on the type of response you should return so that Peerwallet would understand the response sent. Or return the appropriate error into the ‘note’ variable as sent by your Bank or as you want it seen by the user on Peerwallet.
Step 5 Card is processed and the user on Peerwallet should see all of these processes within 3 to 10 seconds depending on how fast your API service is.
After creating your Virtual card offer, then click the edit button you should see the Modify Api Details button to set your API details. The button looks like this.
From there you should then enter your API details. Below are the required end points to be entered.
- Card Creation End Point
- Fetch Card Details End Point
- Load Balance End Point
- Fetch Card Transactions End Point.
For each query, Peerwallet would send some variables to the end point you have specified and then wait for a response in a format we have also specified. So for each query we shall be explaining here the variables we shall send and the type of response to be gotten back
CARD CREATION
call_method == create
call method is the type of query for this call. On that URL specified, we shall send a variable called ‘call method’ and it shall contain the value called create. Meaning that this call is for a new card creation
POST variables sent by Peerwallet to your end point URL for this call are as follows;
[ call_method, email, amount, card_name, card_address, card_city, card_state, card_postal_code, card_country ]
email:This is the registered email address of the user on Peerwallet
amount: This is the amount the user want to load on the card, the amount here is in the selling currency you specified when creating the card offer.
card_name: If you allowed users to choose a card name, then this is the name sent. Example, John Doe.
card_address:If this option was turned on, this is the card address as entered by the user.
card_city: If this option was turned on, this is the card city as entered by the user.
card_state: If this option was turned on, this is the card state entered by the user
card_postal:If this option was turned on, this is the postal code of the user
card_country: If this option was turned on, this is the Country of user for the card. This would return in 2 code format. Example, us, fr, uk, e.t.c
additional variables:The additional variables you specified when creating the Virtual card offer shall all be returned.
From the example above, we shall return what the user entered as date_of_birth and phone_number. The names of the variables are what you specified them to be when adding into those fields. This is necessary if you want some additional information to be able to create the card.
RETURN VALUES FOR CARD CREATION
NAME
status
status
success or pending or failed
REQUIRED
Yes
DESCRIPTION
should return success if the card has been created, should return pending if the card has been created but the card details are still processing, should return failed if the card could not be created.
identifier
Yes
This is the ID to recognize a card created. Ex:4985098ht0hhbeuhf
9uhfuhjo
note
Yes
A note should always be sent for every call, this would be displayed to the customer to know what error or success the API is returning
FETCH CARD DETAILS
call_method == fetch
call method is the type of query for this call. On that URL specified, we shall send a variable called ‘call method’ and it shall contain the value called fetch. Meaning that this call is to fetch a specific card details
POST variables sent by Peerwallet to your end point URL for this call are as follows;
[ call_method, identifier]
identifier: This is the unique token stored when the card was created, every virtual card is identified by a unique token when they are being created. This token is called the identifier which is sent to this end url for your to fetch card details.
RETURN VALUES TO FETCH CARD DETAILS
NAME
status
VALUE
processed or failed
REQUIRED
Yes
DESCRIPTION
This is an indication that the card details has been fetched, else return failed and add appropriate note of what happened
card_status
active, blocked, in-active, frozen
Yes
You can use any of the status recommended, if status is active it would appear on peerwallet as green, the remaining status would be red.
note
Yes
A note should always be sent for every call, this would be displayed to the customer to know what error or success the API is sending.
card_bal
Yes
The available balance of the card
card_name
Yes
The name of the card
card_number
Yes
The number on the card
card_exp_month
Yes
The Exp Month of the card
card_exp_year
Yes
The Exp Year of the card
card_cvv
Yes
The CVV Year of the card
card_address
No
The billing address of the card
card_city
No
The billing city of the card
card_state
No
The billing state of the card
card_postal_code
No
The billing postal code of the card
card_country
No
The billing country of the card
TERMINATE CARD
[call_method, identifier, response ]
Response would include any of the following;paid, cancelled or failed
paid: means the user has paid for the subscription
Cancelled:means the user has cancelled the subscription, you should further delete or freeze the card from your end
Failed:means the user's doesn't have not enough to pay the subscription, you should further delete or freeze the card from your end
call_method == recurring
LOAD CARD BALANCE
call_method == load
call method is the type of query for this call. On that URL specified, we shall send a variable called ‘call method’ and it shall contain the value called load. Meaning that this call is load the balance of a particular card
POST variables sent by Peerwallet to your end point URL for this call are as follows;
[ call_method, amount, identifier]
amount: This is the amount the user want to load on the card, the amount here is in the selling currency you specified when creating the card offer. your end
identifier: This is the unique token stored when the card was created, every virtual card is identified by a unique token when they are being created. This token is called the identifier which is sent to this end url for your to fetch card details
RETURN VALUES FOR CARD BALANCE
NAME
status
VALUE
success or pending or failed
REQUIRED
Yes
DESCRIPTION
should return success if the card has been loaded, should return pending if the card has been loaded but still processing, should return failed if the card could not be loaded.
note
Yes
A note should always be sent for every call, this would be displayed to the customer to know what error or success the API is sending.
FETCH CARD TRANSACTIONS
call_method == trans
call method is the type of query for this call. On that URL specified, we shall send a variable called ‘call method’ and it shall contain the value called trans. Meaning that this call is to fetch the transactions of a specific card
POST variables sent by Peerwallet to your end point URL for this call are as follows;
[call_method, identifier]
identifier:This is the unique token stored when the card was created, every virtual card is identified by a unique token when they are being created. This token is called the identifier which is sent to this end url for you to fetch card details.
RETURN VALUES FOR CARD FETCH TRANSACTIONS
NAME
status
VALUE
processed or failed
REQUIRED
Yes
DESCRIPTION
should return processed if the details has been fetched else return failed
note
Yes
A note should always be sent for every call, this would be displayed to the customer to know what error or success the API is sending
data [details, amount, date]
Yes
This should be a simple array of values.
data [ details, amount, date ]
data [ details, amount, date ]
data [ details, amount, date ] e.t.c
