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);

This endpoint returns a list of kycs needed by the payment provider to validate the wallet. You should update it with urls of the needed documents and then ask for their validation.

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);

Both source and target must own a wallet and the source's wallet must by sufficiently funded.

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);

The target must own a wallet.

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);

Both source and target must own a wallet.

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 :

Follow the next tutorial