Integrating PAYMENTPLUG's Wallet for a Crowdfunding platform
I am developing a Crowdfunding Platform. How to implement PAYMENTPLUG Wallet ?
This document specifies the workflow and basic functionalities used by crowdfunding to process payments with PAYMENTPLUG's Wallet API. For specific needs, please contact our team at support@paymentplug.com .
INTRODUCTION
PAYMENTPLUG is a payment solution which enables crowdfunding platform to easily process third-party payments.
Wallet Master Account Set-up
Your first step is to register your platform and create a sandbox account.
Please request our support team support@paymentplug.com in order to setup your Master Account.
Once your master account is created, you will have the access to PAYMENTPLUG’s wallet API and dashboard.
AUTHENTICATION
For Authentication you need to pass verification hash generated using SHA256 algorithm and the secret key shared by us.
Parameters to be included while calculating the hash are different for each API. Kindly refer API docs for more details.
INTEGRATION
Register project owner
1. Create a project owner user
Users can be:
- Individual: a natural person
- Legal: a business, organization, sole trade
User Type can be Individualor Legal .
If user type is legal then entity type can be Business/ Organization/ Public Company/ Private Company/Sole Trader.
Account type has to be Merchant in the request.
Create project owner with the following API call, please refer to our documentation in details regarding createAccount (for individual) & createBusinessAccount (for legal entity).
Sample Request
{
"token": "OZa6b6SNays37d+UVaWnfqJsuHI5W+i4SawctRtwy4A=",
"country_code": "44",
"mobile": "2078137221",
"custCountry": "England",
"email": "abclimited@yahoo.com",
"password": "Test@1234",
"account_type": "Merchant",
"user_type": "Legal",
"entity_type": "Business",
"business_nature_type": "Retailer",
"walletOwnerId": "1",
"platformId": "1",
"deviceId": "abcd1234",
"Currency": "GBP",
"companyDetail": {
"companyNumber": "12345678",
"companyName": "ABC Limited",
"companyWebsite": "www.company.com",
"companyRegisteredDate": "30/06/2012",
"taxCountryISO": "GB",
"taxNumber": "2587419635",
"directorCount": "2",
"uboCount": "3",
"registeredAddress": {
"postalCode": "SE6 9YU",
"countryISO": "GB",
"address": "7",
"state": "Brick Lane",
"city": "London"
}
},
"tradingDetail": {
"tradingName": "ABC Limited",
"tradingAddress": {
"postalCode": "DH6 4JN",
"countryISO": "GB",
"address": "12 Park Ave",
"street": "Coxhoe",
"city": "Durham"
}
},
"contactPerson": {
"firstName": "Test",
"lastName": "docs",
"dob": "30/06/2000"
},
"roles": [
"ubo"
],
"registeredAddress": {
"postalCode": "401105",
"countryISO": "IN",
"address": "xyz",
"state": "Maharashtra",
"city": "Mumbai"
},
"isTosOfTWAccepted": true,
"termsConsent": "Terms of Services and privacy policy",
"emailOtp": "521478",
"otp": "784963"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1",
"customerId": "189405"
}
Store the received user information, particularly the customerId, as it is required for all user actions.
2. Add Business Person
To complete the due diligence requirements for a legal entity, you also need to collect details of business person. Number of business person required depends on your due diligence requirements. For Example : You may require at least 2 persons with the role of director and one primaryContact of the business. You can add these business person using the addBusinessPerson API. One of the Business person need to be the Primary Contact. If your business has only 1 Director, you will be able to create only 1 person and the same person can be identified as both a director and a primaryContact.
If any person owns more than 25% in the business, you can set their role as a ubo (ultimate beneficial owner).
Sample Request
{
"customerId": "189405",
"walletOwnerId": "1",
"firstName": "John",
"lastName": "Doe",
"dob": "30/06/1990",
"roles": [
"director",
"ubo",
"primaryContact"
],
"residentialAddress": {
"postalCode": "SE6 9YU",
"countryISO": "GB",
"address": "7",
"state": "Brick Lane",
"city": "London"
},
"verificationHash": "7d420e0efa467bc32438043cd2a29f26b37e9e30910fdd6aff08bf5f774a018d"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1",
"customerId": "189405"
}
Store the received information, particularly the personid, as it is required for other actions. all user actions.
3. Create a project owner's e-wallet
Use the customerId, to createWalletwhich enables the user to store e-money. The e-wallet is owned by the respective user. The e-wallet will be identified by its currency and user can create only 1 e-wallet for each currency. In order to get the list of e-wallets for each customer, you can call the getWalletList API.
Sample Request
{
"customerId": "189405",
"walletOwnerId": "1",
"walletName": "Wallet_GBP",
"walletCurrency": "GBP",
"walletId": "",
"verificationHash": "7d420e0efa467bc32438043cd2a29f26b37e9e30910fdd6aff08bf5f774a018d"
}
Sample Response
{
"responseCode": "1",
"status": "SUCCESS"
}
4. Register a project owner's bank account
Register the project owner's bank account API to payout the funds from his e-wallet(s).
Sample Request
{
"customerId": "189405",
"walletOwnerId": "1",
"bankName": "SBM",
"accountNumber": "41406760",
"accountHolderName": "John Doe ",
"sortCode": "309457",
"countryISO": "GB",
"IBAN": "FR7630004000031234567890143",
"BIC": "CRLYFRPP",
"currency": [
"GBP",
"USD"
],
"bankAddress": {
"postalCode": "SE6 9YU",
"address": "7",
"street": "Brick Lane",
"city": "London"
},
"isDefault": "N",
"verificationHash": "7d420e0efa467bc32438043cd2a29f26b37e9e30910fdd6aff08bf5f774a018d"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1",
"bankId": "72345"
}
Store the received information, particularly the bankAccountId, as it is required for other actions. Also you can get the list of Bank Account Details using our listBankAccounts API.
5. Create and submit KYC documents
Project Owner refers to any individuals or businesses that are selling goods on your platform. Given that you control the entire experience of the project owner's on your platform, and Paymentplug never interacts directly with them, you will need to build flows to collect the necessary information required for performing Due Diligence on the project owner's and submit the same on Paymentplug platform. List of KYC required for project owner can be configured using Wallet Owner Interface. Example List.
| Each Business Person | Company Documents |
|---|---|
| IDENTITY PROOF | ARTICLES OF ASSOCIATION |
| ADDRESS PROOF | SHAREHOLDER DECARATION |
| REGISTRATION PROOF |
The documents need to be validated by your compliance team using wallet owner dashboard.
Find more technical information here.
Register Contributors
1. Create a contributor
Create a contributor by repeating the project owner creation process.
Once again, contributor and project owner can be a natural person (natural user) or a legal entity (legal user).
User Type can be individual or legal.
Account type has to be Customer.
2. Create a contributor's e-wallet
Create a buyers wallet account by using the createWallet API. The e-wallet will be identified by its currency and user can create only 1 e-wallet for each currency. In order to get the list of e-wallets, you can call the getWalletList API.
3. Register a contributor's bank account
Register the contributor's bank account to payout the refunds from his e-wallet(s) by repeating the project owner’s e-wallet creation process.
4. Register Card Details
Create a card registration token to store reusable and non-sensitive card details (tokens) within PAYMENTPLUG’s environment. This object is linked to the user with the customerID
.For more details please refer addCard API. Also you can get the list of card details using our listCards API.
Sample Request
{
"customerId": "189405",
"cardNumber": "4111110000000021",
"cardFirstName": "John",
"cardLastName": "Doe",
"expiryDate": "02/25",
"cardType": "VISA CARD",
"cardNameIdentifier": "john",
"isDefaultToBeUsed": 1,
"isEncrypted": "N",
"verificationHash": "dbcc5c99b33478b684abd0c16b8da1a2b934d765758f7e16d047808df73d1e6c"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1",
"cardId": "262"
}
The registered card may be used multiple times. You need to store the cardId in the response for one click pay-in. Also you can get the list of Card Details using our listCards .
Payment execution (pay-in)
Project Owner and contributors have now been registered within our API. The next step is to send funds to a user’s e-wallet.
1. Pay-In by registered card
We recommend using our Direct Load endpoint for a seamless integration and one-click payments.
The API call contains the cardID, currency, amount (in cents), and other additional information as mentioned in the API.
Sample Request
{
"merchantTransactionId": "TD23243456577",
"amount": "50.00",
"currency": "USD",
"cardId": "262",
"cardCvv": "123",
"customerId": "189405",
"walletOwnerId": "1",
"transactionType": "LOAD",
"mobilePlatform": "iOS",
"paymentMode": "CC",
"paymentBrand": "VISA",
"customerEmail": "abclimited@yahoo.com",
"customerFirstName": "John",
"customerLastName": "Doe",
"cardNumber": "4111110000000021",
"cardExpiryMonth": "12",
"cardExpiryYear": "2033",
"customerName": "John Doe",
"country": "England",
"city": "Durham",
"state": "Coxhoe",
"postcode": "DH6 4JN",
"street1": "12 Park Ave",
"verficationHash": "47ec67262f2f05b8a269eaa732d46540ffa56359a94f4a46d8b994c91c0b6381"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "8",
"amount": "50.00",
"transactionId": "262067"
}
User contributors pay into their respective e-wallets but funds should NOT be escrowed there. You should directly transfer the funds to the project's e-wallet.
Once the funds are credited on the contributor’s e-wallet, call our purchase API endpoint from the contributor’s account to the project owner’s account.
Sample Request
{
"customerId": "189405",
"transactionType": "PURCHASE",
"currency": "GBP",
"type": "Card",
"walletOwnerId": "1",
"products": [
{
"vendorId": "275",
"amount": "10.00",
"orderDescription": "Product Name"
},
{
"vendorId": "375",
"amount": "10.00",
"orderDescription": "Product Name2"
}
],
"verficationHash": "47ec67262f2f05b8a269eaa732d46540ffa56359a94f4a46d8b994c91c0b6381"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1",
"currency": "GBP",
"purchase": [
{
"purchaseId": "189765",
"vendorId": "275",
"amount": "10.00"
},
{
"purchaseId": "189766",
"vendorId": "375",
"amount": "10.00"
}
]
}
2. Pay-In using web load SDK
Web load end point returns the payment page URL in return. You should display payment page to the buyer. Once the payment is successful user account get updated.
The API call contains currency, amount (in cents), and additional information as mentioned in the Web load SDK
Sample Request
String params ="
merchantTransactionId="TD32434553454"
&amount="50.00"
¤cy="USD"
&descriptor="TD32434553454"
&customerId="189405"
&walletOwnerId="1"
&verificationHash="8416e8c5cf8cecc7325d19c5b12015863d37f18f2ee9b669c975bf2db2be6125"
&transactionType="LOAD"
&mobilePlatform="android/iOS/web"
&paymentMode="CC"
&paymentBrand="VISA";
Sample Response
{
"status": "Success",
"amount": "50.00",
"statusdescription": "Transaction Successful"
}
User contributors pay into their respective e-wallets but funds should NOT be escrowed there. You should directly transfer the funds to the project's e-wallet.
Once the funds are credited on the buyer’s account, call our purchase API endpoint from the buyer’s account to the seller’s account.
3. Pay-In by bank transfer
Bank transfer payments involve contributor sending funds to their account on PAYMENTPLUG which are then credited to the project owner’s account as a separate transaction.
The first step is to get the contributor to make a bank transfer to their account on PAYMENTPLUG.
Call the Bank Pay-IN API as below.
Sample Request
{
"customerId": "189405",
"walletOwnerId": "1",
"amount": "50.00",
"verificationHash": "dbcc5c99b33478b684abd0c16b8da1a2b934d765758f7e16d047808df73d1e6c"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1",
"referenceId": "3454545478",
"bankName": "SBM",
"accountNumber": "41406760",
"accountHolderName": "John Doe",
"sortCode": "309457",
"IBAN": "FR7630004000031234567890143",
"BIC": "CRLYFRPP"
}
The API call will return the bank details to which the contributor will need to make a transfer. This also includes a reference which will need to be provided on the bank transfer. You should display these bank details to the contributor instructing them to make a transfer with the reference provided. It is recommended that you highlight to your contributors the importance of sending the transfer with the accurate reference as otherwise the transaction will automatically be returned to the sender. Allowing users to easily copy the reference on your UI is often useful. User contributors pay into their respective e-wallets but funds should NOT be escrowed there. You should directly transfer the funds to the project's e-wallet. Once the funds are credited on thecontributor’s e-wallet, call our purchase API endpoint from the contributor’s account to the project owner’s account.
Funds Management
As a crowdfunding platform, you may manage funds between contributors and project owners.
1. Refund
PAYMENTPLUG as a crowdfunding platform, you may manage funds between contributors and project owners.
Create one or several transfer refunds to allow the contributor to reinvest into another project.
Alternatively, refund the credit card payment (transfer refund then pay-in refund ).
- Transfer refund : reimbursement to a user e-wallet
- Pay-in refund : reimbursement to a user card
Create a Transfer Refund by using the transactionId returned during purchase.
Sample Request
{
"customerId": "189405",
"walletOwnerId": "1",
"amount": "10.00",
"currency": "GBP",
"transactionId": "189765",
"transactionType": "TRANSFER",
"verificationHash": "dbcc5c99b33478b684abd0c16b8da1a2b934d765758f7e16d047808df73d1e6c"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1"
}
Create PayIn Refund using pay in transactionId returned during direct load or web load.
Sample Request
{
"customerId": "189405",
"walletOwnerId": "1",
"amount": "10.00",
"currency": "GBP",
"transactionId": "189765",
"type": "PAYIN",
"verificationHash": "dbcc5c99b33478b684abd0c16b8da1a2b934d765758f7e16d047808df73d1e6c"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1"
}
2. Transfer funds between contributor and project owner
A transfer request allows you to move funds from one e-wallet to another. In the crowdfunding flow, funds will be transferred from the contributor’s e-wallet to the project owner’s using transfer API.
Sample Request
{
"amount": "50",
"to_cust_id": "427",
"from_cust_id": "189405",
"comment": "personal",
"walletOwnerId": "1",
"fromCurrencyCode": "USD",
"accountType": "Wallet",
"walletId": "123",
"verificationHash": "c5c87ac4cc094858fd635c1f010fa2254620ac667b8f6684416c78a96c0ce2e4"
}
Sample Response
{
"to_cust_name": "XYZ",
"amount": "50.00",
"responseCode": 1
}
3. Pay-out to the project owner's bank account
The last step of the crowdfunding transaction flow is the bankPayout .
Sample Request
{
"customerId": "189405",
"walletOwnerId": "1",
"amount": "10.00",
"fromCurrency": "GBP",
"bankId": "189765",
"verificationHash": "dbcc5c99b33478b684abd0c16b8da1a2b934d765758f7e16d047808df73d1e6c"
}
Sample Response
{
"status": "SUCCESS",
"responseCode": "1"
}
GLOSSARY
| CROWDFUNDING PLATFORM | Online platform where projects are funded by contributors. Transactions are processed by the platform. (You) |
| USER | Natural person (natural user) or a legal person (legal user). |
| PROJECT OWNER | User who owns a project. |
| CONTRIBUTOR | User who contributes to a project. |
| ENTITY TYPE | Business type if the user is a legal user. Can be Business/ Organization/ Public Company/ Private Company/Sole Trader. |
| BUSINESS PERSON | Business person linked to legal user. Can be Director, UBO , primary Contact . |
| E-WALLET | Digital wallet on which electronic money is stored. |
| PAYIN / LOAD | Deposit of funds by a user on an e-wallet. |
| TRANSFER | Movement of funds from one e-wallet to another. |
| PAYOUT | Withdrawal of funds from an e-wallet to a end-user’s bank account. |
| FEE | Commission calculated and collected by the crowdfunding platform. |
| FEE E-WALLET | E-wallet owned by the marketplace to collect fees. |
| REFUND | Reimbursement to a user. |
| KYC (Know your customer) | Verification process of your users’ identity, part of European anti-money laundering regulation. |
| WALLET OWNER ID | ID of the platform operator in PAYMENTPLUG environment. |
| CUSTOMER ID | ID of the end-user in PAYMENTPLUG environment. |
| TRANSACTION ID | ID of any load / pay-in /purchase / transfer done by user. |