master

Welcome to the SpankPay SDK!

Get paid with crypto!

Overview

The SpankPay Merchant SDK makes it easy to get paid with cryptocurrency: easy for your users, and easy for you (the developer).

Getting started with SpankPay is a simple three-step process:

1. Include the SpankPay JavaScript

Add the following line to the bottom of the page on which you will be accepting payments:

<script src="https://pay.spankchain.com/spankpay.js"></script>

2. Add a Pay with SpankPay button

Add the following code to create a button which will start a SpankPay payment. Alternatively, you can call the JavaScript API directly.

<button
    data-spankpay-key="test_quickstart_key"
    data-amount="69.69"
    data-currency="USD"
    data-accept-currencies="BOOTY,ETH,BTC,DOGE"
    data-callback="https://pay.spankchain.com/api/quickstart/callback"
    data-on-payment="onSpankPayPayment">
  Pay with SpankPay!
</button>

<script>
function onSpankPayPayment(payment) {
    console.log(`Payment ${payment.status}:`, payment)
}
</script>

Want more control? SpankPay comes with a complete JavaScript API to give you full control of the payment process.

3. Generate an API key and write a Webhook endpoint

After you've evaluated SpankPay and would like to fully integrate it with your site, you will need to sign up for an account, create testing + production API keys, and implement a webhook endpoint which SpankPay will use to notify your application on a successful payment. This is covered in detail in Webhook Callbacks.

Integrating SpankPay

1. Include the SpankPay JavaScript

The first step in integrating SpankPay into your website is including the SpankPay JavaScript. This can be done directly with a <script> tag:

<script src="https://pay.spankchain.com/spankpay.js"></script>

Or via npm:

$ npm install --save spankpay

See SpankPay APIs for complete API documentation for the spankpay.js library.

2. Create a Purchase

In SpankPay, a Purchase is used to request payment from a user. Purchases can be created through either a SpankPay Button.

<button
    data-spankpay-key="test_quickstart_key"
    data-amount="69.69"
    data-currency="USD"
    data-accept-currencies="BOOTY,ETH,BTC,DOGE"
    data-callback="https://pay.spankchain.com/api/quickstart/callback"
    data-on-payment="onSpankPayPayment">
  Pay with SpankPay!
</button>

Which will show the SpankPay payment page when the Pay with SpankPay! button is clicked, and call the onSpankPayPayment callback once the payment has been completed and the webhook callback has been called.

Or via the SpankPay.showPurchase(...) method:

const { SpankPay } = require('spankpay')

SpankPay.showPurchase({
    key: 'test_quickstart_key',
    amount: '69.69',
    currency: 'USD',
    acceptCurrencies: ['BOOTY', 'ETH', 'BTC', 'DOGE'],
    callback: 'https://pay.spankchain.com/api/quickstart/callback',
    onPayment: function(payment) {
        console.log(`Payment ${payment.status}`, payment)
    },
})

And For a complete description of each of these methods, including their different options, see the Purchase API.

3. Implement a Webhook Callback URL

When SpankPay receives confirmation of a user's payment, it will call the callback webhook URL with a Payment to notify your application that the payment was completed successfully.

POST /api/quickstart/callback
Content-Type: text/plain
X-SpankPay-Key: test_quickstart_key
X-SpankPay-Signature: t=1551389518&s=b613679a0814d9ec…

{
    "type": "payment",
    "paymentId": "pay_c493715653c",
    "timestamp": "1969-06-09T06:09:06.969Z",
    "purchaseId": "pur_f95d778c35f",
    "purchase": { ... },
    "amount": "69.69",
    "amountCurrency": "USD",
    "inputAmount": "0.6969",
    "inputCurrency": "ETH",
    "inputTx": "0x2144292c5ad…",
    "receipt": {
        "type": "webhook",
        "url": "https://yoursite.com/yourserver/callback",
        "status": "called",
        "calledOn": "1969-06-09T06:09:06.969Z",
        "responseStatusCode": 200,
        "response": ...,
        ...
    }
    ...
}

For more, see:

4. Testing Your Integration

Testing API Keys

Every API key has a corresponding "testing" key. This testing key shares common settings (such as accepted coins) with the main key, but the currency list in the Purchase iframe will also include the option to pay with "test" versions of each coin.

When a test coin is selected, the user will be presented with a "send fake payment" button, which will immediately simulate a payment with that coin.

Test payments are identical to real payments, except the currencies will be prefixed with "TEST":

{
    "amount": "69.69",
    "amountCurrency": "TEST-USD",
    "inputAmount": "0.6969",
    "inputCurrency": "TEST-ETH",
    ...
}

Note that the testing API key also uses a different secret key.

We recommend using the testing key in your development and staging environments.

Testing Webhooks

For more details on effectively testing webhooks during development, see: Testing Webhooks.

NextSpankPay APIs

Last updated