Shell Python Node PHP C# Ruby

Payload.js Checkout

Payload.js exposes a simple drop-in Checkout interface with a robust javascipt API for web and mobile web integrations.

Example

Below is a simple example of Payload Checkout. Click Pay Now to view.

Pay Now Button

<form action="/submit_payment" method="POST">
  <script src="https://payload.co/Payload.js"
    pl-client-key="client_key_AWcpDnNBB7oLfNqfQ6g66262"
    pl-amount="100.00"
    pl-description="Membership">
  </script>
</form>

Step 1) Script Tag

Use the script tag to embed a Pay Now button into your form. This will open an instance of Payload Checkout to accept a new payment.

Step 2) Form Submit

Once a payment is confirmed, a hidden input, <input type="hidden" name="pl_transaction_id" value="{id}">, is added to the form element and then Payload.js automatically submits the form.

Step 3) Server Confirmation

pl_transaction_id = 'txn_19QsDurdSxJ0gVNzOcQSlew3D'
curl "https://api.payload.co/transactions/$pl_transaction_id" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -X PUT \
    -d status=processed
import payload as pl
pl.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'

@server.route('/submit_payment', method='post')
def post_transaction(pl_transaction_id):
    pl.Transaction(id=pl_transaction_id)\
        .update(status='processed')
require 'payload'
Payload.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'

post '/submit_payment/' do
    pl_transaction_id = params[:pl_transaction_id]

    transaction = Payload::Transaction.get(
        pl_transaction_id,
        update: { 'status' => 'processed' }
    )
end
<?php
pl::$api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE';

$pl_transaction_id = $_GET['pl_transaction_id'];

$transaction = Payload\Transaction::filter_by(
        pl::attr()->id->eq(pl_transaction_id)
    )->update(array( 'status' => 'processed' ));
?>
var pl = require('payload-api')
pl.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'

app.post('/submit_payment', (req, res) => {
    var pl_transaction_id = req.body.pl_transaction_id
    pl.Transaction({ id: pl_transaction_id })
        .update({ status: 'processed' })
        .then(function() {
            res.send('Payment Successful!')
        })
})
pl.api_key = "secret_key_3bW9JMZtPVDOfFNzwRdfE";

string pl_transaction_id = "txn_19QsDurdSxJ0gVNzOcQSlew3D";

new pl.Payment(new{
    id=pl_transaction_id
}).update(new { status="processed" });

On the server side, if you've enabled "Two-step authorization" in your API Key settings, you must confirm the transaction.

The transaction has only been authorized at this point. To confirm the transaction you need to update the status from authorized to processed as seen in the example.


JavaScript Interface

Step 1) Open via JavaScript

<script src="https://payload.co/Payload.js"></script>

<script>
Payload('client_key_AWcpDnNBB7oLfNqfQ6g66262');

var checkout = new Payload.Checkout({
    amount: 1000.0,
    description: "Example Payment"
})
</script>

Payload Checkout can be opened using the javascript interface by creating a new instance of Payload.Checkout, as seen in the example.

You can have Payload Checkout automatically submit a form after a successful payment by passing the form element as the form parameter when creating the checkout instance.


Step 2) Watch for Callback

<script>
checkout.on('processed', function(evt) {
    $.post('/submit_payment',
        { pl_transaction_id: evt.transaction_id })
})
</script>

When using the JavaScript interface and Checkout is not embedded within a form, you can watch for the processed callback to receive the transaction id.

Once you receive the transaction id you will need to send that to the server using an asynchronous request or trigger your own form submission.

Step 3) Server Confirmation

pl_transaction_id = 'txn_19QsDurdSxJ0gVNzOcQSlew3D'
curl "https://api.payload.co/transactions/$pl_transaction_id" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -X PUT \
    -d status=processed
import payload as pl
pl.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'

@server.route('/submit_payment', method='post')
def post_transaction(pl_transaction_id):
    pl.Transaction(id=pl_transaction_id)\
        .update(status='processed')
require 'payload'
Payload.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'

post '/submit_payment/' do
    pl_transaction_id = params[:pl_transaction_id]

    transaction = Payload::Payment.get(
        pl_transaction_id,
        update: { 'status' => 'processed' }
    )
end
<?php
Payload\Payload::$api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE';

$pl_transaction_id = $_GET['pl_transaction_id'];


$transaction = Payload\Transaction::filter_by(
        pl::attr()->id->eq(pl_transaction_id)
    )->update(array( 'status' => 'processed' ));
);
?>
var pl = require('payload-api')
pl.api_key = 'secret_key_3bW9JMZtPVDOfFNzwRdfE'

app.post('/submit_payment', (req, res) => {
    var pl_transaction_id = req.body.pl_transaction_id
    pl.Payment({ id: pl_transaction_id })
        .update({ status: 'processed' })
        .then(function() {
            res.send('Payment Successful!')
        })
})
pl.api_key = "secret_key_3bW9JMZtPVDOfFNzwRdfE";

string pl_transaction_id = "txn_19QsDurdSxJ0gVNzOcQSlew3D";

new pl.Payment(new{
    id=pl_transaction_id
}).update(new { status="processed" });

On the server side, if you've enabled "Two-step authorization" in your API Key settings, you must confirm the pl_transaction_id using the transactions api.

The transaction has only been authorized at this point. To confirm the transaction you need to update the status from authorized to processed as seen in the example.


JavaScript Callbacks

<script>
Payload.on( '.checkout-btn', 'processed', function(evt) {
    console.log('handle event')
})
</script>

Payload Checkout has different JavaScript events that you can watch for. To watch for an event on a Payload Button, you can pass either the element or a css selector as the first parameter.

Event Description
loaded Event triggered after the form has been successfully completed
processed Event triggered after a payment has been processed successfully
declined Event triggered if a payment attempt was declined *
closed Event triggered after the form has been closed

Note:"Raise Declined Error" must be disabled on an API Key to trigger a declined event


Custom Styling

<script>
const checkout = new Payload.Checkout({
    amount: 1000.0,
    description: "Example Payment",
    style: {
        'default': {
            primaryColor: '#ff00ff',
            backgroundColor: '#ffffff',
            color: '#000000',
            input: {
                borderColor: '#efefef',
                boxShadow: 'none',
            },
            header: {
                backgroundColor: '#eeccff',
            },
            button: {
                boxShadow: 'none',
            }
        }
    }
})
</script>

The checkout plugin accepts a style option. The default style accepts the following options:

CSS Style Description
primaryColor Hex color code to override the primary color.
backgroundColor Hex color code to override the plugin background.
color Hex color code to override the standard text color.
input.borderColor Hex color code to override the input border color.
input.boxShadow Override the input box shadow css rule.
header.backgroundColor Hex color code to override the modal header background color.
header.color Hex color code to override the modal header text color.
button.boxShadow Override the button shadow css rule.
button.color Hex color code to override the button text color.

Checkout Configuration

Script Tag Attributes

Attributes Description
pl-client-key
required
Your client key.
pl-amount
required without invoice-id
The payment amount.
pl-amount-editable
optional
Allow custom amounts.
pl-description
required without invoice-id
A description of the payment.
pl-order-number If you have a specific order number, include it to reference the transaction later.
pl-processing-id The processing account id for the payment.
pl-customer-id Load an existing customer's account settings. See the Customers section for more information.
pl-card-payments
default: true
Specifies if payments via card are accepted.
pl-bank-account-payments
default: false
Specifies if payments via bank account are accepted.
pl-billing-address Use true or false to specify whether billing address fields are displayed. Default is false.
pl-email The customer's email address, if available.
pl-name The customer's name, if available.
pl-invoice-id To tie the resulting payment to an invoice, pass the invoice id value.
pl-auto-billing-toggle Adds an option to allow the customer to set the payment method as the billing default.
pl-conv-fee Use true or false to specify whether the fee should be charged as a convenience.
pl-attrs Transaction custom attributes JSON object. Example: data-attrs='{"example":"data"}'
pl-status Set to authorized for a pre-auth payment.
pl-btn-class CSS class to apply to the button.
pl-btn-text Display text for the button.
pl-type
default: popup-btn
Choose between popup-btn and inline.

JavaScript Attributes

Attributes Description
key
required
Your client key.
amount
required without invoice id
The payment amount.
description
required
A description of the payment.
amount_editable
optional
Allow custom amounts.
processing_id
optional
The processing account id for the payment.
customer_id
optional
The customer's account id.
card_payments
default: true
Specifies if payments via card are accepted.
bank_account_payments
default: false
Specifies if payments via bank account are accepted.
billing_address Use true or false to specify whether billing address fields are displayed. Default is false.
email The customer's email address, if available.
full_name The customer's full name, if available.
invoice_id To tie the resulting payment to an invoice, pass the invoice id value.
auto_billing_toggle Adds an option to allow the customer to set the payment method as the billing default.
attrs Transaction custom attributes JSON object. Example: {"example":"data"}
status Set to authorized for a pre-auth payment.
conv_fee Use true or false to specify whether the fee should be charged as a convenience.
inline An html element to embed the interface instead of a popup.
form If present, following a successful payment the form will be submitted with the pl_transaction_id parameter.
autosubmit Set to false to disable automatic form submit