#1 Payment Collection tool

Documentation

Overview

Sparkle  provides you access to your resources through RESTful endpoints. so you can test the API. You would also be able to access your test API credential and keys from here

HTTP Request Sample

We would provide cURL request sample, just so you can quickly test each endpoint on your terminal or command line. Need a quick how-to for making cURL requests? just use an HTTP client such as Postman, like the rest of us!

Requests and Responses

Both request body data and response data are formatted as JSON. Content type for responses are always of the type application/json. You can use the Tryba API in test mode, which does not affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode

Errors

Errors are returned when one or more validation rules fail or unauthorized access to API. Examples include not passing required parameters e.g. not passing the transaction/provider ref during a re-query call will result in a validation error. Here's a sample below:

                                    
                                    {
                                        "status": "failed",
                                        "message": "tx_ref is required",
                                        "data": "null"
                                    }
                                    
                                    

Initiate Transaction

This is your IPN url, it is important for receiving payment notification. Successful transactions redirects to this url after payment. {tx_ref} is returned, so you don't need to pass it with your url

URL to redirect to when a transaction is completed. This is useful for 3DSecure payments so we can redirect your customer back to a custom page you want to show them.

Your transaction reference. This MUST be unique for every transaction.

This is the first_name of your customer.

This is the last_name of your customer.

This is the email address of your customer. Transaction notification will be sent to this email address

Currency to charge in. [ 'XOF', 'KES', 'NGN', 'RWF', 'ZAR', 'EUR', 'UGX', 'GBP', 'USD', 'ZMW' ]

Amount to charge the customer.

{
"title":"Title of payment",
"description":"Description of payment",
"logo":"https://assets.piedpiper.com/logo.png"
}

You can pass extra information here.

                                    
                                    curl -X POST "https://whitelabel.justwallet.com/sparkle/public/api/payment" 
                                    -H "Accept: application/json" 
                                    -H "Authorization: Bearer {secret_key}"
                                    -d "{
                                        "amount": "100",
                                        "currency": "NGN",
                                        "email": "[email protected]",
                                        "first_name":"John",
                                        "last_name":"Doe",
                                        "callback_url": "https://webhook.site/9d0b00ba-9a69-44fa-a43d-a82c33c36fdc",
                                        "return_url": "https://webhook.site",
                                        "tx_ref": "2346vrcd",
                                        "customization": {
                                            "title": "Test Payment",
                                            "description": "Payment Description",
                                            "logo": "https://assets.piedpiper.com/logo.png"
                                        },
                                        "meta": {
                                            "uuid": "uuid",
                                            "response": "Response"
                                        }
                                    }"
                                    
                                

Response

                                    
                                    {
                                        "message": "Payment link created",
                                        "status": "success",
                                        "data": {
                                            "checkout_url": "https://whitelabel.justwallet.com/sparkle/public/payment/09229936784"
                                        }
                                    }
                                    
                                

Validate a Transaction

This shows you how to validate a transaction

                                    
                                    curl -X GET "https://whitelabel.justwallet.com/sparkle/public/api/transaction/{tx_ref}"
                                    -H "Accept: application/json" 
                                    -H "Authorization: Bearer {secret_key}"
                                    
                                

Response

                                    
                                    {
                                        "message": "Payment details",
                                        "status": "success",
                                        "data": {
                                            "first_name": "John",
                                            "last_name": "Doe",
                                            "email": "[email protected]",
                                            "currency": "NGN",
                                            "amount": "10,000.00",
                                            "charge": "400.00",
                                            "mode": "test",
                                            "type": "API",
                                            "status": "success",
                                            "reference": "20193542126",
                                            "tx_ref": "2346vrcdssdadffx",
                                            "customization": {
                                                "title": "Test Payment",
                                                "description": "Payment Description",
                                                "logo": "https://logo.png"
                                            },
                                            "meta": {
                                                "uuid": "uuid",
                                                "response": "Response"
                                            },
                                            "created_at": "2022-01-12T10:43:09.000000Z",
                                            "updated_at": "2022-01-12T10:43:09.000000Z"
                                        }
                                    }
                                    
                                

Integrating Website Payment

Receiving money on your website is now easy. All you need to do is copy the html form code below to your website page

                                    
                                    <form method="POST" action="https://whitelabel.justwallet.com/sparkle/public/ext_transfer" >
                                        <input type="hidden" name="secret_key" value="{secret_key}" />
                                        <input type="hidden" name="callback_url" value="https://example.com/callbackurl" />
                                        <input type="hidden" name="return_url" value="https://example.com/returnurl" />
                                        <input type="hidden" name="tx_ref" value="2346vrcd" />
                                        <input type="hidden" name="amount" value="100" />
                                        <input type="hidden" name="currency" value="USD" />
                                        <input type="hidden" name="email" value="[email protected]" />
                                        <input type="hidden" name="first_name" value="John" />
                                        <input type="hidden" name="last_name" value="Doe" />
                                        <input type="hidden" name="title" value="Test Payment" />
                                        <input type="hidden" name="description" value="Payment Description" />
                                        <input type="hidden" name="logo" value="https://example.com/logo.png" />
                                        <input type="hidden" name="meta" value="" />
                                        <input type="submit" value="submit" />
                                    </form>
                                    
                                

Initiate Transaction

This is important for creating payment links

This is your IPN url, it is important for receiving payment notification. Successful transactions redirects to this url after payment. {tx_ref} is returned, so you don't need to pass it with your url

URL to redirect to when a transaction is completed. This is useful for 3DSecure payments so we can redirect your customer back to a custom page you want to show them.

Your transaction reference. This MUST be unique for every transaction.

This is the first_name of your customer.

This is the last_name of your customer.

This is the email address of your customer. Transaction notification will be sent to this email address

Currency to charge in. [ 'XOF', 'KES', 'NGN', 'RWF', 'ZAR', 'EUR', 'UGX', 'GBP', 'USD', 'ZMW' ]

Amount to charge the customer.

{
"title":"Title of payment",
"description":"Description of payment",
"logo":"https://assets.piedpiper.com/logo.png"
}

You can pass extra information here.

Sample Inline Redirect Implementation

You can embed Sparkle on your page using our SparkleCheckout() JavaScript function. The function responds to your request in accordance with your request configurations. If you specify a callback_url in your request, the function will redirect your users to the provided callback URL when they complete the payment.

                                    
                                    <form>
                                    <script src="https://whitelabel.justwallet.com/sparkle/public/js/payment.js"></script>
                                    <div id="message"></div>
                                    <button type="button" onClick="makePayment()">Pay Now</button>
                                    </form>
                                    <script>
                                        function makePayment(){
                                        SparkleCheckout({
                                            "secret_key": "PUB-yeybqoM9nCEjf2eQ7FLgCrbDtGWZhPay",
                                            "tx_ref": "7657863465874",
                                            "amount": "10000",
                                            "currency": "USD",
                                            "callback_url": "https://webhook.site/7657863465874",
                                            "return_url": "https://webhook.site",
                                            "customer":{
                                            "email": "[email protected]",
                                            "first_name":"John",
                                            "last_name":"Doe",
                                            },
                                            "customization": {
                                            "title": "Test Payment",
                                            "description": "Payment Description",
                                            "logo": "https://assets.piedpiper.com/logo.png"
                                            },
                                            "meta": {
                                            "uuid": "uuid",
                                            "response": "Response"
                                            }
                                        });
                                        }
                                        </script>
                                    
                                

woocommerce

Woo commerce plugin for sparkle for easy checkout

Create card

This is your IPN url, it is important for receiving payment notification webhooks

Currency to charge in. [ 'NGN', 'USD' ]

Amount to charge the customer.

                                
                                curl -X POST "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/create" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                -d "{
                                    "amount": "10000",
                                    "currency": "NGN",
                                    "callback_url": "https://webhook.site/"
                                }"
                                
                            

Response

                                
                                {
                                    "message": "Payment link created",
                                    "status": "success",
                                    "data": {
                                    "id": "gd07622d-0e2c-43bc-baad-4df37d6f7f5f4",
                                    "user_id": "dge7622d-0e2c-43bc-baad-4df37d6f7f5f4",
                                    "account_id": 2002803,
                                    "card_hash": "ba07622d-0e2c-43bc-baad-4df376f7f5f4",
                                    "card_pan": "4288030060916824",
                                    "masked_card": "428803*******6824",
                                    "cvv": "789",
                                    "expiration": "2025-06",
                                    "card_type": "visa",
                                    "name_on_card": "CEN Ezikel",
                                    "callback": "https://webhook.site",
                                    "amount": "10000",
                                    "charge": "1",
                                    "status": 1,
                                    "ref_id": "VC-KAJjxd",
                                    "city": null,
                                    "state": null,
                                    "address": null,
                                    "zip_code": null,
                                    "currency": "11",
                                    "paid": "10100",
                                    "created_at": "2022-01-24T02:14:10.000000Z",
                                    "updated_at": "2022-01-24T02:14:10.000000Z",
                                    "business_id": "2227090"
                                    }
                                }
                                
                            

Fund card

Amount to charge the customer.

Card identification number.

                                
                                curl -X POST "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/fund" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                -d "{
                                    "amount": "10000",
                                    "card_hash": "ba07622d-0e2c-43bc-baad-4df376f7f5f4"
                                }"
                                
                            

Response

                                
                                {
                                    "message": "Card Funding successful",
                                    "status": "success",
                                    "data": {}
                                }
                                
                            

Withdraw card

Amount to charge the customer.

Card identification number.

                                
                                curl -X POST "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/withdraw" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                -d "{
                                    "amount": "10000",
                                    "card_hash": "ba07622d-0e2c-43bc-baad-4df376f7f5f4"
                                }"
                                
                            

Response

                                
                                {
                                    "message": "Card Withdrawal successful",
                                    "status": "success",
                                    "data": {}
                                }
                                
                            

Block card

                                
                                curl -X GET "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/block/{card_hash}" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                
                            

Response

                                
                                {
                                    "message": "Card Blocked",
                                    "status": "success",
                                    "data": {}
                                }
                                
                            

Unblock card

                                
                                curl -X GET "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/unblock/{card_hash}" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                
                            

Response

                                
                                {
                                    "message": "Card Unblocked",
                                    "status": "success",
                                    "data": {}
                                }
                                
                            

Terminate card

                                
                                curl -X GET "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/terminate/{card_hash}" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                
                            

Response

                                
                                {
                                    "message": "Card Terminated",
                                    "status": "success",
                                    "data": {}
                                }
                                
                            

Card transactions

                                
                                curl -X GET "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/transactions/{card_hash}" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                
                            

Response

                                
                                {
                                    "message": "Card Transactions",
                                    "status": "success",
                                    "data": {}
                                }
                                
                            

All Cards

                                
                                curl -X GET "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/all" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                
                            

Response

                                
                                {
                                    "message": "All Cards",
                                    "status": "success",
                                    "data": {}
                                }
                                
                            

Get a Card

                                
                                curl -X GET "https://whitelabel.justwallet.com/sparkle/public/api/virtual_card/card/{card_hash}" 
                                -H "Accept: application/json" 
                                -H "Authorization: Bearer {secret_key}"
                                
                            

Response

                                
                                {
                                    "message": "All Cards",
                                    "status": "success",
                                    "data": {}
                                }