XRP|BLACK

Client plug-in API documentation

Client plug-in

Before you begin

The following procedure is used to create an end-to-end payment on the client.

Note this assumes you have already created your server-side API to create a new payment request.

You will need the hash and accesskey that was generated.

You must never expose your wallet Secret KEy publically or on any client-side code.

You must also ensure you verify the payment has been successful on the server-side using the server-side generated payment hash.

We do not take any responsibility for exposed Secret Key, or if your code did not properly verify payment has been made successfully.

Pre-requisites.

You must ensure you have included jQuery in your code. This release has been tested to work with 3.6.0:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>

Include xrpblack.css style sheet file in your page <head>:

<link href="https://assets.xrpblack.com/1.0.4/xrpblack.css" rel="stylesheet" />

Include xrpblack.js JavaScript file in your <body>:

<script id="xrpblack" src="https://assets.xrpblack.com/1.0.4/xrpblack.js"></script>

Create a pay button

When creating the XRP|BLACK pay button, you have various choices for sizes.

<div class="xrpblack-pay">
<div class="xrpblack-pay compact"> 
<div class="xrpblack-pay large">
<div class="xrpblack-pay xlarge">

Trigger payment

You will need to first create a new payment on the server. USe the API /api/payments to create a payment. Once you have initialized, the "Pay with XRP" button is rendered for class xrpblack-pay

Never create payments on the client, as this will expose your security key

You can then initialise the xrpblack object as follows:

xrpblack.initialize({
    hash: "...",
    accesskey: "...",
    buttontheme: "DARK",
    callbackurl: "https://xrpblack.stmz.in/test/"
});

hash is the payment hash returned when you created the payment on the server-side

accesskey is the payment accesskey returned when you created the payment on the server-side

buttontheme can either be "DARK" or "NORMAL"

callbackurl is the URL to return to when payment is completed. When this happens, the querystring will return "result" and "h" for hash. Avoid HTML/URL encoding this text, the library will do this upon submission.

Below is an example return when payment is completed:

https://yourdomain.com/yourweborapi?result=SUCCESS&h=63D0EF1F43CF826E96598600C781998F56F50463D49E614EEE13FD492E50D32F

API documentation

Before you begin

All APIs are written as RESTful. All POST and response data is in JSON format

When you registered, you were given a secretkey. This is different from your XRPL wallet secret

We will never ask for your XRPL wallet secret key, and you should always keep that secret and private.

To avoid suspension of your wallet, please ensure you:

Avoid flooding the servers with requests, throttle limits are in place
Do not perform any load testing, this will result in automatic suspension
Always trigger payments on the client, this is because IP addresses are registered and throttling is enforced.
It is strongly recommended that you use the client libraries for client-side API calls.

Never do API calls that require your API secretkey to be available publically. These API calls must be run on the server side

API basics

All APIs are RESTful and use the HTTPS protocol. APIs do not enforce CORs so you can safely use them in browsers.

The common response format for API calls is as follows:

{
    "result": "OK",
    "description": "Payment status returned successfully",
    "status": {
        ....
        }
    }
}

Response body properties:

Parameter	Description
result	API call status. A response of "OK" means the API action/command was successfully returned. It does not mean, for example, a payment is successful
description	provides a human-readable description of the API action/command execution. Any errors will be written to this property
status	JSON property returning any details relating to the API call, e.g. payment status, payment trigger details

Note: All dates are returned in UTC date and time formats

Response Status Codes:

Status Code	Description
OK (200)	API call was successfuly
Bad Request (400)	Supplied information was invalid, or resulted in an invalid operation
Error (400)	The request resulted in an error. This is generally a server handled error
Not Found (404)	The resource was not found, e.g. payment or wallet
Queue Full (406)	The payment queue is full. This

Create a new payment

Create a new payment request. This should only be ran on the server-side

End-point and method: https://xrpblack.com/api/payment POST

Content-Type: application/json

Request Body (raw):

{
    "walletkey": "...",
    "securitykey": "...",
    "amount": 123.33,
    "symbol": "USD",
    "payload": {
        ...
        }
 }

Request body properties:

Parameter	Description
walletkey	Wallet key provided when you registered.
securitykey	Your wallet security key you used when you registered. This is not your XRPL wallet seed phrase. This is a secret and MUST never be visible by anyone.
amount	The amount of XRP that is required to be paid. Value must be between 0.02 and 1,000,000. The maximum number of decimal places is 4
symbol (optional)	The currency to covert from. If ommited, the amount specified will be XRP. Otherwise, the selected currency will be converted to XRP. Accepted currency symbols include: USD, AUD, GBP, EUR, JPY, CHF, CAD, ZAR, BRL, INR, IDR, OLS. This currency list may be expanded in future. Our conversion data is proudly powered by
payload	this can be any JSON structure that you choose and can be a maximum of 2KB in data. This payload is returned when you retreive the payment status. Refer below for example

Example with payment payload:

{
    "walletkey": "...",
    "securitykey": "...",
    "amount": 123.33,
    "symbol": "AUD",
    "payload": {
        "orderid": 4556123,
        "description":"Some description",
        "client_id": "ABC123"
        }
 }

Response body for successful payment creation:

{
    "result": "OK",
    "description": "Payment request created successfully",
    "status": {
        "hash": "75FCC6FBAEE84C1CE4840CD1F0D475D1CE40B173A023F4A8C9140A6C1FEAD4E4",
        "accesskey": "xT5J0j8fchFOiPIrkDQdB4BkKunaGtMb3dLx9XVhY2txKWIbPekMIR52tHuauCYs9qQRtcXnhX5NkVtwGg7Tl65ow2gIy7zo4hPn",
        "paymentstatus": "NEW",
        "amount": 2.3140,
        "amountformatted": 2.3140,
        "fromamount": 1.11,
        "symbol": "AUD",
        "fromamountformatted": "1.11 AUD",
        "transactionfeexrp": 0.0023140,
        "created": "2022-07-06T00:49:08.357"
    }
}

Response body properties:

You can also refere to payment status for additional details

Parameter	Description
hash, accesskey	Used when triggering payments or retreiving the payment status. It is SAFE to use this in client scripts.
paymentstatus	status of the payment created. Will generally be "NEW"
amount	Confirmed amount of XRP expected to be paid
amountformatted	Confirmed amount of XRP formatted
fromamount	The original amount as per symbol
symbol	The symbol of the original amount. Defaults to XRP if symbol is ommited
fromamountformatted	The original amount as per symbol, formatted.
transactionfeexrp	Transaction fee for the payment. This is deducted from the payment made by the user when sending payments to your account.
created	Date and time the transaction was created

Get payment status

Returns the payment status of a payment

End-point and method: https://xrpblack.com/api/payment/{hash} POST

Content-Type: application/json

Where:

hash is the payment hash that was generated wehen you created the payment

Response body for successful payment status return:

Properties will only be returned where there is a value. For example, if a payment is cancelled, receivedfrom won't be returned.

{
    "result": "OK",
    "description": "Payment status returned successfully",
    "status": {
        "hash": "E95EE360DF644A70C9762D5C9502E01C58CB36EB8DCD085853A9994BC08F7F4D",
        "paymentstatus": "SUCCESS",
        "receivedfrom": "rKe3CiVbaztiJsmbAYhNuCs5fvZ4sxr1nY",
        "xrplreceivehash": "B5773221028ADA5F360D30E909D72BEBDC872FCBF65CA30E6B249D785DBFA9D2",
        "xrplfinalhash": "1EF171FF8746A071187C07D186266C0F4CC151D720404DD3E999B30AA64D20D6",
        "amount": 1111.6110,
        "amountformatted": 1,111.6110,
        "symbol": "AUD",
        "fromamount": 0.30,
        "fromamountformatted": "0.30 AUD",
        "conversionrate": 0.4910,
        "created": "2022-06-23T03:55:44.243",
        "received": "2022-06-23T03:56:10.18",
        "finalised": "2022-06-23T03:56:14.94",
        "systemtime": "2022-06-24T05:55:35.147",
        "payload": {
            ...
            }
        }
}

Response body properties for "status":

Parameter	Description
hash	Payment hash
paymentstatus	Payment status. This can be either NEW, PENDING, SUCCESS, TIMEOUT, OR CANCELLED
receivedfrom	The XRPL wallet that made the XRP payment.
xrplreceivehash	XRPL transaction hash for the received payment. This hash can be searched on the XRPL public ledger
xrplfinalhalsh	XRPL transaction hash for the payment to the final wallet from the XRP\|BLACK interim wallet address. This hash can be searched on the XRPL public ledger
amount	Amount of XRP to be paid
amountformatted	Same as above, except formatted with number formatting
symbol	Original currency symbol used for the payment
fromamount	If symbol is not XRP, the original currency amount Will only be returned when symbol is not XRP.
fromamountformatted	As per above, except formatted number with symbol added. Will only be returned when symbol is not XRP.
conversionrate	Conversion rate used, i.e. currency amount for 1 XRP. Will only be returned when symbol is not XRP.
created	Date/time payment was created
created	Date/time payment expires. The expiry time is set when the payment is triggered by the client during payment
received	Date/time payment was received from the user
finalised	Date/time payment was finalised, which is when the final payment is transferred to the target wallet
systemtime	Date/time of the system. This is useful when calculating time remaining to expiry
payload	The JSON payload that was submitted when the payment was created