Particeep

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 :

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 :

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 :

A fourth endpoint is available :
(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);
		
In this case, if the source has enough funds on its wallet, the amount is tranfered to the target. If not, the transaction is paid with credit card.

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 :