NAV Navbar
Logo

Online Checkout Tutorial

Payload’s flexible API and robust out-of-the-box features make integrating payments into your e-commerce site easy.

How Does it Work

Get Started

If you don’t already have at least one dedicated Processing Account for your business, you’ll need to set one up, otherwise jump to Checkout.

Adding a Processing Account

Add a Processing Account

<script src="https://payload.co/Payload.js"
  pl-client-key="client_key_AWcpDnNBB7oLfNqfQ6g66262"
  pl-btn-open="processing-account">
</script>
<script>
var pl = Payload('client_key_AWcpDnNBB7oLfNqfQ6g66262')
new pl.ProcessingAccount()
    .on('account_created', function(evt) {
        console.log(evt.account)
    })
</script>

Response

{}

Every payment needs to be associated with an active Processing Account to process. Processing Accounts specify the pricing and settings for how payments should be processed, including what funding account to transmit the payment to.

Processing Accounts can be added through the dashboard or the full setup process can be integrated into your platform using the Integrated Processing Account Setup toolkit.

To integrate the processing account setup into your app or platform, you can use the Processing Account UI toolkit to capture the details for a new processing account.

Below is an example of the Processing Account form. Click the button to view.


Checkout

Payload Checkout is a UI toolkit for integrating simple payment acceptance into your portal or platform. Below are a few of built-in the benefits of accepting payments using the checkout toolkit.

If your platform has recurring customers, you can create Customer accounts and store your customers’ payment information and settings for faster checkout.

To create test transactions you can use dummy card numbers as long as they fit a valid format. For some samples:

Card Type Samples
Visa 4242 4242 4242 4242
MasterCard 5103 2088 7967 2792
American Express 3672 005140 64164
Discover 6011 9102 7504 5718

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 = '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')
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!')
        })
})

On the server side, you must confirm the pl_transaction_id.

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>
var pl = Payload('client_key_AWcpDnNBB7oLfNqfQ6g66262')
var checkout = new pl.Checkout({
    amount: 1000.0,
    description: "Example Payment"
})
</script>

Processed Event

{}

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.

If you enter a payment, you’ll see the processed event from the Javascript callback on the right.


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 not 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 submit.


Step 3) Server Confirmation

pl_transaction_id = '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')
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!')
        })
})

On the server side, 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

For a full list of all the ways Payload Checkout can be configured, see the Checkout Configuration section of the documentation.


Customers

You can accept one-time payments without storing customer information, or use the Customer Account object to save customer data for a quicker checkout process.

Step 1) Add a Customer

Create a New Customer

curl "https://api.payload.co/accounts/" \
  -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
  -d email="matt.perez@example.com" \
  -d full_name="Matt Perez" \
  -d primary_processing_id="processing_account_id" \
  -d phone_number="1234567890" \
  -d type="customer"
account = pl.Customer.create(
    full_name='Full name',
    email='email@example.com',
    phone_number='(111) 111-1111',
    attrs={
      "custom_attribute": "Custom input"
    },
    primary_processing_id='processing_account_id'
)
pl.Customer.create({
    full_name: 'Full name',
    email: 'email@example.com',
    phone_number: '(111) 111-1111',
    attrs: {
      "custom_attribute": "Custom input"
    },
    primary_processing_id: 'processing_account_id'
}).then(function(account) {
    // Handle account creation
})

Response

{}

Create a new Customer using one of Payload’s SDKs. Below is a simple example of a customer onboarding form, with corresponding code snippets on the right.


Step 2) Add Payment Methods

Add Payment Methods

pl.PaymentMethod.create({
    type: card,
    card: {
      card_number: "numeric",
      expiry: "mm/yy"
    },
    account_id: customer_id
}).then(function(card){
  // Handle card creation
})
payment = pl.PaymentMethod.create(
    type='card',
    card={
      'card_number': 'numeric',
      'expiry': 'mm/yy'
    },
    account_id='customer_id'
)
curl https://api.payload.co/payment_methods \
  --header "Content-Type: application/json" \
  -u test_client_key_3bW9JMZtPVDOfFNzwRdfE: \
  -d '{"type":"card","card":{"card_number":"numeric", "expiry":"mm/yy"},"account_id":"customer_id"}'

Response

{}

Secure Input Form Example (Bootstrap 4)

<form id="checkout-form" class="container" pl-form="payment">
    <input type="hidden" pl-input="amount" value="10.00">
    <div class="row pt-2">
        <div class="form-group col-7 px-1">
            <label>Card Number</label>
            <div class="form-control" pl-input="card_number"></div>
        </div>
        <div class="form-group col-3 px-1">
            <label>Expiration</label>
            <div class="form-control" pl-input="expiry"></div>
        </div>
        <div class="form-group col-2 px-1">
            <label>CVC</label>
            <div class="form-control" pl-input="cvc"></div>
        </div>
    </div>
    <div class="row pt-2">
        <button class="btn btn-primary" type="submit">Pay Now</button>
    </div>
</form>

Import Payload

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

Initialize the Form

<script>
  var pl = Payload('UPDATE WITH YOUR test_client_key_....')

  var checkout_form = new pl.Form({
      form: $('#checkout-form').get(0)
  })
</script>

Once the Customer account has been created, you can add Payment Methods programmatically, or use Payload’s Secure Input feature to securely capture card or bank account information from any HTML form.

Cards

Bank Accounts


One-Click Checkout

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

<script>
  var pl = Payload('client_key_AWcpDnNBB7oLfNqfQ6g66262')
  var checkout = new pl.Checkout({
    amount: 1000.0,
    description: "Example Payment",
    customer_id: "3bvM06IcMoIklRmC8yfmy"
  })
</script>

Now that you have customers, if your pass a customer_id in when you create your checkout button, their payment information will automatically populate.


Object Reference