How to receive payment
This page will explain how to receive payment via Particeep's API.
1 - Setting up the environment
There are some prerequisites you need to set up in order for the wallet module to properly work :
- You need an administrator user with the same email as the one defined on your consumer
-
To set a user as administrator, you need to create a role "admin" for this user via the following endpoint :
(PUT) /v1/role/{user_id}/add/{role_name}
String user_id = "1234"; String role = "admin"; String url = "https://test-api.particeep.com/v1/role/" + user_id + "/add/" + role; JsonNode role = Json.newObject() .put("target_id", "string") .put("target_type", "string"); HttpResponse result = WS.url(url).put(role); String result = result.getString(); System.out.println(result);
- You need to have a payment provider set up on you consumer. This should already be settled with our sales team.
- You need a confirmed wallet for this user. This wallet will be the one credited with the transactions fees.
2 - The Wallet module
The wallet module allows to link a virtual wallet to a user. This wallet is then used to move money between users.
Create a wallet
The creation of a wallet for a given user can be done with the following endpoint :
(PUT) /v1/wallet
String url = "https://test-api.particeep.com/v1/wallet";
JsonNode wallet = Json.newObject()
.put("owner_id", "string")
.put("owner_type", "string")
.put("wallet_type", "NATURAL")
.put("owner_ip", "string")
.put("email", "string")
.put("first_name", "string")
.put("last_name", "string")
.put("gender", "MAN")
.put("birthday", "string")
.put("nationality", "string")
.put("countryOfResidence", "string")
.put("businessName", "string");
HttpResponse result = WS.url(url).put(wallet);
String result = result.getString();
System.out.println(result);
Various information are needed in order to create a valid wallet.
Confirm a wallet
A wallet must be validated by the payment provider in order to proceed to payments. The validation of a wallet is done via the kyc module and its endpoints :
-
Create the kycs :
(PUT) /v1/kycs
String url = "https://test-api.particeep.com/v1/kycs"; JsonNode kycs = Json.newObject() .put("owner_id", "string") .put("owner_type", "string") .put("user_type", "NATURAL"); HttpResponse result = WS.url(url).put(kycs); String result = result.getString(); System.out.println(result);
-
Update the kycs :
(POST) /v1/kycs
String url = "https://test-api.particeep.com/v1/kycs"; JsonNode id_card = Json.newObject() .put("doc_type", "ID_CARD") .put("url", "string"); JsonNode kycs = Json.newObject() .put("owner_id", "string") .put("owner_type", "string"); kycs.putArray(docs).add(id_card); HttpResponse result = WS.url(url).post(kycs); String result = result.getString(); System.out.println(result);
-
Send the kycs to the payment provider for validation :
(POST) /v1/kycs/askValidation/owner/{owner_id}/{owner_type}
String owner_id = "1234"; String owner_type = "USER"; String url = "https://test-api.particeep.comPOST /v1/kycs/askValidation/owner/"+ owner_id + "/" + owner_type; JsonNode kycs = Json.newObject(); HttpResponse result = WS.url(url).post(kycs); String result = result.getString(); System.out.println(result);
Fund a wallet
Once the wallet is validated, the funding of a wallet through credit card can be done with the following endpoint :
(POST) /v1/wallet/{id}/cashin
String id = "1234"
String url = "https://test-api.particeep.com/v1/wallet/" + id + "/cashin";
JsonNode cashin = Json.newObject()
.put("amount", "0")
.put("fees", "0")
.put("tag", "string")
.put("accept_url", "string")
.put("decline_url", "string")
.put("pending_url", "string")
.put("owner_ip", "string")
.put("locale", "fr_FR");
HttpResponse result = WS.url(url).post(cashin);
String result = result.getString();
System.out.println(result);
An url (depending on the payment provider) will be returned. You should redirect the user to it in order for him to fill in his credit card details. You can feed to the endpoint redirection urls in case of success or failure.
Make a transfer between wallets
A transfer between two wallets can be done with the following endpoint :
(POST) /v1/wallet/transfer
String url = "https://test-api.particeep.com/v1/wallet/transfer";
JsonNode transfer = Json.newObject()
.put("debited_wallet_id", "string")
.put("credited_wallet_id", "string")
.put("amount", "0")
.put("fees", "0")
.put("tag", "string");
HttpResponse result = WS.url(url).post(transfer);
String result = result.getString();
System.out.println(result);
The fees set in the request will be transfered to the administrator's wallet.
Cash out a wallet
You can associate a bank account to a wallet through the endpoint :
(PUT) /v1/wallet/{id}/bankaccount
String id = "1234"
String url = "https://test-api.particeep.com/v1/wallet/" + id + "/bankaccount";
JsonNode bankAccount = Json.newObject()
.put("bank_name", "string")
.put("iban", "string")
.put("bic", "string")
.put("number", "string")
.put("street", "string")
.put("zip", "string")
.put("city", "string")
.put("country", "string ")
.put("acct_num", "string")
.put("aba_num", "string")
.put("transit_num", "string")
.put("target_id", "string");
HttpResponse result = WS.url(url).put(bankAccount);
String result = result.getString();
System.out.println(result);
Once the bank account has been validated, you can proceed to cash out the wallet to this bank account via :
(POST) /v1/wallet/{id}/cashout
String id = "1234"
String url = "https://test-api.particeep.com/v1/wallet/" + id + "/cashout";
JsonNode cashout = Json.newObject()
.put("bank_account_id", "string")
.put("amount", "0")
.put("fees", "0")
.put("tag", "string");
HttpResponse result = WS.url(url).post(cashout);
String result = result.getString();
System.out.println(result);
You want to cash out the wallet associated to the administrator user to collect the fees applied to other users' payments.
3 - The Payment module
If you are using the transaction module, you can transfer money accordingly using the payment module, which can use wallet transfer or direct credit card payment.
Pay a transaction
There are three ways to pay a transaction :
-
You can transfer money from the source's wallet to the target's with this endpoint :
(POST) /v1/payment/wallet/{transaction_id}
String transaction_id = "1234" String url = "https://test-api.particeep.com/v1/payment/wallet/" + transaction_id; JsonNode payment = Json.newObject(); HttpResponse result = WS.url(url).post(payment); String result = result.getString(); System.out.println(result);
-
You can directly fund the target's wallet with a credit card with this endpoint :
(POST) /v1/payment/cash-in/direct/{transaction_id}
String transaction_id = "1234" String url = "https://test-api.particeep.com/v1/payment/cash-in/direct/" + transaction_id; JsonNode payment = Json.newObject() .put("accept_url", "string") .put("decline_url", "string") .put("pending_url", "string") .put("owner_ip", "string") .put("locale", "fr_FR"); HttpResponse result = WS.url(url).post(payment); String result = result.getString(); System.out.println(result);
-
You can fund the source's wallet with a credit card and then make a transfer from the source's wallet to the target's with this endpoint :
(POST) /v1/payment/credit-card/{transaction_id}
String transaction_id = "1234" String url = "https://test-api.particeep.com/v1/payment/credit-card/" + transaction_id; JsonNode payment = Json.newObject() .put("accept_url", "string") .put("decline_url", "string") .put("pending_url", "string") .put("owner_ip", "string") .put("locale", "fr_FR"); HttpResponse result = WS.url(url).post(payment); String result = result.getString(); System.out.println(result);
(POST) /v1/payment/{transaction_id}
String transaction_id = "1234"
String url = "https://test-api.particeep.com/v1/payment/" + transaction_id;
JsonNode payment = Json.newObject()
.put("accept_url", "string")
.put("decline_url", "string")
.put("pending_url", "string")
.put("owner_ip", "string")
.put("locale", "fr_FR");
HttpResponse result = WS.url(url).post(payment);
String result = result.getString();
System.out.println(result);
Refund a transaction
In order to refund a transaction, you should use this endpoint :
(POST) /v1/payment/refund/{transaction_id}
String transaction_id = "1234"
String url = "https://test-api.particeep.com/v1/payment/refund/" + transaction_id;
JsonNode refund = Json.newObject();
HttpResponse result = WS.url(url).post(refund);
String result = result.getString();
System.out.println(result);
The amount will be refunded on the source's wallet if the transaction has been paid with wallets, or on the source's credit card if it has been paid by credit card.
Next steps
Now that you know how to proceed to payments, you may want to look into how to confirm a payment :