# Structure for Building rave Libraries and plugins

## Getting Started

Step 1: sign up for a sandbox account here: http://rave.frontendpwc.com

Step 2: follow instructions here to generate your test keys: https://flutterwavedevelopers.readme.io/v1.0/docs/prerequisite

## Building rave plugins using the rave modal.
When building a rave plugin using the rave modal/javascript Popup modal, this checklist helps as a guide to make sure you have everything covered:

> **Use this SDK as a guide to building yours: https://github.com/Flutterwave/Flutterwave-Rave-PHP-SDK**

> **Also see this plugin as a guide: https://github.com/Flutterwave/WooCommerce-Rave-Payment-Gateway**

- [ ] Implement rave’s integrity checksum flow into your plugin. see [more](https://flutterwavedevelopers.readme.io/docs/checksum) on integrity checksum
- [ ] Ensure you create a test mode switch that allows the user activate test mode or live mode, i.e. the user can set test keys and live keys and you call the test or live endpoint.
- [ ] Ensure that for successful transactions, you either dump the response from the verify status endpoint to the developer or use the response to redirect to a successful page and provide value (e.g. E-commerce/billing plugins).
- [ ] Ensure that for failed transactions, you get the response from the callback functions, pass to the server and make a status check call using merchant’s reference. (https://flutterwavedevelopers.readme.io/v1.0/reference#xrequery-transaction-verification).
- [ ] Ensure you document option for user’s to use multiple currencies on the getpaidSetup function. For e-commerce/billing plugins, implement the country and currency flow from rave within the plugin, see table below.

| Country | Currency
| -------- |:-------------:|
| NG | NGN |
| | USD |
| | KES(Card payments)|
| | EUR |
| | GBP |
| KE | KES (Mpesa account payments)|
| GH | GHS |
| | USD |
| ZA | ZAR |

- [ ] Ensure you document option for developer to toggle on and off payment methods see doc for example (https://flutterwavedevelopers.readme.io/docs/splitting-payment-methods). For e-commerce/billing plugins implement the payment method flow into the admin section.

## Building Rave Libraries using Rave APIs

### Rave Library Services
- [ ] Account charge (NG Banks)
- [ ] Account charge (International for US and ZAR).
- [ ] Card Charge (Bake in support for 3DSecure/PIN).
- [ ] Encryption
- [ ] Transaction status check (Normal requery flow and xrequery).
- [ ] Retry transaction status check flow.
- [ ] Preauth -> Capture -> Refund/void.
- [ ] Support for USSD and Mcash (Alternative payment methods).
- [ ] List of banks for NG Account charge. (Get banks list).
- [ ] Get fees endpoint.
- [ ] Integrity Checksum (https://flutterwavedevelopers.readme.io/docs/checksum).

> API Integration flow:

### Card charge:

- [ ] Step 1: Encrypt payment card details using encryption algorithm, see test and encryptions and algorithm here: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-encryption-2
https://flutterwavedevelopers.readme.io/v1.0/reference#rave-encryption

- [ ] Step 2: When you send card request for Local Mastercard and verve cards you get a response `SUGGESTED_AUTH: "PIN"`. This means you are meant to follow step 1 again, passing `pin` and `suggested_auth: "PIN"` in your request.

- [ ] Step 3: When you send a card request including `redirect_url` in your request(we call your redirect url and append the response to it) for Local Visa cards you get a response you can see here: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-direct-charge

- [ ] Step 4: When you pass an International card i.e. A card whose bin is Not a Nigerian bin,you send a card request including `redirect_url` in your request(we call your redirect url and append the response to it) and get a response.

### Card Validation:

- [ ] Step 1: When you get your response from a direct charge request, you can use the parameter `authModelUsed: "PIN"` || `authModelUsed: "VBVSECURECODE"` || `authModelUsed: "AVS_VBVSECURECODE` to determine validation flow.

- [ ] `authModelUsed: "PIN"`: This requires that you collect otp from the merchant and call the endpoint described here: https://flutterwavedevelopers.readme.io/v1.0/reference#validate-card-charge-1

- [ ] `authModelUsed: "VBVSECURECODE"`: This requires that you load the authurl returned in the response, in an Iframe or new window, the customer validates on the hosted page and we call the url you passed in `redirect_url` appending the response to it.

- [ ] `authModelUsed: "AVS_VBVSECURECODE`: Same flow as `authModelUsed: "VBVSECURECODE"`.

### Account Charge:

*NB: Account payments are currently only available for Nigeria and south Africa.*

- [ ] Step 1: Call the bank account details endpoint: https://flutterwavedevelopers.readme.io/v1.0/reference#list-of-banks

- [ ] Step 2: Encrypt payment account details using encryption algorithm, see test and encryptions and algorithm here: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-encryption-account
https://flutterwavedevelopers.readme.io/v1.0/reference#rave-encryption

- [ ] Step 3: Send payment request to charge the account: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-direct-charge

- [ ] Step 4: Validate account payments by collecting otp from the customer: https://flutterwavedevelopers.readme.io/v1.0/reference#validate-account-charge-1

***NB: We advice merchants that they requery for all failed transactions, to get the final status. See how to do that here: https://flutterwavedevelopers.readme.io/v1.0/reference#transaction-status-check***

### Transaction status check

- [ ] Step 1: call the transaction status endpoint: https://flutterwavedevelopers.readme.io/v1.0/reference#verification

### Transaction status check using xrequery

- [ ] Step 1: call the xrequery endpoint: https://flutterwavedevelopers.readme.io/v1.0/reference#xrequery-transaction-verification

### Preauth payments.

- [ ] Step 1: An introduction to preauthorisation: https://flutterwavedevelopers.readme.io/v2.0/reference#introduction-1
- [ ] Step 2: Encrypt your preauth parameters and call the charge endpoint: https://flutterwavedevelopers.readme.io/v2.0/reference#preauthorise-card
- [ ] Step 3: Capture a preauth payment: https://flutterwavedevelopers.readme.io/v2.0/reference#capture
- [ ] Step 4: Refund or void a preauth payment: https://flutterwavedevelopers.readme.io/v2.0/reference#refund-or-void

> **NB: For Preauth payment please use the keys below:
| Public Key | FLWPUBK-8cd258c49f38e05292e5472b2b15906e-X |
| Secret Key | FLWSECK-c51891678d48c39eff3701ff686bdb69-X |**

> **Preauth payments is based on approval per merchant, and is not open to accounts except approval to use these payment method is given.**

### Get Fees
- [ ] Step 1: https://flutterwavedevelopers.readme.io/v2.0/reference#get-fees

### List of Banks
- [ ] Step 1: https://flutterwavedevelopers.readme.io/v2.0/reference#list-of-banks

### Direct charge payment refunds
- [ ] Step 1: https://flutterwavedevelopers.readme.io/v2.0/reference#refund

### Exchange Rates
- [ ] Step 1: https://flutterwavedevelopers.readme.io/v2.0/reference#exchange-rates

## Alternative payment methods

### Nigerian USSD

> This is currently only available for GTB and Zenith Bank.

- [ ] Step 1: Encrypt payment card details using encryption algorithm, see test and encryptions and algorithm here: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-parameters
https://flutterwavedevelopers.readme.io/v1.0/reference#rave-encryption

- [ ] Step 2: Call the charge endpoint: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-direct-charge
- [ ] Step 3: In sdk documentation FOR GTB show merchant they need to display `*737*50*amount*159#` and the `flwRef` returned for the customer to complete the transaction
- [ ] Step 4: Pass the next step on to the developer, Instruct developer to use webhooks to get notified on transaction, and set it to pending, then complete/failed once notified with same status on webhook. See guide on using webhooks here: https://flutterwavedevelopers.readme.io/v2.0/docs/events-webhooks

- [ ]Step 5: After notification developer would requery and confirm final status.

### Ghana Mobile Money

- [ ] Step 1: Encrypt payment card details using encryption algorithm, see test and encryptions and algorithm here: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-parameters
https://flutterwavedevelopers.readme.io/v1.0/reference#rave-encryption

- [ ] Step 2: Call the charge endpoint: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-direct-charge
- [ ] Pass the next step on to the developer, Instruct developer to use webhooks to get notified on transaction, and set it to pending, then complete/failed once notified with same status on webhook. See guide on using webhooks here: https://flutterwavedevelopers.readme.io/v2.0/docs/events-webhooks

- [ ] After notification developer would requery and confirm final status.

### Kenya Mpesa

- [ ] Step 1: Encrypt payment card details using encryption algorithm, see test and encryptions and algorithm here: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-parameters
https://flutterwavedevelopers.readme.io/v1.0/reference#rave-encryption

- [ ] Step 2: Call the charge endpoint: https://flutterwavedevelopers.readme.io/v1.0/reference#rave-direct-charge
- [ ] Step 3: Display the Mpesa Buisness account number `637747` and the Account number which is returned as `orderRef` in the charge response.


- [ ] Pass the next step on to the developer, Instruct developer to use webhooks to get notified on transaction, and set it to pending, then complete/failed once notified with same status on webhook. See guide on using webhooks here: https://flutterwavedevelopers.readme.io/v2.0/docs/events-webhooks

- [ ] After notification developer would requery and confirm final status.

## Test cases plugins

- [ ] Plugins must use integrity checksum
- [ ] Merchant must be able to toggle between test and live mode.
- [ ] Status of transaction must be verified before showing successful or failed to customer, in cases where the plugin is handling that.
- [ ] Merchants must be able to accept payments in multiple currencies
- [ ] Successful test cards must return successful response to developer or customer
- [ ] Failed test card must return failed response to developer or customer.
- [ ] Merchant must be able to toggle on and off, different payment methods.
- [ ] Integrity checksum must be implemented, in cases where merchant is not passing details to the getpaidSetup function directly.
- [ ] Merchant can use meta tags in getpaidSetup function.

## Test cases Libraries.

- [ ] Customer must be able to perform a mastercard transaction in currency NGN using PIN to authenticate successfully.
- [ ] Customer must be able to perform a Verve card transaction using PIN to authenticate successfully.
- [ ] Customer must be ablet to perform a Visa card transaction using 3DSecure to authenticate successfully.
- [ ] Merchant must be able to get the failure response returned for transactions to them.
- [ ] Merchant must be able to List all banks to be charged for account payments.
- [ ] Merchant must be able to charge all available account methods successfully.
- [ ] Merchant should be able to Requery for transactions using flwRef returned in response.
- [ ] Merchant must be able to use xrequery endpoint to requery transactions with their own unique reference.
- [ ] Merchant must be able to get fees to be charged.
- [ ] Merchant must be able to charge customers using GTB and Zenith USSD successfully.
- [ ] Merchant must be able to charge customers using Mpesa successfully.
- [ ] Merchant must be able to charge customers using Ghana mobile money successfully.